diff --git a/docs/annotations/annotations.md b/docs/annotations/annotations.md new file mode 100644 index 000000000..79957c139 --- /dev/null +++ b/docs/annotations/annotations.md @@ -0,0 +1,120 @@ +# Annotations + +ExternalDNS sources support a number of annotations on the Kubernetes resources that they examine. + +The following table documents which sources support which annotations: + +| Source | controller | hostname | internal-hostname | target | ttl | (provider-specific) | +|--------------|------------|----------|-------------------|---------|-----|---------------------| +| Ambassador | | | | | Yes | | +| Connector | | | | | | | +| Contour | Yes | Yes[^1] | | Yes | Yes | Yes | +| CloudFoundry | | | | | | | +| CRD | | | | | | | +| F5 | | | | | Yes | | +| Gateway | Yes | Yes[^1] | | | Yes | Yes | +| Gloo | | | | | Yes | Yes | +| Ingress | Yes | Yes[^1] | | Yes | Yes | Yes | +| Istio | Yes | Yes[^1] | | Yes | Yes | Yes | +| Kong | | Yes | | | Yes | Yes | +| Node | Yes | | | | Yes | | +| OpenShift | Yes | Yes[^1] | | Yes | Yes | Yes | +| Pod | | Yes | Yes | | | | +| Service | Yes | Yes[^1] | Yes[^1][^2] | Yes[^3] | Yes | Yes | +| Skipper | Yes | Yes[^1] | | Yes | Yes | Yes | +| Traefik | | Yes | | Yes | Yes | Yes | + +[^1]: Unless the `--ignore-hostname-annotation` flag is specified. +[^2]: Only behaves differently than `hostname` for `Service`s of type `LoadBalancer`. +[^3]: Also supported on `Pods` referenced from a headless `Service`'s `Endpoints`. + +## external-dns.alpha.kubernetes.io/access + +Specifies which set of node IP addresses to use for a `Service` of type `NodePort`. + +If the value is `public`, use the Nodes' addresses of type `ExternalIP`, plus IPv6 addresses of type `InternalIP`. + +If the value is `private`, use the Nodes' addresses of type `InternalIP`. + +If the annotation is not present and there is at least one address of type `ExternalIP`, +behave as if the value were `public`, otherwise behave as if the value were `private`. + +## external-dns.alpha.kubernetes.io/controller + +If this annotation exists and has a value other than `dns-controller` then the source ignores the resource. + +## external-dns.alpha.kubernetes.io/endpoints-type + +Specifies which set of addresses to use for a headless `Service`. + +If the value is `NodeExternalIP`, use each relevant `Pod`'s `Node`'s address of type `ExternalIP` +plus each IPv6 address of type `InternalIP`. + +Otherwise, if the value is `HostIP` or the `--publish-host-ip` flag is specified, use +each relevant `Pod`'s `Status.HostIP`. + +Otherwise, use the `IP` of each of the `Service`'s `Endpoints`'s `Addresses`. + +## external-dns.alpha.kubernetes.io/hostname + +Specifies the domain for the resource's DNS records. + +## external-dns.alpha.kubernetes.io/ingress-hostname-source + +Specifies where to get the domain for an `Ingress` resource. + +If the value is `defined-hosts-only`, use only the domains from the `Ingress` spec. + +If the value is `annotation-only`, use only the domains from the `Ingress` annotations. + +If the annotation is not present, use the domains from both the spec and annotations. + +## external-dns.alpha.kubernetes.io/internal-hostname + +Specifies the domain for the resource's DNS records that are for use from internal networks. + +For `Services` of type `LoadBalancer`, uses the `Service`'s `ClusterIP`. + +For `Pods`, uses the `Pod`'s `Status.PodIP`. + +## external-dns.alpha.kubernetes.io/target + +Specifies a comma-separated list of values to override the resource's DNS record targets (RDATA). + +Targets that parse as IPv4 addresses are published as A records and +targets that parse as IPv6 addresses are published as AAAA records. All other targets +are published as CNAME records. + +## external-dns.alpha.kubernetes.io/ttl + +Specifies the TTL (time to live) for the resource's DNS records. + +The value may be specified as either a duration or an integer number of seconds. +It must be between 1 and 2,147,483,647 seconds. + +## Provider-specific annotations + +Some providers define their own annotations. Cloud-specific annotations have keys prefixed as follows: + +| Cloud | Annotation prefix | +|------------|------------------------------------------------| +| AWS | `external-dns.alpha.kubernetes.io/aws-` | +| CloudFlare | `external-dns.alpha.kubernetes.io/cloudflare-` | +| IBM Cloud | `external-dns.alpha.kubernetes.io/ibmcloud-` | +| Scaleway | `external-dns.alpha.kubernetes.io/scw-` | + +Additional annotations that are currently implemented only by AWS are: + +### external-dns.alpha.kubernetes.io/alias + +If the value of this annotation is `true`, specifies that CNAME records generated by the +resource should instead be alias records. + +This annotation is only relevant if the `--aws-prefer-cname` flag is specified. + +### external-dns.alpha.kubernetes.io/set-identifier + +Specifies the set identifier for DNS records generated by the resource. + +A set identifier differentiates among multiple DNS record sets that have the same combination of domain and type. +Which record set or sets are returned to queries is then determined by the configured routing policy. diff --git a/mkdocs.yml b/mkdocs.yml index b9ea79fdf..471428721 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,6 +12,8 @@ nav: - Code of Conduct: code-of-conduct.md - License: LICENSE.md - Tutorials: tutorials/ + - Annotations: + - About: annotations/annotations.md - Registries: - About: registry/registry.md - TXT: registry/txt.md