docs(proposal): externaldns api graduation to beta

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
 ---
 ```

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

@@ -0,0 +1,164 @@
+```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/<apiVersion> 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/[email protected])
+4. TBD
+5. TBD
+
+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
+│   │   ├── 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
+```
+
+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
+
+_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.