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:
|
The following table documents which sources support which annotations:
|
||||||
|
|
||||||
| Source | controller | hostname | internal-hostname | target | ttl | (provider-specific) | ingress |
|
| Source | controller | hostname | internal-hostname | target | ttl | (provider-specific) |
|
||||||
|--------------|------------|----------|-------------------|---------|---------|---------------------|:-------:|
|
|--------------|------------|----------|-------------------|---------|---------|---------------------|
|
||||||
| Ambassador | | | | Yes | Yes | Yes | No |
|
| Ambassador | | | | Yes | Yes | Yes |
|
||||||
| Connector | | | | | | | No |
|
| Connector | | | | | | |
|
||||||
| Contour | Yes | Yes[^1] | | Yes | Yes | Yes | No |
|
| Contour | Yes | Yes[^1] | | Yes | Yes | Yes |
|
||||||
| CloudFoundry | | | | | | | No |
|
| CloudFoundry | | | | | | |
|
||||||
| CRD | | | | | | | No |
|
| CRD | | | | | | |
|
||||||
| F5 | | | | Yes | Yes | | No |
|
| F5 | | | | Yes | Yes | |
|
||||||
| Gateway | Yes | Yes[^1] | | Yes[^4] | Yes | Yes | No |
|
| Gateway | Yes | Yes[^1] | | Yes[^4] | Yes | Yes |
|
||||||
| Gloo | | | | Yes | Yes[^5] | Yes[^5] | No |
|
| Gloo | | | | Yes | Yes[^5] | Yes[^5] |
|
||||||
| Ingress | Yes | Yes[^1] | | Yes | Yes | Yes | No |
|
| Ingress | Yes | Yes[^1] | | Yes | Yes | Yes |
|
||||||
| Istio | Yes | Yes[^1] | | Yes | Yes | Yes | Yes |
|
| Istio | Yes | Yes[^1] | | Yes | Yes | Yes |
|
||||||
| Kong | | Yes[^1] | | Yes | Yes | Yes | No |
|
| Kong | | Yes[^1] | | Yes | Yes | Yes |
|
||||||
| Node | Yes | | | Yes | Yes | | No |
|
| Node | Yes | | | Yes | Yes | |
|
||||||
| OpenShift | Yes | Yes[^1] | | Yes | Yes | Yes | No |
|
| OpenShift | Yes | Yes[^1] | | Yes | Yes | Yes |
|
||||||
| Pod | | Yes | Yes | Yes | | | No |
|
| Pod | | Yes | Yes | Yes | | |
|
||||||
| Service | Yes | Yes[^1] | Yes[^1][^2] | Yes[^3] | Yes | Yes | No |
|
| Service | Yes | Yes[^1] | Yes[^1][^2] | Yes[^3] | Yes | Yes |
|
||||||
| Skipper | Yes | Yes[^1] | | Yes | Yes | Yes | No |
|
| Skipper | Yes | Yes[^1] | | Yes | Yes | Yes |
|
||||||
| Traefik | | Yes[^1] | | Yes | Yes | Yes | No |
|
| Traefik | | Yes[^1] | | Yes | Yes | Yes |
|
||||||
|
|
||||||
[^1]: Unless the `--ignore-hostname-annotation` flag is specified.
|
[^1]: Unless the `--ignore-hostname-annotation` flag is specified.
|
||||||
[^2]: Only behaves differently than `hostname` for `Service`s of type `ClusterIP` or `LoadBalancer`.
|
[^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
|
## 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`
|
If the value is `NodeExternalIP`, use each relevant `Pod`'s `Node`'s address of type `ExternalIP`
|
||||||
plus each IPv6 address of type `InternalIP`.
|
plus each IPv6 address of type `InternalIP`.
|
||||||
|
|||||||
@ -37,6 +37,7 @@ nav:
|
|||||||
- Rate Limits: docs/advanced/rate-limits.md
|
- Rate Limits: docs/advanced/rate-limits.md
|
||||||
- TTL: docs/advanced/ttl.md
|
- TTL: docs/advanced/ttl.md
|
||||||
- Decisions: docs/proposal/0*.md
|
- Decisions: docs/proposal/0*.md
|
||||||
|
- Configuration Precedence: docs/advanced/configuration-precedence.md
|
||||||
- Contributing:
|
- Contributing:
|
||||||
- Kubernetes Contributions: CONTRIBUTING.md
|
- Kubernetes Contributions: CONTRIBUTING.md
|
||||||
- Release: docs/release.md
|
- Release: docs/release.md
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user