external-dns/docs/advanced/ttl.md
Ivan Ka 17fa4b4e7a
feat(source): support ttl annotation on pod (#5527)
* feat(source/pod): add support ttl annotation

Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com>

* feat(source/pod): add support ttl annotation

Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com>

---------

Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com>
2025-06-19 21:50:51 -07:00

221 lines
6.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.:
```yaml
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](https://golang.org/pkg/time/#ParseDuration):
```yaml
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
```yaml
annotations:
external-dns.alpha.kubernetes.io/ttl: "30s"
```
---
### Long TTL for Static Services
If your services 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
```yml
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.