feat(source/gateway-api)!: migrate Gateway and HTTPRoute to v1

[System-Arch]

Summary

This reverts the Kubernetes API interactions for Gateway and HTTPRoute objects from v1beta1 back to v1, undoing PR #4610 (July 2024).

Background

The original revert to v1beta1 was made because GKE clusters were not yet serving v1 CRDs, causing crash loops for a significant portion of the user base (#4366). At the time, the maintainer noted:

"Dropping v1beta1 support and moving fully to v1 in external-dns will probably happen at some point, but it'll be at least a year from now."

That was nearly two years ago. The situation has now reversed:

• GKE now serves v1 Gateway API CRDs. The original blocker no longer applies.
• Modern clusters are dropping v1beta1. Gateway API v1.5.0 introduced a ValidatingAdmissionPolicy that prevents downgrades below v1.5. Clusters running current Gateway API CRDs may no longer serve v1beta1.
• ExternalDNS is broken on modern clusters. Users report fatal crashes: failed to sync *v1beta1.Gateway: context deadline exceeded (Not working configuration Gateway API  #4768). This is the mirror image of the original 0.14.1 causing crash loopback related to v1.Gateway #4366.

Since v1 Gateway and HTTPRoute have been available since Gateway API v1.0.0 (October 2023), this change is safe for any cluster running Gateway API 1.0 or later.

Changes

• source/gateway.go: imports, informer type, and function signatures changed from v1beta1 to v1
• source/gateway_httproute.go: informer factory call, embedded informer type, and TypeMeta APIVersion moved to v1
• 5 test files: Gateway fixtures changed from v1beta1.Gateway to v1.Gateway; client calls from GatewayV1beta1() to GatewayV1()
• docs/sources/gateway-api.md: version documentation updated

Impact

This is a breaking change for those sites that only have v1beta1 CRDs for Gateway and HTTPRoute as summarized in the following table:

Cluster	Status
Gateway API ≥ 1.0.0 (Oct 2023)	✅both v1 and v1beta1 served — PR works
Gateway API < 1.0.0	❌ v1 not served — PR breaks these clusters

Scope

This change intentionally covers only Gateway and HTTPRoute. TLSRoute, TCPRoute, and UDPRoute remain at v1alpha2. TLSRoute's migration to v1 depends on Gateway API v1.5.0+ and is tracked separately in #6247.

Fixes #6290

Checklist

• Unit tests updated
• End user documentation updated

[k8s-ci-robot]

Welcome @System-Arch!

It looks like this is your first PR to kubernetes-sigs/external-dns 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/external-dns has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[k8s-ci-robot]

Hi @System-Arch. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

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.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: mloiseleur / name: Michel Loiseleur (e350da4)
• ✅ login: System-Arch / name: System-Arch (0106793, 9df1b2e, a74c438, bd1d6ef, db483bc, e350da4)

[ivankatliarchuk]

The API server handles conversion transparently -> if objects were stored as v1beta1 but v1 is served, you can still list/watch via v1 without issue. So storedVersions containing v1beta1 does not prevent ExternalDNS from using v1.

So the documentation's framing of "requires Gateway API v1.0.0" is an approximation. The real requirement is:

The Gateway and HTTPRoute CRDs must have v1 in their spec.versions with served: true.

By any chance could you add to description evidences similar to #5611 (comment) with spec.versions[].served and status.storedVersions

Could you share similar results for this PR #5085 (comment) for beta versions that not working currently?

[ivankatliarchuk]

CLA needs signing

[System-Arch]

The API server handles conversion transparently -> if objects were stored as v1beta1 but v1 is served, you can still list/watch via v1 without issue. So storedVersions containing v1beta1 does not prevent ExternalDNS from using v1.

So the documentation's framing of "requires Gateway API v1.0.0" is an approximation. The real requirement is:

The Gateway and HTTPRoute CRDs must have v1 in their spec.versions with served: true.

By any chance could you add to description evidences similar to #5611 (comment) with spec.versions[].served and status.storedVersions

Could you share similar results for this PR #5085 (comment) for beta versions that not working currently?

Hi @ivankatliarchuk ,

Thank you for reviewing this change. My Gateway and HTTProute CRDs do indeed show 'v1' (and only 'v1') in spec.versions and have served:true. Note this is with the v1.5.0 Gateway API standard CRDs and the v1.4.1 experimental CRD for TLSroute (to keep Cilium 1.19) happy.

Regarding your second question, I saw an issue about a week ago when I first started integrating Cilium Gateway API support into a self-hosted v1.35.1 K8s cluster. At that time, I believe I saw error messages similar to those shown in #5611 where ExternalDNS pods were crashing at startup due to not finding v1apha2 CRDs for Gateway and HTTProute. I subsequently created a custom build of External DNS with the change proposed in this PR (and support for v1 TLSroute, which was not included in the PR), which appeared to resolve the issue, and things worked as expected (after working out other kinks).

In response to your query, I reverted back to the 0.20.0 version of External DNS and, much to my surprise (but in alignment with your assertions), I was unable to reproduce the issue, and things appear to still be working correctly. Thus, you can close or defer this PR if you feel it is still premature to upgrade External DNS as proposed. If you would like to still consider the change (it's line-for-line the same as what was accepted and reverted two years ago), let me know and I'll complete the CLA.

Thanks for your time and assistance.

[ivankatliarchuk]

Thanks for confirming.

Whether to support v1beta1 vs v1 - is not about just bumping dependencies. Rest is described in this PR review with evidences has to be provided #6291 (review)

[mloiseleur]

It's true it has been a lonnnng time we are with this v1beta.
@abursavich Any comments ?

[abursavich]

The added empty lines in import blocks bug me, but meh. LGTM.

[ivankatliarchuk]

The PR opener is just completely ignore what being asked

• sign CLA
• provide evidences to validate which version served/stored
• evidences that is fixing the bug described in the issue

[abursavich]

I can't help with signing the CLA, but... FWIW, this is something we intended to do long ago, but certain cloud providers held us back because they were slow to upgrade their CRDs to include v1.

The current CRDs provided in the latest Gateway API release (v1.5.1) still include the served v1beta1 definitions (e.g. Gateway and HTTPRoute). I don't know why cloud providers would go out of their way to remove the v1beta1 definitions or change them to unserved, but I've seen crazier things.

The v1 api has been available since v1.0.0 on Oct 31, 2023 and included Gateway, GatewayClass, and HTTPRoute from the start. GRPCRoute graduated to v1 with v1.1.0 on May 8, 2024. TLSRoute and ListenerSet graduated to v1 in v1.5.0 on February 26, 2026 (only 3 weeks ago).

⚠️ The recentness of of TLSRoute's move to v1 does give me pause as this will be a breaking change for anyone using an older version. Since GKE was one of the problem providers last time and is mentioned in the description of this PR, I'm using it as an example. GKE updates the CRDs with as part of cluster upgrades. You can't upgrade the CRDs out of band with GKE releases. The last mention of upgraded Gateway API CRDs in the GKE release notes is to v1.3 CRDs in GKE version 1.33.2-gke.1335000 on July 28, 2025. It's possible that it's been updated since then and they left it out of the release notes, but I cannot confirm.

/lgtm cancel

I would be okay with merging this if TLSRoute was put back on v1beta1.

When this first became an issue, I thought about writing an adapter that would monitor and use whichever API version is available in the cluster. It seemed like overkill at the time and I wouldn't be available to work on it for the next two or three weeks, but I'd be down to pick that back up next month since this seems like it may continue to be an issue with the evolution of the Gateway API.

[ivankatliarchuk]

It's not providers, the Gateway API does not have deprecation with api versions and supported period. Example istio https://istio.io/latest/docs/releases/supported-releases/#support-status-of-istio-releases.

So basically, nothing forces GCP to actually switch to latest apiversion.

I could be wrong

[AndrewCharlesHay]

Hard blockers before anything else

CLA needs signing and a rebase is needed — k8s-ci-robot flagged both. Nothing else matters until those are done.

On the TLSRoute confusion

@abursavich's /lgtm cancel comment says "I would be okay with merging this if TLSRoute was put back on v1beta1" — but TLSRoute was never at v1beta1 in this repo, it's at v1alpha2, and this PR doesn't touch it. TLSRoute stays at v1alpha2 throughout. I think the concern got mis-stated; the actual concern seems to be about whether cloud providers have caught up to v1 for Gateway and HTTPRoute specifically, which is a separate question. Worth clarifying so the thread doesn't stay unresolved on a misread.

On the evidence request

@ivankatliarchuk's ask is reasonable — for a change that breaks users on old clusters, showing spec.versions[].served output is a fair bar. The author confirmed they couldn't reproduce the original crash on 0.20.0, which weakens the "fixes a regression" framing. But the direction is still correct: the PR description references real user crash reports in #4768, and v1 has been available for 1.5 years (since Gateway API v1.0, October 2023). The original v1beta1 revert was explicitly described as temporary.

On the code

The change is clean. One thing worth noting: removing the explicit cast v1.HTTPRoute(clone) in gateway_httproute.go is correct — in gateway-api, v1beta1.HTTPRoute was always a type alias for v1.HTTPRoute, so the cast was already a no-op. The import cleanup is tidy.

One doc gap

The new docs say TLSRoute "has not yet graduated to v1 in the version of Gateway API used by ExternalDNS" — but TLSRoute did graduate to v1 in Gateway API v1.5.0 (February 26, 2026, three weeks ago). The statement is technically true for ExternalDNS's current dependency version, but a follow-up issue/PR to migrate TLSRoute to v1 should probably be tracked explicitly so it doesn't get forgotten again like Gateway/HTTPRoute did.

Summary

Sign the CLA, rebase, and provide the kubectl get crd gateways.gateway.networking.k8s.io -o yaml evidence @ivankatliarchuk asked for. The change itself is sound.

[System-Arch]

The added empty lines in import blocks bug me, but meh. LGTM.

Hi @abursavich,
I have removed the empty lines in import statements as suggested. Is there anything else I need to do to wrap up this PR? Thanks

[mloiseleur]

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: abursavich, mloiseleur

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

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [mloiseleur]

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

[ivankatliarchuk]

/lgtm

[ivankatliarchuk]

Fixes #6290