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