From e0f923954c11869550fee9950d9c21e5176831f5 Mon Sep 17 00:00:00 2001 From: ivan katliarchuk Date: Sun, 9 Feb 2025 19:11:11 +0000 Subject: [PATCH 1/8] docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk --- docs/proposal/design-template.md | 2 +- .../dnsendpoint-graduation-to-beta.md | 139 ++++++++++++++++++ 2 files changed, 140 insertions(+), 1 deletion(-) create mode 100644 docs/proposal/dnsendpoint-graduation-to-beta.md diff --git a/docs/proposal/design-template.md b/docs/proposal/design-template.md index 4d75aaa98f..32eea82fae 100644 --- a/docs/proposal/design-template.md +++ b/docs/proposal/design-template.md @@ -4,7 +4,7 @@ title: New Feature or Deprecation/Removal Proposal version: if applicable authors: you, me -creation-date: 2025-01-01 +creation-date: 2025-jan-01 status: draft --- ``` diff --git a/docs/proposal/dnsendpoint-graduation-to-beta.md b/docs/proposal/dnsendpoint-graduation-to-beta.md new file mode 100644 index 0000000000..e5df13e834 --- /dev/null +++ b/docs/proposal/dnsendpoint-graduation-to-beta.md @@ -0,0 +1,139 @@ +```yaml +--- +title: "Proposal: API DNSEndpoint graduation to beta" +version: tbd +authors: ivankatliarchuk +creation-date: 2025-feb-9 +status: proposal +--- +``` + +# Proposal: Agree on requirements for API DNSEndpoint to graduate to beta + +## Summary + +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. 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`. + +## Motivation + +The DNSEndpoint API is a crucial component of the ExternalDNS project, allowing users to manage DNS records dynamically. 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. + +### Goals + +- Define the necessary requirements for `DNSEndpoint` API to reach beta status. +- Improve API stability, usability, and documentation. +- Improve test coverage, automate documentation creation, and validation mechanisms. +- Ensure backward compatibility and migration strategies from alpha to beta. +- Collect and incorporate feedback from existing users to refine the API. +- Address any identified issues or limitations in the current API design. + +### Non-Goals + +- This proposal does not cover the graduation of ExternalDNS itself to a stable release. +- Making `DNSEndpoint` a stable (GA) API at this stage. +- It does not include implementation details for specific DNS providers. +- It does not introduce new functionality beyond stabilizing the DNSEndpoint API. +- Redesigning the API from scratch. +- Introducing breaking changes that would require significant refactoring for existing users. + +## Proposal + +The proposal aims to formalize the promotion process by addressing API design, user needs, and implementation details. + +To graduate the `DNSEndpoint` API to beta, we propose the following actions: + +1. Refactor `endpoint` folder, move away `api/crd` related stuff to `apis/ folder` +2. Documentation for API to be generated automatically with test coverage, similar to `docs/flags.md` +3. API(s) and CRD(s) discoverable. [doc.crds.dev](https://doc.crds.dev/github.com/kubernetes-sigs/external-dns). Example [crosplane](https://doc.crds.dev/github.com/crossplane/crossplane@v0.10.0) +4. TBD +5. TBD + +Proposed folder structure for `apis`. Examples - [gateway-api](https://github.com/kubernetes-sigs/gateway-api/tree/main/apis) + +```yml +├── apis +│ ├── v1alpha +│ │ ├── util/validation +│ │ ├── doc.go +│ │ └── zz_generated.***.go +│ ├── v1beta # outside of scope currently, just an example +│ │ ├── util/validation +│ │ ├── doc.go +│ │ └── zz_generated.***.go +│ ├── v1 # outside of scope currently, just an example +│ │ ├── util/validation +│ │ ├── doc.go +│ │ └── zz_generated.***.go +``` + +### User Stories + +#### Story 1: Cluster Operator/Admin Managing External DNS + +_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. + +#### Story 2: Developers Integrating External DNS + +_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. + +#### Story 3: Cloud-Native Deployments + +_As an SRE_, I need a tested and validated `DNSEndpoint` API that integrates seamlessly with cloud-native networking services, ensuring high availability and scalability. + +#### Story 4: Platform Engineer + +_As a platform engineer_, I want stronger validation and defaulting so that I can reduce misconfigurations and operational overhead. + +### API + +The DNSEndpoint API should provide a robust Custom Resource Definition (CRD) with well-defined fields and validation. + +#### DNSEndpoint + +- [ ] DNSEndpoint do not have any changes from v1alpha1. +- [ ] DNSEndpoint to have changes from v1alpha1. `TBD` + +```yml +apiVersion: externaldns.k8s.io/v1beta1 +kind: DNSEndpoint +metadata: + name: example-endpoint +spec: + endpoints: + - dnsName: "example.com" + recordType: "A" + targets: + - "192.168.1.1" + ttl: 300 + - dnsName: "www.example.com" + recordType: "CNAME" + targets: + - "example.com" +``` + +### Behavior + +How should the new CRD or feature behave? Are there edge cases? + +### Drawbacks + +- Transitioning to beta may require deprecating certain alpha features that are deemed unstable. +- Increased maintenance effort to ensure stability and backward compatibility. +- Users of the alpha API may need to adjust their configurations if breaking changes are introduced. +- Additional maintenance and support burden for the `external-dns` maintainers. + +## Alternatives + +1. **Remain in Alpha**: The DNSEndpoint API could remain in alpha indefinitely, but this would discourage adoption and limit its reliability. + - Pros: No immediate changes or migration concerns. + - Cons: Lack of progress discourages adoption, and users may seek alternative solutions. +2. **Graduate Directly to GA**: Skipping the beta phase could accelerate stability, but it would limit the opportunity for community feedback and refinement. +3. **Introduce a New API Version**: Instead of modifying the existing API, a new version (e.g., `v2alpha1`) could be introduced, allowing gradual migration. + - Pros: Allowing gradual migration like `v1alpha1` -> `v2alpha1` -> `v1beta` + - Cons: This approach would require maintaining multiple versions simultaneously. +4. **Redesign the API Before Graduation** + - Pros: Provides an opportunity to fix any fundamental design flaws before moving to beta. + - Cons: Increases complexity, delays the beta release, and may introduce unnecessary work for existing users. +5. **Deprecate DNSEndpoint and Rely on External Solutions or Annotations** + - Pros: Potentially reduces the maintenance burden on the Kubernetes SIG. + - Cons: Forces users to migrate to third-party solutions or away from CRDs, reducing the cohesion of external-dns within Kubernetes. From 9bd5f73435336983b22e088625a47b79a1f22c34 Mon Sep 17 00:00:00 2001 From: ivan katliarchuk Date: Sun, 9 Feb 2025 20:53:53 +0000 Subject: [PATCH 2/8] docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk --- .../dnsendpoint-graduation-to-beta.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/proposal/dnsendpoint-graduation-to-beta.md b/docs/proposal/dnsendpoint-graduation-to-beta.md index e5df13e834..39e2bc86e4 100644 --- a/docs/proposal/dnsendpoint-graduation-to-beta.md +++ b/docs/proposal/dnsendpoint-graduation-to-beta.md @@ -50,6 +50,8 @@ To graduate the `DNSEndpoint` API to beta, we propose the following actions: Proposed folder structure for `apis`. Examples - [gateway-api](https://github.com/kubernetes-sigs/gateway-api/tree/main/apis) +***Multiple APIs under same version*** + ```yml ├── apis │ ├── v1alpha @@ -66,6 +68,29 @@ Proposed folder structure for `apis`. Examples - [gateway-api](https://github.co │ │ └── zz_generated.***.go ``` +Or similar folder structure for `apis`. Examples - [cert-manager](https://github.com/cert-manager/cert-manager/tree/master/pkg/apis) + +***APIs versioned independently*** + +```yml +├── apis +│ ├── dnsendpoint +│ │ ├── v1alpha +│ │ │ ├── util/validation +│ │ │ ├── doc.go +│ │ │ └── zz_generated.***.go +│ │ ├── v1beta # outside of scope currently, just an example +│ │ │ ├── util/validation +│ │ │ ├── doc.go +│ │ │ └── zz_generated.***.go +│ │ ├── v1 # outside of scope currently, just an example +│ │ │ ├── util/validation +│ │ │ ├── doc.go +│ │ │ └── zz_generated.***.go +│ ├── dnsentry +│ │ ├── v1alpha +``` + ### User Stories #### Story 1: Cluster Operator/Admin Managing External DNS From 52a556de7a0514af6ccfc77b74407bffd2158600 Mon Sep 17 00:00:00 2001 From: ivan katliarchuk Date: Wed, 26 Feb 2025 08:23:08 +0000 Subject: [PATCH 3/8] docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk --- ...eta.md => 003-dnsendpoint-graduation-to-beta.md} | 13 +++++++++---- docs/proposal/design-template.md | 2 +- 2 files changed, 10 insertions(+), 5 deletions(-) rename docs/proposal/{dnsendpoint-graduation-to-beta.md => 003-dnsendpoint-graduation-to-beta.md} (93%) diff --git a/docs/proposal/dnsendpoint-graduation-to-beta.md b/docs/proposal/003-dnsendpoint-graduation-to-beta.md similarity index 93% rename from docs/proposal/dnsendpoint-graduation-to-beta.md rename to docs/proposal/003-dnsendpoint-graduation-to-beta.md index 39e2bc86e4..681aab808f 100644 --- a/docs/proposal/dnsendpoint-graduation-to-beta.md +++ b/docs/proposal/003-dnsendpoint-graduation-to-beta.md @@ -1,8 +1,8 @@ ```yaml --- -title: "Proposal: API DNSEndpoint graduation to beta" +title: "Proposal: Defining a path to Beta the DNSEndpoint API" version: tbd -authors: ivankatliarchuk +authors: @ivankatliarchuk, @raffo, @szuecs creation-date: 2025-feb-9 status: proposal --- @@ -45,8 +45,13 @@ To graduate the `DNSEndpoint` API to beta, we propose the following actions: 1. Refactor `endpoint` folder, move away `api/crd` related stuff to `apis/ folder` 2. Documentation for API to be generated automatically with test coverage, similar to `docs/flags.md` 3. API(s) and CRD(s) discoverable. [doc.crds.dev](https://doc.crds.dev/github.com/kubernetes-sigs/external-dns). Example [crosplane](https://doc.crds.dev/github.com/crossplane/crossplane@v0.10.0) -4. TBD -5. TBD +4. Review and change .status object such that people can debug and monitor DNSEndpoint object behavior. +5. Capture feedback from the community on missing functionality for DNSEndpoint CRD + - In a form of Github issue, pin the issue to the project + - Link all CRD related issues to it +6. Introduce metrics related to DNSEndpoint CRD + - Number of CRDs discovered + - Number of CRDs by status success|fail Proposed folder structure for `apis`. Examples - [gateway-api](https://github.com/kubernetes-sigs/gateway-api/tree/main/apis) diff --git a/docs/proposal/design-template.md b/docs/proposal/design-template.md index 32eea82fae..4d75aaa98f 100644 --- a/docs/proposal/design-template.md +++ b/docs/proposal/design-template.md @@ -4,7 +4,7 @@ title: New Feature or Deprecation/Removal Proposal version: if applicable authors: you, me -creation-date: 2025-jan-01 +creation-date: 2025-01-01 status: draft --- ``` From 4a6530fb12e0a63197885078b58cbaf03de0131f Mon Sep 17 00:00:00 2001 From: ivan katliarchuk Date: Wed, 26 Feb 2025 08:24:22 +0000 Subject: [PATCH 4/8] docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk --- docs/proposal/003-dnsendpoint-graduation-to-beta.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposal/003-dnsendpoint-graduation-to-beta.md b/docs/proposal/003-dnsendpoint-graduation-to-beta.md index 681aab808f..58b30693e8 100644 --- a/docs/proposal/003-dnsendpoint-graduation-to-beta.md +++ b/docs/proposal/003-dnsendpoint-graduation-to-beta.md @@ -3,7 +3,7 @@ title: "Proposal: Defining a path to Beta the DNSEndpoint API" version: tbd authors: @ivankatliarchuk, @raffo, @szuecs -creation-date: 2025-feb-9 +creation-date: 2025-02-09 status: proposal --- ``` From ea5cb4f4e9642c38c50f3e1b90690a140502c2ea Mon Sep 17 00:00:00 2001 From: ivan katliarchuk Date: Wed, 26 Feb 2025 08:26:18 +0000 Subject: [PATCH 5/8] docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk --- docs/proposal/003-dnsendpoint-graduation-to-beta.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/proposal/003-dnsendpoint-graduation-to-beta.md b/docs/proposal/003-dnsendpoint-graduation-to-beta.md index 58b30693e8..40270a5bcd 100644 --- a/docs/proposal/003-dnsendpoint-graduation-to-beta.md +++ b/docs/proposal/003-dnsendpoint-graduation-to-beta.md @@ -42,13 +42,13 @@ The proposal aims to formalize the promotion process by addressing API design, u To graduate the `DNSEndpoint` API to beta, we propose the following actions: -1. Refactor `endpoint` folder, move away `api/crd` related stuff to `apis/ folder` -2. Documentation for API to be generated automatically with test coverage, similar to `docs/flags.md` -3. API(s) and CRD(s) discoverable. [doc.crds.dev](https://doc.crds.dev/github.com/kubernetes-sigs/external-dns). Example [crosplane](https://doc.crds.dev/github.com/crossplane/crossplane@v0.10.0) -4. Review and change .status object such that people can debug and monitor DNSEndpoint object behavior. -5. Capture feedback from the community on missing functionality for DNSEndpoint CRD +1. Capture feedback from the community on missing functionality for DNSEndpoint CRD - In a form of Github issue, pin the issue to the project - Link all CRD related issues to it +2. Refactor `endpoint` folder, move away `api/crd` related stuff to `apis/ folder` +3. Documentation for API to be generated automatically with test coverage, similar to `docs/flags.md` +4. API(s) and CRD(s) discoverable. [doc.crds.dev](https://doc.crds.dev/github.com/kubernetes-sigs/external-dns). Example [crosplane](https://doc.crds.dev/github.com/crossplane/crossplane@v0.10.0) +5. Review and change .status object such that people can debug and monitor DNSEndpoint object behavior. 6. Introduce metrics related to DNSEndpoint CRD - Number of CRDs discovered - Number of CRDs by status success|fail From 74d7f934991938fa2ae81126a60dfcd0bfbe0c94 Mon Sep 17 00:00:00 2001 From: ivan katliarchuk Date: Wed, 26 Feb 2025 09:07:36 +0000 Subject: [PATCH 6/8] docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk --- .../003-dnsendpoint-graduation-to-beta.md | 26 +++++++++++++------ 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/proposal/003-dnsendpoint-graduation-to-beta.md b/docs/proposal/003-dnsendpoint-graduation-to-beta.md index 40270a5bcd..83c05beaa0 100644 --- a/docs/proposal/003-dnsendpoint-graduation-to-beta.md +++ b/docs/proposal/003-dnsendpoint-graduation-to-beta.md @@ -12,11 +12,13 @@ status: proposal ## Summary -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. 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`. +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. +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`. ## Motivation -The DNSEndpoint API is a crucial component of the ExternalDNS project, allowing users to manage DNS records dynamically. 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. +The DNSEndpoint API is a crucial component of the ExternalDNS project, allowing users to manage DNS records dynamically. +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. ### Goals @@ -100,19 +102,19 @@ Or similar folder structure for `apis`. Examples - [cert-manager](https://github #### Story 1: Cluster Operator/Admin Managing External DNS -_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. +*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. #### Story 2: Developers Integrating External DNS -_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. +*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. #### Story 3: Cloud-Native Deployments -_As an SRE_, I need a tested and validated `DNSEndpoint` API that integrates seamlessly with cloud-native networking services, ensuring high availability and scalability. +*As an SRE*, I need a tested and validated `DNSEndpoint` API that integrates seamlessly with cloud-native networking services, ensuring high availability and scalability. #### Story 4: Platform Engineer -_As a platform engineer_, I want stronger validation and defaulting so that I can reduce misconfigurations and operational overhead. +*As a platform engineer*, I want stronger validation and defaulting so that I can reduce misconfigurations and operational overhead. ### API @@ -155,15 +157,23 @@ How should the new CRD or feature behave? Are there edge cases? ## Alternatives 1. **Remain in Alpha**: The DNSEndpoint API could remain in alpha indefinitely, but this would discourage adoption and limit its reliability. - - Pros: No immediate changes or migration concerns. - - Cons: Lack of progress discourages adoption, and users may seek alternative solutions. + +- Pros: No immediate changes or migration concerns. +- Cons: Lack of progress discourages adoption, and users may seek alternative solutions. + 2. **Graduate Directly to GA**: Skipping the beta phase could accelerate stability, but it would limit the opportunity for community feedback and refinement. + 3. **Introduce a New API Version**: Instead of modifying the existing API, a new version (e.g., `v2alpha1`) could be introduced, allowing gradual migration. + - Pros: Allowing gradual migration like `v1alpha1` -> `v2alpha1` -> `v1beta` - Cons: This approach would require maintaining multiple versions simultaneously. + 4. **Redesign the API Before Graduation** + - Pros: Provides an opportunity to fix any fundamental design flaws before moving to beta. - Cons: Increases complexity, delays the beta release, and may introduce unnecessary work for existing users. + 5. **Deprecate DNSEndpoint and Rely on External Solutions or Annotations** + - Pros: Potentially reduces the maintenance burden on the Kubernetes SIG. - Cons: Forces users to migrate to third-party solutions or away from CRDs, reducing the cohesion of external-dns within Kubernetes. From 5a74c4e3451b1649a1d82336e6f62967d31f95c3 Mon Sep 17 00:00:00 2001 From: ivan katliarchuk Date: Sat, 8 Mar 2025 08:28:31 +0000 Subject: [PATCH 7/8] docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk --- docs/proposal/003-dnsendpoint-graduation-to-beta.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposal/003-dnsendpoint-graduation-to-beta.md b/docs/proposal/003-dnsendpoint-graduation-to-beta.md index 83c05beaa0..25df29e366 100644 --- a/docs/proposal/003-dnsendpoint-graduation-to-beta.md +++ b/docs/proposal/003-dnsendpoint-graduation-to-beta.md @@ -1,7 +1,7 @@ ```yaml --- title: "Proposal: Defining a path to Beta the DNSEndpoint API" -version: tbd +version: v1alpha1 authors: @ivankatliarchuk, @raffo, @szuecs creation-date: 2025-02-09 status: proposal From ecd1cef80def04b01ddb3de9c563cde94dd2a73f Mon Sep 17 00:00:00 2001 From: ivan katliarchuk Date: Sat, 8 Mar 2025 18:36:36 +0000 Subject: [PATCH 8/8] docs(proposal): externaldns api graduation to beta Signed-off-by: ivan katliarchuk --- docs/proposal/003-dnsendpoint-graduation-to-beta.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposal/003-dnsendpoint-graduation-to-beta.md b/docs/proposal/003-dnsendpoint-graduation-to-beta.md index 25df29e366..6f6bfc73ab 100644 --- a/docs/proposal/003-dnsendpoint-graduation-to-beta.md +++ b/docs/proposal/003-dnsendpoint-graduation-to-beta.md @@ -1,6 +1,6 @@ ```yaml --- -title: "Proposal: Defining a path to Beta the DNSEndpoint API" +title: "Proposal: Defining a path to Beta for DNSEndpoint API" version: v1alpha1 authors: @ivankatliarchuk, @raffo, @szuecs creation-date: 2025-02-09