docs(proposal): annotations support graduation to beta by ivankatliarchuk · Pull Request #5080 · kubernetes-sigs/external-dns

ivankatliarchuk · 2025-02-09T20:34:04Z

Description

No issues to date. But there is definitely an ask and appetite to improve annotation processing. It may take a while but worth to have a plan in place, so community would be able to help to improve annotation processing.

Currently 10 open pull requests 10 open https://github.com/kubernetes-sigs/external-dns/pulls?q=is%3Apr+is%3Aopen+annotation

And 40+ open https://github.com/kubernetes-sigs/external-dns/issues?q=is%3Aissue%20state%3Aopen%20annotations

Mane goals

worth to have/initiate at least a discussion
standard interface and we could have some automation to generate docs from code
easy to add/deprecate/graduate an annotation or group of annotations

The proposal to merge to master 2025-Mar-09 with the decision

Checklist

Unit tests updated
End user documentation updated

Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com>

ivankatliarchuk · 2025-02-09T20:59:52Z

/label tide/merge-method-squash

szuecs

Thanks for the effort I think this can enhance safety and usability of external-dns!

I think there are some things clearly missing:

How do we make sure that annotation graduation has a level of objective quality increase?
How do we handle this with providers that are out of tree, which is one of our top priorities?

As long we have no good answers to these questions we should not invest time into an implementation.

szuecs · 2025-02-14T17:48:49Z

docs/proposal/annotations-graduate-to-beta.md

+
+- **Deprecation Policy and Migration Path**: Establish a clear deprecation policy for outdated annotations. Implement mechanisms to log warnings when deprecated annotations are used and provide comprehensive migration guides to assist users in transitioning to supported annotations.
+
+- **Conflict Detection and Resolution**: Enhance the annotation processing logic to detect conflicting annotations proactively. Implement validation rules that either prevent conflicts at the time of deployment or resolve them in a predictable manner, ensuring consistent behavior.


Do you suggest to implement a validation webhook or something else?

Not exactly. Validation webhook could be a future. At the moment annotations in external-dns just a string, but could be a struct, which could have a simple validation logic. If validation fail, we not processing annotation. Something basic

szuecs · 2025-02-14T17:49:51Z

docs/proposal/annotations-graduate-to-beta.md

+
+- No automated documentation for available annotations.
+- Unclear strategy for supporting different API versions.
+- No defined transition path from `external-dns.alpha.kubernetes.io` annotations to a stable format.


Agree, maybe we should define alpha/beta/stable groups.

We could follow same path as for CRD, at the moment just to standartise annotation processing. I will have a look around, most likely this groups are already provided by kubernetes itself.

szuecs · 2025-02-14T17:50:56Z

docs/proposal/annotations-graduate-to-beta.md

+- No defined transition path from `external-dns.alpha.kubernetes.io` annotations to a stable format.
+- Lack of standardization among annotations.
+
+By adopting a structured approach similar to `ingress-nginx`, we can address these issues and improve the overall functionality and user experience of `external-dns`.


can you link or tell more about their approach? I did not find anything browsing their GH repo

https://github.com/kubernetes/ingress-nginx/tree/main/internal/ingress/annotations

Exactly it. All annotaions well known, each annotations grouped (this could be part of implementation) contains validator and documentation, as well as each providers or sources supported. So we could have autoamted documentation from the code directly.

I'll add this to documentation

szuecs · 2025-02-14T17:54:45Z

docs/proposal/annotations-graduate-to-beta.md

+
+- Introduce automated documentation for supported annotations.
+- Define a strategy for handling multiple API versions in annotations.
+- Ensure backward compatibility where possible.


Backward compatibility is the most important IMO, so I would drop the "where possible".
I think a minor release version increase and a deprecation note for a lifecycle change.
I would suggest something like: alpha -> alpha+beta -> beta -> beta + stable -> stable and each "->" is one minor version increase. So I would suggest that a controller update will have both working "alpha+beta", but log warning for "alpha" annotations in the group of "alpha+beta" graduation step. After all annotations a migrated to "beta" in a cluster that are read by external-dns instance there is no warning log and the next controller update to "beta" is fine.

I'll add this to the decision

szuecs · 2025-02-14T17:55:37Z

docs/proposal/annotations-graduate-to-beta.md

+
+### Non-Goals
+
+- Establish a migration plan from `external-dns.alpha.kubernetes.io` to `external-dns.beta.kubernetes.io`.


IMO we should have a clear idea how to execute the change, so I would like to have it also as goal.

I'll rename proposal. Let's leave migration for a future. At the moment code is tightly coupled with annotations in sources, so clear migration will be a lot of code changes + support different versions which may doulbe the size of codebase.

szuecs · 2025-02-14T18:15:23Z

docs/proposal/annotations-graduate-to-beta.md

+    - _As a maintainer_, I want to define and communicate a clear lifecycle for annotation versions, so that contributors and users understand when alpha annotations will be deprecated and how to migrate.
+	- _As a maintainer_, I want to ensure that annotation behavior is consistent across supported DNS providers (e.g., AWS Route 53, Cloudflare, oogle DNS), so that users do not experience unexpected inconsistencies depending on their provider.
+	- _As a maintainer_, I want to establish validation rules that reject conflicting or redundant annotations at runtime, so that users do not face unpredictable behavior due to overlapping DNS rules.
+	- _As a maintainer_, I want to collaborate with other Kubernetes SIGs (e.g., SIG-Network, SIG-Auth) to align annotation standards,


We are a project of sig-network so "other Kubernetes SIGs" is not sig-network.

Where do you see collaboration needs? Is there any trial to standardize annotations?

szuecs · 2025-02-14T18:21:07Z

docs/proposal/annotations-graduate-to-beta.md

+
+### Behavior
+
+-   `external-dns` should recognize both `alpha` and `beta` annotations where applicable.


What does it exactly mean?

szuecs · 2025-02-14T18:21:48Z

docs/proposal/annotations-graduate-to-beta.md

+
+-   `external-dns` should recognize both `alpha` and `beta` annotations where applicable.
+-   Warnings should be logged when deprecated annotations are used.
+-   Warnings should be logged when annotation is not supported by source or provider.


If the provider is out of tree we don't know their deployed version nor if an annotation is supported or exists.
How do you make sure it works?

szuecs · 2025-02-14T18:23:52Z

docs/proposal/annotations-graduate-to-beta.md

+-   `external-dns` should recognize both `alpha` and `beta` annotations where applicable.
+-   Warnings should be logged when deprecated annotations are used.
+-   Warnings should be logged when annotation is not supported by source or provider.
+-   Future major versions should drop support for `alpha` annotations after a defined period.


I would suggest to use minor versions instead of major versions. In Go major versions are breaking changes for exposed functions/types/... and if we have 50 annotations and increase in small groups we will soon have v50, which IMO makes no sense.

szuecs · 2025-02-14T18:25:08Z

docs/proposal/annotations-graduate-to-beta.md

+### Alternative 2: Keep Annotations in Alpha Permanently
+
+-   Pros: No migration burden for users.
+-   Cons: Lack of stability signals to users, discouraging adoption.


I don't see how we can really make sure that alpha is better than beta. What is the signal of quality to use to make this change?

ivankatliarchuk · 2025-02-22T08:52:26Z

Not abandonned. Still working out things

k8s-triage-robot · 2025-07-23T08:01:48Z

The Kubernetes project currently lacks enough contributors to adequately respond to all PRs.

This bot triages PRs according to the following rules:

After 90d of inactivity, lifecycle/stale is applied
After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
After 30d of inactivity since lifecycle/rotten was applied, the PR is closed

You can:

Mark this PR as fresh with /remove-lifecycle stale
Close this PR with /close
Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

ivankatliarchuk · 2025-07-24T12:08:39Z

Still working on ir

k8s-triage-robot · 2025-08-23T12:10:11Z

The Kubernetes project currently lacks enough active contributors to adequately respond to all PRs.

This bot triages PRs according to the following rules:

After 90d of inactivity, lifecycle/stale is applied
After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
After 30d of inactivity since lifecycle/rotten was applied, the PR is closed

You can:

Mark this PR as fresh with /remove-lifecycle rotten
Close this PR with /close
Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

ivankatliarchuk · 2025-09-02T14:41:58Z

Still WIP

k8s-triage-robot · 2025-09-22T12:51:51Z

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages PRs according to the following rules:

After 90d of inactivity, lifecycle/stale is applied
After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
After 30d of inactivity since lifecycle/rotten was applied, the PR is closed

You can:

Reopen this PR with /reopen
Mark this PR as fresh with /remove-lifecycle rotten
Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close

k8s-ci-robot · 2025-09-22T12:51:59Z

@k8s-triage-robot: Closed this PR.

Details

In response to this:

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages PRs according to the following rules:

After 90d of inactivity, lifecycle/stale is applied

After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied

After 30d of inactivity since lifecycle/rotten was applied, the PR is closed

You can:

Reopen this PR with /reopen

Mark this PR as fresh with /remove-lifecycle rotten

Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

ivankatliarchuk · 2025-10-11T10:35:28Z

/reopen

k8s-ci-robot · 2025-10-11T10:35:34Z

@ivankatliarchuk: Reopened this PR.

Details

In response to this:

/reopen

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

k8s-ci-robot · 2025-10-11T10:35:40Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign mloiseleur for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

coveralls · 2025-10-11T10:42:31Z

Pull Request Test Coverage Report for Build 18428296455

Details

0 of 0 changed or added relevant lines in 0 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage remained the same at 78.581%

Totals
Change from base Build 18416862229:	0.0%
Covered Lines:	15845
Relevant Lines:	20164

💛 - Coveralls

k8s-triage-robot · 2025-11-10T11:29:07Z

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages PRs according to the following rules:

After 90d of inactivity, lifecycle/stale is applied
After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
After 30d of inactivity since lifecycle/rotten was applied, the PR is closed

You can:

Reopen this PR with /reopen
Mark this PR as fresh with /remove-lifecycle rotten
Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close

k8s-ci-robot · 2025-11-10T11:29:13Z

@k8s-triage-robot: Closed this PR.

Details

In response to this:

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages PRs according to the following rules:

After 90d of inactivity, lifecycle/stale is applied

After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied

After 30d of inactivity since lifecycle/rotten was applied, the PR is closed

You can:

Reopen this PR with /reopen

Mark this PR as fresh with /remove-lifecycle rotten

Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

docs(proposal): annotations support graduation to beta

5563fd9

Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com>

k8s-ci-robot requested review from mloiseleur and szuecs February 9, 2025 20:34

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Feb 9, 2025

ivankatliarchuk mentioned this pull request Feb 9, 2025

feat: configure arbitrary provider-specific properties via annotations #4875

Closed

2 tasks

docs(proposal): annotations support graduation to beta

e9f91d8

Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com>

k8s-ci-robot added the tide/merge-method-squash Denotes a PR that should be squashed by tide when it merges. label Feb 9, 2025

szuecs reviewed Feb 14, 2025

View reviewed changes

ivankatliarchuk mentioned this pull request Mar 17, 2025

chore(source): code cleanup #5189

Closed

2 tasks

ivankatliarchuk marked this pull request as draft April 24, 2025 07:05

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Apr 24, 2025

ivankatliarchuk mentioned this pull request Jun 6, 2025

feat(gateway-api): add ability to override target on *Route resources #5319

Closed

2 tasks

k8s-ci-robot added the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label Jul 23, 2025

k8s-ci-robot added lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed. and removed lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. labels Aug 23, 2025

k8s-ci-robot closed this Sep 22, 2025

k8s-ci-robot reopened this Oct 11, 2025

k8s-ci-robot added the docs label Oct 11, 2025

ivankatliarchuk mentioned this pull request Oct 12, 2025

Documentation gap: Provider-specific annotations placement for Gateway API sources #5901

Closed

lexfrei mentioned this pull request Oct 23, 2025

docs(proposal): Gateway API annotation placement clarity proposal #5919

Merged

k8s-ci-robot closed this Nov 10, 2025


		- Deprecation Policy and Migration Path: Establish a clear deprecation policy for outdated annotations. Implement mechanisms to log warnings when deprecated annotations are used and provide comprehensive migration guides to assist users in transitioning to supported annotations.

		- Conflict Detection and Resolution: Enhance the annotation processing logic to detect conflicting annotations proactively. Implement validation rules that either prevent conflicts at the time of deployment or resolve them in a predictable manner, ensuring consistent behavior.


		### Non-Goals

		- Establish a migration plan from `external-dns.alpha.kubernetes.io` to `external-dns.beta.kubernetes.io`.


		### Behavior

		- `external-dns` should recognize both `alpha` and `beta` annotations where applicable.

Conversation

ivankatliarchuk commented Feb 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ivankatliarchuk commented Feb 9, 2025

Uh oh!

szuecs left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ivankatliarchuk commented Feb 22, 2025

Uh oh!

k8s-triage-robot commented Jul 23, 2025

Uh oh!

ivankatliarchuk commented Jul 24, 2025

Uh oh!

k8s-triage-robot commented Aug 23, 2025

Uh oh!

ivankatliarchuk commented Sep 2, 2025

Uh oh!

k8s-triage-robot commented Sep 22, 2025

Uh oh!

k8s-ci-robot commented Sep 22, 2025

Uh oh!

ivankatliarchuk commented Oct 11, 2025

Uh oh!

k8s-ci-robot commented Oct 11, 2025

Uh oh!

k8s-ci-robot commented Oct 11, 2025

Uh oh!

coveralls commented Oct 11, 2025

Pull Request Test Coverage Report for Build 18428296455

Details

💛 - Coveralls

Uh oh!

k8s-triage-robot commented Nov 10, 2025

Uh oh!

k8s-ci-robot commented Nov 10, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ivankatliarchuk commented Feb 9, 2025 •

edited

Loading