From 85b6a6efae49c910c1e2840f90ccd9108002e46a Mon Sep 17 00:00:00 2001 From: Ivan Ka <5395690+ivankatliarchuk@users.noreply.github.com> Date: Fri, 3 Oct 2025 17:02:59 +0100 Subject: [PATCH] docs(advanced): configuration precedence (#5871) * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk * docs(advanced): configuration precedence Co-authored-by: Michel Loiseleur <97035654+mloiseleur@users.noreply.github.com> * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk --------- Signed-off-by: ivan katliarchuk Co-authored-by: Michel Loiseleur <97035654+mloiseleur@users.noreply.github.com> --- docs/advanced/configuration-precedence.md | 43 ++++++++++++++++++++++ docs/annotations/annotations.md | 45 +++++++++++++---------- mkdocs.yml | 1 + 3 files changed, 69 insertions(+), 20 deletions(-) create mode 100644 docs/advanced/configuration-precedence.md diff --git a/docs/advanced/configuration-precedence.md b/docs/advanced/configuration-precedence.md new file mode 100644 index 000000000..008aa255b --- /dev/null +++ b/docs/advanced/configuration-precedence.md @@ -0,0 +1,43 @@ +## Annotations vs. CLI Flags Precedence + +ExternalDNS configuration can come from these sources: resource annotations, CLI flags, environment variables, and defaults. +The effective value is determined by the following precedence order: + +```mermaid +flowchart TD + A[1. Resource Annotations] -->|Override| Result + B[2. CLI Flags] -->|Used if no annotation| Result + C[3. Environment Variables] -->|May override defaults
and in some cases flags/annotations| Result + D[4. Defaults] -->|Fallback| Result + + subgraph Flags + B1[Filter Flags: --flag-with-filter] -->|Define scope
Annotations outside scope ignored| B + B2[Non-filter Flags] -->|Apply if no annotation| B + end + + Result[Effective ExternalDNS Configuration] + + A --> Result + B --> Result + D --> Result +``` + +1. **Annotations** + - Most configuration options can be set via annotations on supported resources. + - When present, annotations override the corresponding CLI flags and defaults. + - Exception: should be documented. + - Exception: ignored when applied to `kind: DNSEndpoint` + - Exception: filter flags (e.g. `--service-type-filter`, `--source`) define the *scope* of resources considered. + +2. **CLI Flags** + - Non-filter flags apply if no annotation overrides them. + - Filter flags (`--source`, `--service-type-filter`, `--*-filter`) limit which resources are processed. + - Annotations outside the defined scope are ignored. + - If a resource is excluded by a filter, annotations configured on the resource or defaults will not be applied. + +3. **Environment Variables** + - May override defaults, and in some cases may take precedence over CLI flags and annotations. + - Behavior depends on how the variable is mapped in the code. Where or not it replicates CLI flag or provider specific. Example: `kubectl` or `cloudflare`. + +4. **Defaults** + - If none of the above specify a value, ExternalDNS falls back to its defaults. diff --git a/docs/annotations/annotations.md b/docs/annotations/annotations.md index 88ee23031..343079d31 100644 --- a/docs/annotations/annotations.md +++ b/docs/annotations/annotations.md @@ -4,25 +4,25 @@ ExternalDNS sources support a number of annotations on the Kubernetes resources The following table documents which sources support which annotations: -| Source | controller | hostname | internal-hostname | target | ttl | (provider-specific) | ingress | -|--------------|------------|----------|-------------------|---------|---------|---------------------|:-------:| -| Ambassador | | | | Yes | Yes | Yes | No | -| Connector | | | | | | | No | -| Contour | Yes | Yes[^1] | | Yes | Yes | Yes | No | -| CloudFoundry | | | | | | | No | -| CRD | | | | | | | No | -| F5 | | | | Yes | Yes | | No | -| Gateway | Yes | Yes[^1] | | Yes[^4] | Yes | Yes | No | -| Gloo | | | | Yes | Yes[^5] | Yes[^5] | No | -| Ingress | Yes | Yes[^1] | | Yes | Yes | Yes | No | -| Istio | Yes | Yes[^1] | | Yes | Yes | Yes | Yes | -| Kong | | Yes[^1] | | Yes | Yes | Yes | No | -| Node | Yes | | | Yes | Yes | | No | -| OpenShift | Yes | Yes[^1] | | Yes | Yes | Yes | No | -| Pod | | Yes | Yes | Yes | | | No | -| Service | Yes | Yes[^1] | Yes[^1][^2] | Yes[^3] | Yes | Yes | No | -| Skipper | Yes | Yes[^1] | | Yes | Yes | Yes | No | -| Traefik | | Yes[^1] | | Yes | Yes | Yes | No | +| Source | controller | hostname | internal-hostname | target | ttl | (provider-specific) | +|--------------|------------|----------|-------------------|---------|---------|---------------------| +| Ambassador | | | | Yes | Yes | Yes | +| Connector | | | | | | | +| Contour | Yes | Yes[^1] | | Yes | Yes | Yes | +| CloudFoundry | | | | | | | +| CRD | | | | | | | +| F5 | | | | Yes | Yes | | +| Gateway | Yes | Yes[^1] | | Yes[^4] | Yes | Yes | +| Gloo | | | | Yes | Yes[^5] | Yes[^5] | +| Ingress | Yes | Yes[^1] | | Yes | Yes | Yes | +| Istio | Yes | Yes[^1] | | Yes | Yes | Yes | +| Kong | | Yes[^1] | | Yes | Yes | Yes | +| Node | Yes | | | Yes | Yes | | +| OpenShift | Yes | Yes[^1] | | Yes | Yes | Yes | +| Pod | | Yes | Yes | Yes | | | +| Service | Yes | Yes[^1] | Yes[^1][^2] | Yes[^3] | Yes | Yes | +| Skipper | Yes | Yes[^1] | | Yes | Yes | Yes | +| Traefik | | Yes[^1] | | Yes | Yes | Yes | [^1]: Unless the `--ignore-hostname-annotation` flag is specified. [^2]: Only behaves differently than `hostname` for `Service`s of type `ClusterIP` or `LoadBalancer`. @@ -47,7 +47,12 @@ If this annotation exists and has a value other than `dns-controller` then the s ## external-dns.alpha.kubernetes.io/endpoints-type -Specifies which set of addresses to use for a headless `Service`. +Specifies which set of addresses to use for a [`headless Service`](https://kubernetes.io/docs/concepts/services-networking/service/#headless-services). + +Supported values: + +- `NodeExternalIP`. Required `--service-type-filter=ClusterIP` and `--service-type-filter=Node` or no `--service-type-filter` flag specified. +- `HostIP`. If the value is `NodeExternalIP`, use each relevant `Pod`'s `Node`'s address of type `ExternalIP` plus each IPv6 address of type `InternalIP`. diff --git a/mkdocs.yml b/mkdocs.yml index 248182b59..ba43d2893 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -37,6 +37,7 @@ nav: - Rate Limits: docs/advanced/rate-limits.md - TTL: docs/advanced/ttl.md - Decisions: docs/proposal/0*.md + - Configuration Precedence: docs/advanced/configuration-precedence.md - Contributing: - Kubernetes Contributions: CONTRIBUTING.md - Release: docs/release.md