Skip to content

Commit 85b6a6e

Browse files
ivankatliarchukmloiseleur
ivankatliarchuk
and
mloiseleur
authored
docs(advanced): configuration precedence (kubernetes-sigs#5871)
* docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <[email protected]> * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <[email protected]> * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <[email protected]> * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <[email protected]> * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <[email protected]> * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <[email protected]> * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <[email protected]> * docs(advanced): configuration precedence Co-authored-by: Michel Loiseleur <[email protected]> * docs(advanced): configuration precedence Signed-off-by: ivan katliarchuk <[email protected]> --------- Signed-off-by: ivan katliarchuk <[email protected]> Co-authored-by: Michel Loiseleur <[email protected]>
1 parent caa4fc7 commit 85b6a6e

File tree

3 files changed

+69
-20
lines changed

3 files changed

+69
-20
lines changed

‎docs/advanced/configuration-precedence.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
## Annotations vs. CLI Flags Precedence
2+
3+
ExternalDNS configuration can come from these sources: resource annotations, CLI flags, environment variables, and defaults.
4+
The effective value is determined by the following precedence order:
5+
6+
```mermaid
7+
flowchart TD
8+
A[1. Resource Annotations] -->|Override| Result
9+
B[2. CLI Flags] -->|Used if no annotation| Result
10+
C[3. Environment Variables] -->|May override defaults<br/>and in some cases flags/annotations| Result
11+
D[4. Defaults] -->|Fallback| Result
12+
13+
subgraph Flags
14+
B1[Filter Flags: --flag-with-filter] -->|Define scope<br/>Annotations outside scope ignored| B
15+
B2[Non-filter Flags] -->|Apply if no annotation| B
16+
end
17+
18+
Result[Effective ExternalDNS Configuration]
19+
20+
A --> Result
21+
B --> Result
22+
D --> Result
23+
```
24+
25+
1. **Annotations**
26+
- Most configuration options can be set via annotations on supported resources.
27+
- When present, annotations override the corresponding CLI flags and defaults.
28+
- Exception: should be documented.
29+
- Exception: ignored when applied to `kind: DNSEndpoint`
30+
- Exception: filter flags (e.g. `--service-type-filter`, `--source`) define the *scope* of resources considered.
31+
32+
2. **CLI Flags**
33+
- Non-filter flags apply if no annotation overrides them.
34+
- Filter flags (`--source`, `--service-type-filter`, `--*-filter`) limit which resources are processed.
35+
- Annotations outside the defined scope are ignored.
36+
- If a resource is excluded by a filter, annotations configured on the resource or defaults will not be applied.
37+
38+
3. **Environment Variables**
39+
- May override defaults, and in some cases may take precedence over CLI flags and annotations.
40+
- 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`.
41+
42+
4. **Defaults**
43+
- If none of the above specify a value, ExternalDNS falls back to its defaults.

‎docs/annotations/annotations.md‎

Lines changed: 25 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -4,25 +4,25 @@ ExternalDNS sources support a number of annotations on the Kubernetes resources
44

55
The following table documents which sources support which annotations:
66

7-
| Source | controller | hostname | internal-hostname | target | ttl | (provider-specific) | ingress |
8-
|--------------|------------|----------|-------------------|---------|---------|---------------------|:-------:|
9-
| Ambassador | | | | Yes | Yes | Yes | No |
10-
| Connector | | | | | | | No |
11-
| Contour | Yes | Yes[^1] | | Yes | Yes | Yes | No |
12-
| CloudFoundry | | | | | | | No |
13-
| CRD | | | | | | | No |
14-
| F5 | | | | Yes | Yes | | No |
15-
| Gateway | Yes | Yes[^1] | | Yes[^4] | Yes | Yes | No |
16-
| Gloo | | | | Yes | Yes[^5] | Yes[^5] | No |
17-
| Ingress | Yes | Yes[^1] | | Yes | Yes | Yes | No |
18-
| Istio | Yes | Yes[^1] | | Yes | Yes | Yes | Yes |
19-
| Kong | | Yes[^1] | | Yes | Yes | Yes | No |
20-
| Node | Yes | | | Yes | Yes | | No |
21-
| OpenShift | Yes | Yes[^1] | | Yes | Yes | Yes | No |
22-
| Pod | | Yes | Yes | Yes | | | No |
23-
| Service | Yes | Yes[^1] | Yes[^1][^2] | Yes[^3] | Yes | Yes | No |
24-
| Skipper | Yes | Yes[^1] | | Yes | Yes | Yes | No |
25-
| Traefik | | Yes[^1] | | Yes | Yes | Yes | No |
7+
| Source | controller | hostname | internal-hostname | target | ttl | (provider-specific) |
8+
|--------------|------------|----------|-------------------|---------|---------|---------------------|
9+
| Ambassador | | | | Yes | Yes | Yes |
10+
| Connector | | | | | | |
11+
| Contour | Yes | Yes[^1] | | Yes | Yes | Yes |
12+
| CloudFoundry | | | | | | |
13+
| CRD | | | | | | |
14+
| F5 | | | | Yes | Yes | |
15+
| Gateway | Yes | Yes[^1] | | Yes[^4] | Yes | Yes |
16+
| Gloo | | | | Yes | Yes[^5] | Yes[^5] |
17+
| Ingress | Yes | Yes[^1] | | Yes | Yes | Yes |
18+
| Istio | Yes | Yes[^1] | | Yes | Yes | Yes |
19+
| Kong | | Yes[^1] | | Yes | Yes | Yes |
20+
| Node | Yes | | | Yes | Yes | |
21+
| OpenShift | Yes | Yes[^1] | | Yes | Yes | Yes |
22+
| Pod | | Yes | Yes | Yes | | |
23+
| Service | Yes | Yes[^1] | Yes[^1][^2] | Yes[^3] | Yes | Yes |
24+
| Skipper | Yes | Yes[^1] | | Yes | Yes | Yes |
25+
| Traefik | | Yes[^1] | | Yes | Yes | Yes |
2626

2727
[^1]: Unless the `--ignore-hostname-annotation` flag is specified.
2828
[^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
4747

4848
## external-dns.alpha.kubernetes.io/endpoints-type
4949

50-
Specifies which set of addresses to use for a headless `Service`.
50+
Specifies which set of addresses to use for a [`headless Service`](https://kubernetes.io/docs/concepts/services-networking/service/#headless-services).
51+
52+
Supported values:
53+
54+
- `NodeExternalIP`. Required `--service-type-filter=ClusterIP` and `--service-type-filter=Node` or no `--service-type-filter` flag specified.
55+
- `HostIP`.
5156

5257
If the value is `NodeExternalIP`, use each relevant `Pod`'s `Node`'s address of type `ExternalIP`
5358
plus each IPv6 address of type `InternalIP`.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ nav:
3737
- Rate Limits: docs/advanced/rate-limits.md
3838
- TTL: docs/advanced/ttl.md
3939
- Decisions: docs/proposal/0*.md
40+
- Configuration Precedence: docs/advanced/configuration-precedence.md
4041
- Contributing:
4142
- Kubernetes Contributions: CONTRIBUTING.md
4243
- Release: docs/release.md

0 commit comments

Comments
 (0)