docs: multi-cluster shared DNS records

[mloiseleur]

What does it do ?

New page docs/advanced/multi-cluster-shared-records.md, documenting how several ExternalDNS instances can publish the same hostname.

It also states what is not supported:
=> two instances each contributing targets to one record set.

The ownership TXT record is per DNS name and carries one owner, so targets cannot be attributed per cluster — nor removed when a cluster goes away.

Cross-links from the AWS routing-policies tutorial and operational best practices, plus an mkdocs.yml nav entry.

Motivation

Closes #1441. The use cases raised there — failover clusters, blue/green, multi-region — are covered by the documented patterns.

More

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

Note: The AWS pattern was tested locally with LocalStack, see first comment below.

[kubernetes-prow]

[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 szuecs 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]

Coverage Report for CI Build 30719855253

Coverage increased (+0.005%) to 81.702%

Details

• Coverage increased (+0.005%) from the base build.
• Patch coverage: No coverable lines changed in this PR.
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	21390
Covered Lines:	17476
Line Coverage:	81.7%
Coverage Strength:	1457.03 hits per line

---

💛 - Coveralls

[mloiseleur]

End-to-end validation against LocalStack Route 53

Validated the documented patterns against a real Route 53 API (LocalStack 4.0.3 community) with a kind cluster (docs/snippets/tutorials/aws-localstack/kind.yaml) for the crd source. Two ExternalDNS instances from source, same hosted zone, each scoped to its own namespace to emulate two clusters:

go run main.go --provider=aws --source=crd --registry=txt \
  --txt-owner-id=cluster-a --namespace=cluster-a \
  --domain-filter=example.com --policy=sync --once
# AWS_ENDPOINT_URL=http://127.0.0.1:4566 (LocalStack); same run for cluster-b

Pattern C — two DNSEndpoints, same dnsName: app.example.com, distinct setIdentifier, aws/weight: "50". Resulting zone matches the doc exactly, ownership TXT inheriting both the set identifier and the weight:

NAME                TYPE  SET-ID     WEIGHT  VALUE
a-app.example.com.  TXT   cluster-a  50      "heritage=external-dns,external-dns/owner=cluster-a,..."
a-app.example.com.  TXT   cluster-b  50      "heritage=external-dns,external-dns/owner=cluster-b,..."
app.example.com.    A     cluster-a  50      198.51.100.10
app.example.com.    A     cluster-b  50      203.0.113.10

• ✅ Weight shift to 90/10, and weight 0 (record kept, Weight: 0, not deleted) — each instance only ever upserts its own record set.
• ✅ Deleting cluster B's DNSEndpoint deletes exactly its own A + TXT set; cluster A untouched.
• ✅ Both instances converge — All records are already up to date, no churn.
• ✅ Pattern A: multi-target DNSEndpoint → single A record set with both values.
• ✅ Not supported (merging targets): same hostname, no set identifier, two owners — cluster A creates it, cluster B skips and reports All records are already up to date, zone keeps A's target only.