Routing: Geo Rules

Geo Rules

Geo rules allow you to steer specific source IP ranges to specific pool endpoints, overriding the pool's default load-balancing algorithm for those prefixes. Each rule maps a source CIDR block to a single endpoint address with an optional priority for tie-breaking.

Geo rules are evaluated per-query against the client IP resolved from the DNS request. If no geo rule matches, the pool falls back to its configured algorithm (round-robin, weighted, latency, etc.).

License: Geo rules require the pro tier or above. Create and update operations return HTTP 403 on lower tiers. Contact licensing@gslb.nexus to upgrade.

Model

Field	Type	Description
`id`	string	UUID assigned on creation
`poolId`	string	Pool this rule belongs to
`cidr`	string	Source CIDR to match (e.g. `203.0.113.0/24`, `2001:db8::/32`)
`endpoint`	string	IP address of the pool member to route matching requests to
`priority`	int	Tie-breaking priority — lower value = higher priority. Default `100`
`createdAt`	int64	Unix timestamp
`updatedAt`	int64	Unix timestamp

APIList geo rules for a pool

GET /api/v1/pools/{poolId}/georules

Response 200 OK: array of GeoRule objects.

[  {    "id": "a1b2c3...",    "poolId": "pool-uuid",    "cidr": "203.0.113.0/24",    "endpoint": "203.0.113.10",    "priority": 100,    "createdAt": 1716100000,    "updatedAt": 1716100000  }]

Create a geo rule

POST /api/v1/pools/{poolId}/georules

Field	Type	Required	Default	Description
`cidr`	string	yes	—	Source CIDR block
`endpoint`	string	yes	—	Pool member IP to route to
`priority`	int	no	`100`	Tie-breaking priority

Response 201 Created: the created GeoRule object.

curl -X POST https://nexus-api.example.com/api/v1/pools/$POOL_ID/georules \  -H "Authorization: Bearer $GSLB_API_KEY" \  -H "Content-Type: application/json" \  -d '{"cidr":"10.0.0.0/8","endpoint":"10.1.2.3","priority":10}'

Update a geo rule

PUT /api/v1/georules/{id}

Body fields: cidr, endpoint, priority (all required).

Response 200 OK: updated GeoRule object.

Delete a geo rule

DELETE /api/v1/georules/{id}

Response 204 No Content.

gslbctl

Geo rules are managed through the interactive TUI. Launch gslbctl and navigate to the pool, then press G to open the geo rules screen.

Key	Action
`n`	New rule
`e`	Edit selected rule
`d`	Delete selected rule
`esc`	Back to pool

Terraform

resource "nexus_geo_rule" "eu_office" {
  pool_id  = nexus_pool.web.id
  cidr     = "203.0.113.0/24"
  endpoint = "203.0.113.10"
  priority = 10
}

Attribute	Type	Required	Description
`pool_id`	string	yes	Pool to attach this rule to
`cidr`	string	yes	Source CIDR block
`endpoint`	string	yes	Pool member IP
`priority`	number	no	Tie-breaking priority (default `100`)

Behaviour notes

CIDR matching uses longest-prefix-match. A /32 rule takes precedence over a /24 rule for the same address regardless of priority.
Priority breaks ties when two rules have identical prefix lengths. Lower value wins.
No match falls back to the pool's algorithm (round-robin, weighted, latency, geo-ip, etc.).
IPv4-mapped IPv6 addresses (::ffff:0:0/96) are matched against their IPv4 representation.
Rules take effect immediately on create, update, and delete — no restart required.
Rules replicate to all cluster nodes via NATS state sync.