external-dns/docs/advanced/configuration-precedence.md

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:

flowchart TD
    A[1. Resource Annotations] -->|Override| Result
    B[2. CLI Flags] -->|Used if no annotation| Result
    C[3. Environment Variables] -->|May override defaults<br/>and in some cases flags/annotations| Result
    D[4. Defaults] -->|Fallback| Result

    subgraph Flags
        B1[Filter Flags: --flag-with-filter] -->|Define scope<br/>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.