mirror of
https://github.com/kubernetes-sigs/external-dns.git
synced 2025-12-16 17:21:16 +01:00
docs(advanced): configuration precedence (#5871)
* docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com> * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com> * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com> * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com> * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com> * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com> * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com> * docs(advanced): configuration precedence Co-authored-by: Michel Loiseleur <97035654+mloiseleur@users.noreply.github.com> * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com> --------- Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com> Co-authored-by: Michel Loiseleur <97035654+mloiseleur@users.noreply.github.com>
This commit is contained in:
Ivan Ka
GitHub
parent
caa4fc75a3
commit
85b6a6efae
43
docs/advanced/configuration-precedence.md
Normal file
43
docs/advanced/configuration-precedence.md
Normal file
@ -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<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.
|
||||
@ -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`.
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user