Create a load balancer

A load balancer answers A and AAAA queries for one hostname in the zone from your origin pools. Create one when a name should resolve to whichever of your servers is healthy, or to the servers nearest each client.

• Create at least one origin pool in the zone. New load balancer… is available once the zone has one.
• The hostname must have no A, AAAA or CNAME records. If it has some, create the pools first, then delete the records on the DNS tab just before you create the load balancer, so the name is without answers for as short a time as possible.

1. In the dashboard, go to Websites, open the domain and select the Load balancing tab.
2. Under Load balancers, select New load balancer….
3. Enter a Name for your own use, such as api-global.
4. Enter the Hostname: a name under the zone, such as api or eu.api, or @ for the domain itself. The hint under the field shows the full name the load balancer answers for.
5. Set the TTL (s), from 5 to 3,600 seconds. Resolvers ask again after this time, so a short TTL moves clients off an unhealthy origin sooner.
6. Choose the Session affinity: None, or By client IP to give each resolver the same origin while it stays healthy.
7. Choose the Steering, and for Geographic or Proximity, how to Locate the client by (Steering).
8. Under Default pools, select the pools in the order to try them. Each selected pool shows its place in the order; select it again to take it out.
9. Optionally, choose a Fallback pool to answer when no pool above has a healthy origin. The load balancer needs at least one default pool or a fallback pool.
10. For Geographic steering, add rules under By region, By country and By PoP. For each, select Add rule, choose the region or PoP, or type a two-letter country code such as DE, then select the rule's pools in order.
11. Select Create load balancer.

A Geographic load balancer uses the most specific rule that matches: PoP, then country, then region. A client that matches no rule gets the default pools.

Check what a client in a given place would get before you rely on the load balancer.

1. Open the load balancer's actions menu and select Preview answers.
2. Choose a Coritan PoP under From PoP, or leave it at Any (use resolver IP) and enter a resolver's address under Resolver IP.
3. Choose the Type, A or AAAA, and select Preview answer.

The panel shows the Answer, which pool and rule chose it under Chosen by, the Pool order steering produced, and where Coritan placed the client under Client seen as. The preview uses the origins' current health. Select Hide preview in the menu to close it.

• To change it, open its actions menu, select Edit load balancer…, make the change and select Save load balancer.
• To stop it answering, turn off its Enabled switch in the table, or Load balancer enabled in its dialog. While it is off, the name gets no A or AAAA answers.
• To delete it, open its actions menu, select Delete load balancer…, type its full hostname, such as api.example.com, and select Delete load balancer.

The dashboard confirms Load balancer api.example.com created., and the load balancer appears under Load balancers with its Steering and Pools. Ask a Coritan nameserver from a terminal; each answer holds one origin's address:

dig @ns1.coritan.com api.example.com A +short

Hostname already has A/AAAA/CNAME records; remove them before creating a load balancer

Delete the name's A, AAAA and CNAME records on the DNS tab, then create the load balancer.

A load balancer already owns this hostname

Another load balancer in the zone answers for that name. Edit it instead, or choose another hostname.

Choose at least one default pool or a fallback pool.

Select a pool under Default pools, or choose a Fallback pool.

Enter a label under the zone, such as api or eu.api, or @ for the apex.

Enter the hostname relative to the zone, without the domain: api for api.example.com.

Add a pool to the country rule for DE.

Every rule needs at least one pool. Select one in the rule, or remove the rule.

Load balancer limit reached (50) or Steering entry limit reached (200)

A zone holds up to 50 load balancers, and a load balancer up to 200 pool entries across its default pools and rules.

The preview shows No answer · no members

No pool in the order has an enabled origin of the type you asked for. An AAAA query needs IPv6 origins.

The preview shows No answer · load balancer disabled

The load balancer is off. Turn it on in the table.

The page warns Proximity steering needs a location on every pool

A pool without a Primary location cannot be ranked by distance, so it answers only when no closer pool can. Set one on each pool.

• How DNS load balancing works
• Create an origin pool
• Load balancing reference

Create a load balancer in zone 42 from pools 7 and 8, with pool 9 as the fallback. hostname is relative to the zone, and the default pools are tried in the order you list them:

curl -X POST https://api.coritan.com/api/v1/dns/zones/42/load-balancers \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-global",
    "hostname": "api",
    "ttl": 30,
    "steering_policy": "geo",
    "location_strategy": "pop",
    "default_pools": [7, 8],
    "fallback_pool_id": 9,
    "region_pools": {"WEU": [7], "ENAM": [8]},
    "country_pools": {"DE": [7]}
  }'

The answer is 201 with the load balancer:

{
  "id": 5,
  "zone_id": 42,
  "name": "api-global",
  "hostname": "api",
  "enabled": true,
  "ttl": 30,
  "session_affinity": "none",
  "steering_policy": "geo",
  "location_strategy": "pop",
  "fallback_pool_id": 9,
  "default_pools": [7, 8],
  "location_pools": {},
  "country_pools": {"DE": [7]},
  "region_pools": {"WEU": [7], "ENAM": [8]},
  "created_at": "2026-09-25T09:30:00Z",
  "updated_at": "2026-09-25T09:30:00Z"
}

Region codes are listed in the reference. Country codes are two-letter ISO codes, and PoP codes are the location codes the From PoP list shows.

List a zone's load balancers with GET /api/v1/dns/zones/42/load-balancers, sorted by hostname, and read one with GET /api/v1/dns/zones/42/load-balancers/5. PATCH changes the fields you send; a list or map you send, such as default_pools or country_pools, replaces the old one whole. DELETE answers 204.

Preview an answer. Send from_location with a PoP code, or from_ip with a resolver's address, and qtype:

curl -X POST https://api.coritan.com/api/v1/dns/zones/42/load-balancers/5/preview \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"qtype": "A", "from_ip": "198.51.100.53"}'

{
  "load_balancer_id": 5,
  "hostname": "api",
  "context": {"location_code": null, "country_code": "DE", "region_code": "WEU", "latitude": null, "longitude": null, "source": "resolver_ip"},
  "pool_order": [7],
  "cascade_hit": "country",
  "selected_pool_id": 7,
  "member": {"id": 31, "pool_id": 7, "address": "203.0.113.10", "address_type": "A", "weight": 10, "priority": 0, "enabled": true, "health_status": "healthy"},
  "servfail": false,
  "reason": "ok"
}

member is the origin chosen, with the fields of an origin in its pool (the example leaves some out), or null when there is no answer. The reference lists the values of cascade_hit and reason.