Configure DNS record TTL (Time-To-Live)¶

An optional annotation external-dns.alpha.kubernetes.io/ttl is available to customize the TTL value of a DNS record.
TTL is specified as an integer encoded as string representing seconds.

To configure it, simply annotate a service/ingress, e.g.:

apiVersion: v1
kind: Service
metadata:
  annotations:
    external-dns.alpha.kubernetes.io/hostname: nginx.external-dns-test.my-org.com.
    external-dns.alpha.kubernetes.io/ttl: "60"
  ...

TTL can also be specified as a duration value parsable by Golang time.ParseDuration:

apiVersion: v1
kind: Service
metadata:
  annotations:
    external-dns.alpha.kubernetes.io/hostname: nginx.external-dns-test.my-org.com.
    external-dns.alpha.kubernetes.io/ttl: "1m"
  ...

Both examples result in the same value of 60 seconds TTL.

TTL must be a positive value.

TTL annotation support¶

Note: For TTL annotations to work, the external-dns.alpha.kubernetes.io/hostname annotation must be set on the resource and be supported by the provider as well as the source.

Providers¶

Provider	Supported
`Akamai`	✅
`AlibabaCloud`	✅
`AWS`	✅
`AWSSD`	✅
`Azure`	✅
`Civo`	❌
`Cloudflare`	✅
`CoreDNS`	❌
`DigitalOcean`	✅
`DNSSimple`	✅
`Exoscale`	✅
`Gandi`	✅
`GoDaddy`	✅
`Google GCP`	✅
`InMemory`	❌
`Linode`	❌
`NS1`	❌
`OCI`	✅
`OVH`	❌
`PDNS`	❌
`PiHole`	✅
`Plural`	❌
`RFC2136`	✅
`Scaleway`	✅
`Transip`	✅
`Webhook`	✅

Sources¶

Source	Supported
`ambassador-host`	✅
`cloudfoundry`	❌
`connector`	❌
`contour-httpproxy`	✅
`crd`	❌
`empty`	❌
`f5-transportserver`	✅
`f5-virtualserver`	✅
`fake`	❌
`gateway-grpcroute`	✅
`gateway-httproute`	✅
`gateway-tcproute`	✅
`gateway-tlsroute`	✅
`gateway-udproute`	✅
`gloo-proxy`	✅
`ingress`	✅
`istio-gateway`	✅
`istio-virtualservice`	✅
`kong-tcpingress`	✅
`node`	✅
`openshift-route`	✅
`pod`	✅
`service`	✅
`skipper-routegroup`	✅
`traefik-proxy`	✅

Notes¶

When the external-dns.alpha.kubernetes.io/ttl annotation is not provided, the TTL will default to 0 seconds and endpoint.TTL.isConfigured() will be false.

AWS Provider¶

The AWS Provider overrides the value to 300s when the TTL is 0.
This value is a constant in the provider code.

Azure¶

TTL value should be between 1 and 2,147,483,647 seconds.
By default it will be 300s.

CloudFlare Provider¶

CloudFlare overrides the value to “auto” when the TTL is 0.

DigitalOcean Provider¶

The DigitalOcean Provider overrides the value to 300s when the TTL is 0.
This value is a constant in the provider code.

DNSimple Provider¶

The DNSimple Provider default TTL is used when the TTL is 0. The default TTL is 3600s.

Google Provider¶

Previously with the Google Provider, TTL’s were hard-coded to 300s.
For safety, the Google Provider overrides the value to 300s when the TTL is 0.
This value is a constant in the provider code.

For the moment, it is impossible to use a TTL value of 0 with the AWS, DigitalOcean, or Google Providers.
This behavior may change in the future.

Linode Provider¶

The Linode Provider default TTL is used when the TTL is 0. The default is 24 hours

TransIP Provider¶

The TransIP Provider minimal TTL is used when the TTL is 0. The minimal TTL is 60s.

Use Cases for `external-dns.alpha.kubernetes.io/ttl` annotation¶

The external-dns.alpha.kubernetes.io/ttl annotation allows you to set a custom TTL (Time To Live) for DNS records managed by external-dns.

Use the external-dns.alpha.kubernetes.io/tt annotation to fine-tune DNS caching behavior per record, balancing between update frequency and performance.

This is useful in several real-world scenarios depending on how frequently DNS records are expected to change.

Fast Failover for Critical Services¶

For services that must be highly available—like APIs, databases, or external load balancers—set a low TTL (e.g., 30 seconds) so DNS clients quickly update to new IPs during:

Node failures
Region failovers
Blue/green deployments

annotations:
  external-dns.alpha.kubernetes.io/ttl: "30s"

Long TTL for Static Services¶

If your service’s IP or endpoint rarely changes (e.g., static websites, internal dashboards), you can set a long TTL (e.g., 86400 seconds = 24 hours) to:

Reduce DNS query load
Improve cache performance
Lower cost with some DNS providers

annotations:
  external-dns.alpha.kubernetes.io/ttl: "24h"

Canary or Experimental Services¶

Use a short TTL for services under test or experimentation to allow fast DNS propagation when making changes, allowing easy rollback and testing.

Provider-Specific Optimization¶

Some DNS providers charge per query or have query rate limits. Adjusting the TTL lets you:

Reduce costs
Avoid throttling
Manage DNS traffic load efficiently

Regulatory or Contractual SLAs¶

Certain environments may require TTL values to align with:

Regulatory guidelines
Legacy system compatibility
Contractual service-level agreements

Autoscaling Node Pools in GCP (or Other Cloud Providers)¶

In environments like Google Cloud Platform (GCP) using private node IPs for DNS resolution, ExternalDNS may register node IPs with a default TTL of 300 seconds.

During autoscaling events (e.g., node addition/removal or upgrades), DNS records may remain stale for several minutes, causing traffic to be routed to non-existent nodes.

By using the TTL annotation you can:

Reduce TTL to allow faster DNS propagation
Ensure quicker routing updates when node IPs change
Improve resiliency during frequent cluster topology changes
Fine-grained TTL control helps avoid downtime or misrouting in dynamic, autoscaling environments.