Available Annotations

Numerous annotations can be added to services advertised by External DNS to modify its behavior and the record metadata. Annotations are applied at a per-service level to influence records. This topic describes the annotations that you can add to the services advertised by External DNS.

Add Provider Agnostic Annotations

The provider agnostic annotation is independent of the DNS service provider. You can use this type of annotation with all the supported DNS providers.

Access

The annotation for access objects is external-dns.alpha.kubernetes.io/access. In a scenario where a service, ingress, or node has both a public and private IP address, you can specify which IP address you want External DNS to advertise. The two available arguments for this annotation are private and public.

If this argument is not set, the default is public to advertise the public IP address as illustrated in the following YAML file.

kind: Service
metadata:
  annotations:
    external-dns.alpha.kubernetes.io/hostname: sub.domain.tld
    external-dns.alpha.kubernetes.io/access: public

Endpoints Type

The annotation for access objects is external-dns.alpha.kubernetes.io/endpoints-type. This annotation is only applicable when advertising a headless service with External DNS.

If you are advertising a headless service with External DNS, you can use this annotation to specify whether the pod IP addresses or the node's external IP address should be advertised. The available arguments are HostIP and NodeExternalIP.

apiVersion: v1
kind: Service
metadata:
  annotations:
    external-dns.alpha.kubernetes.io/hostname: sub.domain.tld
    external-dns.alpha.kubernetes.io/endpoints-type: NodeExternalIP

Hostname

The annotation for access objects is external-dns.alpha.kubernetes.io/hostname.

Single Hostname

Adding the hostname annotation to your service tells External DNS that it is a service you want to advertise. Define a hostname for your service as shown below.

apiVersion: v1
kind: Service
metadata:
  annotations:
    external-dns.alpha.kubernetes.io/hostname: sub.domain.tld

Multiple Hostnames

If you want to advertise a service on multiple different hostnames, you would delineate them with, use an annotation as shown below.

apiVersion: v1
kind: Service
metadata:
  annotations:
    external-dns.alpha.kubernetes.io/hostname: sub.domain.tld,sub2.domain.tld,sub3.domain.tld

Ingress Hostname Source

The annotation for access objects is external-dns.alpha.kubernetes.io/access. This annotation is applicable only when advertising an ingress with External DNS.

Ingresses have three methods of notifying External DNS they need to be advertised. These include a host defined in either spec.rules.host or annotated with external-dns.alpha.kubernetes.io/hostname.

The following annotation allows specifying External DNS that only advertises hostnames from either the spec.rules.host field or the hostname annotation. The two valid arguments are defined-hosts-only and annotation-only.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    external-dns.alpha.kubernetes.io/hostname: sub.domain.tld
    external-dns.alpha.kubernetes.io/ingress-hostname-source: annotation-only

Internal Hostname

The annotation for access objects is external-dns.alpha.kubernetes.io/access. If you want to advertise the service IP address rather than the public LoadBalancer IP address, you can specify a hostname using this annotation. For example, use this annotation when you want a hostname for use for communication within a cluster.

apiVersion: v1
kind: Service
metadata:
  annotations:
    external-dns.alpha.kubernetes.io/internal-hostname: sub.domain.tld

As with the standard external-dns.alpha.kubernetes.io/hostname annotation, you may specify multiple hostnames by using a comma (,) delineator.

Target

The annotation for access objects is external-dns.alpha.kubernetes.io/access. This is applicable only when advertising an ingress with External DNS.

If you want to manually specify IP target(s) to be advertised by External DNS, add the below annotation to Ingresses.

Single Target

Use the following annotation with a single target.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    external-dns.alpha.kubernetes.io/hostname: sub.domain.tld
    external-dns.alpha.kubernetes.io/target: 12.34.56.78

Multiple Targets

To advertise multiple targets, separate IP addresses using comma (,) as a delineator.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    external-dns.alpha.kubernetes.io/hostname: sub.domain.tld
    external-dns.alpha.kubernetes.io/target: 12.34.56.78,90.12.34.56

Time to Live (TTL)

The annotation for access objects is external-dns.alpha.kubernetes.io/access. To specify a Time-to-Live (TTL) value other than the default for your designated DNS provider, set an annotation as shown below (time in seconds):

apiVersion: v1
kind: Service
metadata:
  annotations:
    external-dns.alpha.kubernetes.io/hostname: sub.domain.tld
    external-dns.alpha.kubernetes.io/ttl: "60"

Add Provider Specific Annotations

Currently, we support only the weight annotation as the provider specific annotations.

Weight

NS1 DNS provider supports this annotation.

If you want to add a weight value to your DNS record, add the following annotation with a required weight value.

apiVersion: v1
kind: Service
metadata:
  annotations:
    external-dns.alpha.kubernetes.io/hostname: sub.domain.tld
    external-dns.alpha.kubernetes.io/weight: "100"