Skip to content

docs: correct the Gateway API version requirement - #2256

Open
m-altaifi wants to merge 2 commits into
cert-manager:masterfrom
m-altaifi:docs/gateway-api-v1-crd-requirement
Open

m-altaifi wants to merge 2 commits into
cert-manager:masterfrom
m-altaifi:docs/gateway-api-v1-crd-requirement

Conversation

@m-altaifi

Copy link
Copy Markdown
Contributor

Fixes #1623.

The note currently reads:

🚧 cert-manager 1.14+ is tested with v1 Kubernetes Gateway API. It should also work with v1beta1 and v1alpha2 because of resource conversion, but has not been tested with it.

That reads as though a cluster serving only v1beta1/v1alpha2 is supported. It isn't — cert-manager will not start:

  • pkg/controller/context.go imports gwapi "sigs.k8s.io/gateway-api/apis/v1" and calls d.ServerResourcesForGroupVersion(gwapi.GroupVersion.String()) at startup, returning the Gateway API CRDs do not seem to be present, but ExperimentalGatewayAPISupport is set to true when they are not.
  • The Gateway shim watches ctx.GWShared.Gateway().V1().Gateways(), so gateway.networking.k8s.io/v1 is the only version it lists and watches.

That is exactly the crash loop reported in cert-manager/cert-manager#6649, and the resolution there was that the cluster had to serve the v1 CRDs. Once they are installed, the reporters confirmed that Gateway resources authored as v1beta1 work fine, which is the part of the original sentence worth keeping.

So the replacement says the v1 CRDs are required, and that your own Gateway manifests may still be v1beta1/v1alpha2 because the API server converts between versions.

The same paragraph appears in usage/gateway.md and configuration/acme/http01/README.md. Per the repo README ("add it to docs/ and possibly to the specific version of cert-manager that's latest"), I changed content/docs/ and content/v1.19-docs/. The identical text is also in the v1.11–v1.18 snapshots; I left those alone as frozen docs for released versions, but happy to extend if you would rather have them consistent.

Testing

npm ci, then against the four changed files: cspell 0 issues, remark --frail exit 0. No links were added or changed.

The note said cert-manager should also work with v1beta1 and v1alpha2
because of resource conversion, which reads as though a cluster serving
only those versions is supported. It is not: cert-manager resolves
gwapi.GroupVersion from sigs.k8s.io/gateway-api/apis/v1 and calls
ServerResourcesForGroupVersion on it at startup, refusing to start when
the v1 CRDs are absent, and the Gateway shim watches
Gateway().V1().Gateways().

Say that the v1 CRDs are required, and keep the part that is true: the
Gateway manifests themselves may still be written as v1beta1 or
v1alpha2, because the API server converts between versions.

Signed-off-by: m-altaifi <magic.moha@icloud.com>
@cert-manager-prow cert-manager-prow Bot added the dco-signoff: yes Indicates that all commits in the pull request have the valid DCO sign-off message. label Sep 1, 2026
@cert-manager-prow

Copy link
Copy Markdown
Contributor

[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 wallrj 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:

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

@cert-manager-prow cert-manager-prow Bot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Sep 1, 2026
@netlify

netlify Bot commented Sep 1, 2026

Copy link
Copy Markdown

Deploy Preview for cert-manager ready!

Built without sensitive environment variables

Name Link
🔨 Latest commit 43389f1
🔍 Latest deploy log https://app.netlify.com/projects/cert-manager/deploys/6a980ae4063f9b00083354d9
😎 Deploy Preview https://deploy-preview-2256--cert-manager.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates that all commits in the pull request have the valid DCO sign-off message. size/M Denotes a PR that changes 30-99 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Claim about v1beta1/v1alpha2 support for gateway api is misleading

2 participants