Skip to content

Commit f67cc94

Browse files
ivankatliarchukmloiseleur
ivankatliarchuk
and
mloiseleur
authored
docs(proposal): externaldns api graduation to beta (kubernetes-sigs#5079)
* docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk <[email protected]> * docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk <[email protected]> * docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk <[email protected]> * docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk <[email protected]> * docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk <[email protected]> * docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk <[email protected]> * docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk <[email protected]> * docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk <[email protected]> * docs(proposal): externaldns api graduation to beta Co-authored-by: Michel Loiseleur <[email protected]> * docs(proposal): externaldns api graduation to beta --------- Signed-off-by: ivan katliarchuk <[email protected]> Co-authored-by: Michel Loiseleur <[email protected]>
1 parent 65d534e commit f67cc94

File tree

1 file changed

+179
-0
lines changed

1 file changed

+179
-0
lines changed

‎docs/proposal/003-dnsendpoint-graduation-to-beta.md

+179
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
```yaml
2+
---
3+
title: "Proposal: Defining a path to Beta for DNSEndpoint API"
4+
version: v1alpha1
5+
authors: @ivankatliarchuk, @raffo, @szuecs
6+
creation-date: 2025-02-09
7+
status: approved
8+
---
9+
```
10+
11+
# Proposal: Defining a path to Beta for DNSEndpoint API
12+
13+
## Summary
14+
15+
The `DNSEndpoint` API in Kubernetes SIGs `external-dns` is currently in alpha. To ensure its stability and readiness for production environments, we propose defining and agreeing upon the necessary requirements for its graduation to beta.
16+
By defining clear criteria, we aim to ensure stability, usability, and compatibility with the broader Kubernetes ecosystem. On completions of all this items, we should be in the position to graduate `DNSEndpoint` to `v1beta`.
17+
18+
## Motivation
19+
20+
The DNSEndpoint API is a crucial component of the ExternalDNS project, allowing users to manage DNS records dynamically.
21+
Currently, it remains in the alpha stage, limiting its adoption due to potential instability and lack of guaranteed backward compatibility. By advancing to beta, we can provide users with a more reliable API and encourage wider adoption with confidence in its long-term viability and support.
22+
23+
### Goals
24+
25+
- Define the necessary requirements for `DNSEndpoint` API to reach beta status.
26+
- Improve API stability, usability, and documentation.
27+
- Improve test coverage, automate documentation creation, and validation mechanisms.
28+
- Ensure backward compatibility and migration strategies from alpha to beta.
29+
- Collect and incorporate feedback from existing users to refine the API.
30+
- Address any identified issues or limitations in the current API design.
31+
32+
### Non-Goals
33+
34+
- This proposal does not cover the graduation of ExternalDNS itself to a stable release.
35+
- Making `DNSEndpoint` a stable (GA) API at this stage.
36+
- It does not include implementation details for specific DNS providers.
37+
- It does not introduce new functionality beyond stabilizing the DNSEndpoint API.
38+
- Redesigning the API from scratch.
39+
- Introducing breaking changes that would require significant refactoring for existing users.
40+
41+
## Proposal
42+
43+
The proposal aims to formalize the promotion process by addressing API design, user needs, and implementation details.
44+
45+
To graduate the `DNSEndpoint` API to beta, we propose the following actions:
46+
47+
1. Capture feedback from the community on missing functionality for DNSEndpoint CRD
48+
- In a form of Github issue, pin the issue to the project
49+
- Link all CRD related issues to it
50+
2. Refactor `endpoint` folder, move away `api/crd` related stuff to `apis/<apiVersion> folder`
51+
3. Documentation for API to be generated automatically with test coverage, similar to `docs/flags.md`
52+
4. APIs and CRDs discoverable. [doc.crds.dev](https://doc.crds.dev/github.com/kubernetes-sigs/external-dns). Example [crossplane](https://doc.crds.dev/github.com/crossplane/[email protected])
53+
5. Review and change .status object such that people can debug and monitor DNSEndpoint object behavior.
54+
6. Introduce metrics related to DNSEndpoint CRD
55+
- Number of CRDs discovered
56+
- Number of CRDs by status success|fail
57+
58+
Proposed folder structure for `apis`. Examples - [gateway-api](https://github.com/kubernetes-sigs/gateway-api/tree/main/apis)
59+
60+
***Multiple APIs under same version***
61+
62+
```yml
63+
├── apis
64+
│ ├── v1alpha
65+
│ │ ├── util/validation
66+
│ │ ├── doc.go
67+
│ │ └── zz_generated.***.go
68+
│ ├── v1beta # outside of scope currently, just an example
69+
│ │ ├── util/validation
70+
│ │ ├── doc.go
71+
│ │ └── zz_generated.***.go
72+
│ ├── v1 # outside of scope currently, just an example
73+
│ │ ├── util/validation
74+
│ │ ├── doc.go
75+
│ │ └── zz_generated.***.go
76+
```
77+
78+
Or similar folder structure for `apis`. Examples - [cert-manager](https://github.com/cert-manager/cert-manager/tree/master/pkg/apis)
79+
80+
***APIs versioned independently***
81+
82+
```yml
83+
├── apis
84+
│ ├── dnsendpoint
85+
│ │ ├── v1alpha
86+
│ │ │ ├── util/validation
87+
│ │ │ ├── doc.go
88+
│ │ │ └── zz_generated.***.go
89+
│ │ ├── v1beta # outside of scope currently, just an example
90+
│ │ │ ├── util/validation
91+
│ │ │ ├── doc.go
92+
│ │ │ └── zz_generated.***.go
93+
│ │ ├── v1 # outside of scope currently, just an example
94+
│ │ │ ├── util/validation
95+
│ │ │ ├── doc.go
96+
│ │ │ └── zz_generated.***.go
97+
│ ├── dnsentry
98+
│ │ ├── v1alpha
99+
```
100+
101+
### User Stories
102+
103+
#### Story 1: Cluster Operator/Admin Managing External DNS
104+
105+
*As a cluster operator or administrator*, I want a stable `DNSEndpoint` API to reliably manage DNS records within Kubernetes so that I can ensure consistent and automated DNS resolution for my services.
106+
107+
#### Story 2: Developers Integrating External DNS
108+
109+
*As a developer*, I want a well-documented `DNSEndpoint` API that allows me to programmatically define and manage DNS records without worrying about breaking changes.
110+
111+
#### Story 3: Cloud-Native Deployments
112+
113+
*As a SRE*, I need a tested and validated `DNSEndpoint` API that integrates seamlessly with cloud-native networking services, ensuring high availability and scalability.
114+
115+
#### Story 4: Platform Engineer
116+
117+
*As a platform engineer*, I want stronger validation and defaulting so that I can reduce misconfigurations and operational overhead.
118+
119+
### API
120+
121+
The DNSEndpoint API should provide a robust Custom Resource Definition (CRD) with well-defined fields and validation.
122+
123+
#### DNSEndpoint
124+
125+
- [ ] DNSEndpoint do not have any changes from v1alpha1.
126+
- [ ] DNSEndpoint to have changes from v1alpha1. `TBD`
127+
128+
```yml
129+
apiVersion: externaldns.k8s.io/v1beta1
130+
kind: DNSEndpoint
131+
metadata:
132+
name: example-endpoint
133+
spec:
134+
endpoints:
135+
- dnsName: "example.com"
136+
recordType: "A"
137+
targets:
138+
- "192.168.1.1"
139+
ttl: 300
140+
- dnsName: "www.example.com"
141+
recordType: "CNAME"
142+
targets:
143+
- "example.com"
144+
```
145+
146+
### Behavior
147+
148+
How should the new CRD or feature behave? Are there edge cases?
149+
150+
### Drawbacks
151+
152+
- Transitioning to beta may require deprecating certain alpha features that are deemed unstable.
153+
- Increased maintenance effort to ensure stability and backward compatibility.
154+
- Users of the alpha API may need to adjust their configurations if breaking changes are introduced.
155+
- Additional maintenance and support burden for the `external-dns` maintainers.
156+
157+
## Alternatives
158+
159+
1. **Remain in Alpha**: The DNSEndpoint API could remain in alpha indefinitely, but this would discourage adoption and limit its reliability.
160+
161+
- Pros: No immediate changes or migration concerns.
162+
- Cons: Lack of progress discourages adoption, and users may seek alternative solutions.
163+
164+
2. **Graduate Directly to GA**: Skipping the beta phase could accelerate stability, but it would limit the opportunity for community feedback and refinement.
165+
166+
3. **Introduce a New API Version**: Instead of modifying the existing API, a new version (e.g., `v2alpha1`) could be introduced, allowing gradual migration.
167+
168+
- Pros: Allowing gradual migration like `v1alpha1` -> `v2alpha1` -> `v1beta`
169+
- Cons: This approach would require maintaining multiple versions simultaneously.
170+
171+
4. **Redesign the API Before Graduation**
172+
173+
- Pros: Provides an opportunity to fix any fundamental design flaws before moving to beta.
174+
- Cons: Increases complexity, delays the beta release, and may introduce unnecessary work for existing users.
175+
176+
5. **Deprecate DNSEndpoint and Rely on External Solutions or Annotations**
177+
178+
- Pros: Potentially reduces the maintenance burden on the Kubernetes SIG.
179+
- Cons: Forces users to migrate to third-party solutions or away from CRDs, reducing the cohesion of external-dns within Kubernetes.

0 commit comments

Comments
 (0)