INTEGRITY Cloudflare Docs

← Load Balancing / load-balancing / additional-options

CNAME flattening for endpoints

When a DNS-only (gray-clouded) load balancer selects an endpoint whose address is a hostname (for example origin.example.com), Cloudflare resolves that hostname to an IP address and returns an A/AAAA record to the client. This is CNAME flattening, and it matches how CNAME flattening works in Cloudflare DNS.

Some use cases — such as third-party endpoints that perform their own DNS-based steering — require the load balancer to return the CNAME record itself instead of a resolved IP. The flatten_cname property on a pool endpoint lets you opt out of flattening on a per-endpoint basis.

When to use this

Turn flatten_cname off (flatten_cname: false) on an endpoint when:

Leave flatten_cname on (flatten_cname: true, the default) for normal IP-based or hostname endpoints where you just want a fast A/AAAA answer.

Where it applies

flatten_cname only changes resolver output when all of the following are true:

Condition Required value
Load balancer proxy mode DNS-only (gray-clouded). Proxied load balancers must return Cloudflare anycast IPs, so the setting is ignored.
Endpoint address A hostname (CNAME target). For raw IPv4/IPv6 endpoint addresses the setting has no effect.
Load balancer hostname Not the zone apex. CNAME records at a zone apex are not permitted, so the load balancer falls back to flattening at the apex.
The selected endpoint Steering selected this specific endpoint. Setting flatten_cname: false on endpoint A has no effect when steering picks endpoint B in the same pool.

If the selected endpoint has flatten_cname: false but any of the conditions in the preceding table is not met, the load balancer flattens the CNAME and returns A/AAAA records as if the toggle were on.

Configure CNAME flattening

flatten_cname is configured per endpoint inside a pool, alongside name, address, weight, and other endpoint fields. You can set it in the Cloudflare dashboard, the API, or Terraform.

In the dashboard, this setting appears as a Flatten CNAME toggle on each endpoint in a pool. Turn the toggle off to return the endpoint hostname as a CNAME record.

  1. In the Cloudflare dashboard, go to the Load Balancing page.

    Go to Load Balancing ↗

  2. Select the Pools tab.

  3. On the pool that contains the endpoint, select Edit.

  4. In the Endpoints section, find the endpoint you want to change.

  5. Turn Flatten CNAME off.

  6. Select Save.

Flatten CNAME is only available for endpoints whose address is a hostname. Endpoints that use an IP address cannot turn it off.

Use Create Pool or Edit Pool and set flatten_cname on each endpoint in the origins array.

Required API token permissions

At least one of the following token permissions is required:
  • Load Balancing: Monitors and Pools Write
Create Pool
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/load_balancers/pools" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"name": "primary-pool",
		"origins": [
				{
						"name": "origin-a",
						"address": "origin-a.example.com",
						"enabled": true,
						"weight": 1,
						"flatten_cname": false
				},
				{
						"name": "origin-b",
						"address": "origin-b.example.com",
						"enabled": true,
						"weight": 1,
						"flatten_cname": false
				},
				{
						"name": "fallback-ip",
						"address": "203.0.113.10",
						"enabled": true,
						"weight": 1
				}
		]
	}'

flatten_cname defaults to true when omitted, preserving today's behavior for existing pools and endpoints.

Set the attribute on each endpoint inside a cloudflare_load_balancer_pool resource.

resource "cloudflare_load_balancer_pool" "primary" {
  account_id = var.account_id
  name       = "primary-pool"

  origins = [
    {
      name          = "origin-a"
      address       = "origin-a.example.com"
      enabled       = true
      weight        = 1
      flatten_cname = false
    },
    {
      name          = "origin-b"
      address       = "origin-b.example.com"
      enabled       = true
      weight        = 1
      flatten_cname = false
    },
    {
      name    = "fallback-ip"
      address = "203.0.113.10"
      enabled = true
      weight  = 1
    }
  ]
}

Verify

Query the load balancer hostname with dig:

dig lb.example.com A +short

Because the answer depends on which endpoint steering selects, repeated dig queries against the same load balancer can legitimately alternate between CNAME and A/AAAA answers when a pool mixes hostname endpoints with flatten_cname: false and IP endpoints.

Health monitors

Endpoint health monitors are unaffected by this setting. Cloudflare always resolves the endpoint hostname to an IP and probes the underlying service using an uncached DNS lookup. Turning off flattening only changes what is returned to the client at DNS query time — health status continues to reflect the real backend reachability.

Analytics

Per-endpoint request counts and steering decisions remain visible in load balancing analytics, keyed by endpoint name. This lets you track how traffic is distributed across CNAME-returning endpoints.

Limitations