fix(annotations)!: require --annotation-prefix to be set explicitly to prevent silent DNS record deletion

[ivankatliarchuk]

What does it do ?

Relates #6424
Relates #6449

• --annotation-prefix is now a required flag with no default; omitting it causes a hard startup failure via config validation
• The validation error message explains the breaking prefix change and gives both migration paths (old prefix for unmigrated clusters, new prefix once migration is complete)
• NewConfig() now returns a true zero-value struct — all defaults belong in flag binding, not the constructor
• StringMapVar in the flag binder initializes nil maps before registering with kingpin, removing the need for any map pre-initialization in NewConfig()
• Tests updated throughout to pass --annotation-prefix explicitly, reflecting the new required-flag contract

Motivation

• The default annotation prefix changed from external-dns.alpha.kubernetes.io/ to external-dns.kubernetes.io/ with no migration gate
• Users upgrading without updating their resource annotations would silently lose all DNS records: the controller would see owned TXT records but no sources claiming them, triggering deletion
• The failure was completely silent — no error, no warning, just records deleted on the first sync loop

  ┌───────────────────────────────────┬──────────────────────────────────────────────────┬──────────────────────────────────────────────────────┐
  │             Dimension             │      Default (external-dns.kubernetes.io/)       │             Empty (required, our change)             │
  ├───────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────────────────────────────┤
  │ Startup with no flag set          │ Silently continues                               │ Hard fails with actionable error                     │
  ├───────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────────────────────────────┤
  │ Upgrade experience                │ Transparent — DNS records deleted with no signal │ Deployment fails to start — no sync loop runs        │
  ├───────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────────────────────────────┤
  │ DR risk                           │ High — deletion happens before anyone notices    │ None — nothing runs until operator acts              │
  ├───────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────────────────────────────┤
  │ Time to detect                    │ After DNS records are already gone               │ Immediately at pod startup                           │
  ├───────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────────────────────────────┤
  │ Operator action required          │ None — that's the problem                        │ Explicit flag must be set                            │
  ├───────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────────────────────────────┤
  │ Helm/GitOps rollout               │ Rolls out successfully, deletes records          │ Rollout fails, old pod stays up (if rolling update)  │
  ├───────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────────────────────────────┤
  │ Migration path clarity            │ None — no signal that a migration exists         │ Error message explains both paths                    │
  ├───────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────────────────────────────┤
  │ Backward compat with alpha prefix │ Broken silently                                  │ Broken loudly — same end state, different visibility │
  ├───────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────────────────────────────┤
  │ Future default restoration        │ N/A (already defaulted)                          │ Possible once ecosystem has migrated                 │
  ├───────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────────────────────────────┤
  │ Blast radius                      │ All DNS records for unmigrated clusters          │ Zero — nothing changes until operator intervenes     │
  └───────────────────────────────────┴──────────────────────────────────────────────────┴──────────────────────────────────────────────────────┘

More

• Yes, this PR title follows Conventional Commits
• Yes, I added unit tests
• Yes, I updated end user documentation accordingly

[coveralls]

Coverage Report for CI Build 27496709866

Coverage decreased (-0.06%) to 81.585%

Details

• Coverage decreased (-0.06%) from the base build.
• Patch coverage: No coverable lines changed in this PR.
• 37 coverage regressions across 3 files.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

37 previously-covered lines in 3 files lost coverage.

File	Lines Losing Coverage	Coverage
execute.go	33	66.67%
flags/binders.go	2	95.74%
controller.go	2	93.39%

---

Coverage Stats

Relevant Lines:	21005
Covered Lines:	17137
Line Coverage:	81.59%
Coverage Strength:	1484.22 hits per line

---

💛 - Coveralls

[ivankatliarchuk]

I've added file scripts/migrate-annotation-prefix.sh. However, I'm not sure if we should provide anything. As we have no idea how end users environments looks like. Too many ways to deploy things to kubernetes.

[mloiseleur]

I've added file scripts/migrate-annotation-prefix.sh. However, I'm not sure if we should provide anything.

Nowadays, there are so many ways to send resources
=> I think we should not provide a migration tool.

That said, helping our users in this migration is a good idea 👍.

🤔 Instead of providing a migrate-annotation-prefix.sh, wdyt of providing a list-annotated-resources.sh that would list resources with previous or current annotations? Something to help users to choose its prefix and get a quick view of how many resources should be updated.

[ivankatliarchuk]

Instead of providing a migrate-annotation-prefix.sh, wdyt of providing a list-annotated-resources.sh that would list resources with previous or current annotations? Something to help users to choose its prefix and get a quick view of how many resources should be updated.

Agree on that. I was thinking same way. Will re-do it

[ivankatliarchuk]

Made the script read only, it will output only resources and annotations that needs adding

[mloiseleur]

/lgtm

[k8s-ci-robot]

New changes are detected. LGTM label has been removed.

[k8s-ci-robot]

[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 ask for approval from mloiseleur. 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