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.

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

• You want clients to receive a CNAME answer pointing at a third-party SaaS provider or cloud endpoint (for example origin-b.example.com).
• The endpoint resolves to addresses that are dynamic, geo-aware, or client-aware downstream.
• You are failing over between two hostname endpoints and want the client to resolve each provider's hostname directly.

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.

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

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.

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.

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
				}
		]
	}'

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
    }
  ]
}

Query the load balancer hostname with dig:

dig lb.example.com A +short

• If steering selected an endpoint where flatten_cname is false, the answer section contains a CNAME record pointing at the endpoint address (for example, origin-a.example.com.). The client (or its resolver) is responsible for resolving that CNAME further.
• If steering selected an endpoint where flatten_cname is true (or an endpoint whose address is an IP), the answer contains the resolved A/AAAA records.

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.

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.

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.

• Proxied (orange-clouded) load balancers: flatten_cname is ignored. Proxied load balancers must resolve to Cloudflare anycast IPs to deliver Cloudflare's HTTP/HTTPS proxy features.
• Zone apex load balancers: flatten_cname is ignored because CNAME records are not permitted at a zone apex.
• IP endpoints: flatten_cname has no effect — there is no CNAME to flatten or return.
• DNS resolver caching: As with any DNS-only load balancer, downstream resolvers may cache the returned record for the TTL. Clients that ignore TTLs may continue to use a previously cached CNAME or A answer.
• Plan requirement: Available to Enterprise customers on the Load Balancing add-on.

• DNS CNAME flattening — the equivalent feature for non-load-balancer DNS records.
• Proxy modes — when to use DNS-only versus proxied load balancing.
• Common configurations — patterns including active-active failover that benefit from CNAME-returning endpoints.