You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Issue:
None. Found while reviewing tigera/banzai-core#1791 / #1793, which fixed the same bug in CI.
Link to docs preview:
TBD (preview build)
SME review:
An SME has approved this change.
DOCS review:
A member of the docs team has approved this change.
Additional information:
helm template is client-only, so the projectcalico.org.v3 chart can't see the cluster's APIs and renders MutatingAdmissionPolicy at v1beta1. Kubernetes 1.36 serves only v1, so those objects fail to apply.
--validate (next / v3.33 install pages) renders v1, but fails on any re-run: the kubectl-applied CRDs have no Helm ownership metadata, so Helm refuses with ... exists and cannot be imported into the current release. Removed.
No flag (v3.32 install pages, next / v3.33 upgrade note) renders v1beta1 and fails on 1.36.
Fix: a note to add --api-versions admissionregistration.k8s.io/v1/MutatingAdmissionPolicy on 1.36+. 1.34 / 1.35 keep the default. Same approach as calico-private's manifests/generate.sh.
Verified on kind (Kubernetes 1.36.1, Helm v3.16.2, published projectcalico/projectcalico.org.v3 v3.32.2):
Command
Result
no flag
MAP rendered at v1beta1
--validate, fresh cluster
applies
--validate, re-run
CustomResourceDefinition "bgpconfigurations.projectcalico.org" ... exists and cannot be imported into the current release
--api-versions ..., re-run
applies
Not changed: CE 3.24-1 / 3.24-2 / 3.23-2. Those charts hard-code v1beta1 (no .Capabilities switch), so no flag helps; that needs a chart backport if 1.36 is supported there.
Merge checklist:
Deploy preview inspected wherever changes were made
1 paths audited Performance: 97 (🟢 up 19 from production) Accessibility: 98 (no change from production) Best Practices: 92 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports
The reason will be displayed to describe this comment to others. Learn more.
Thanks for catching this. The --validate removal is clearly right and I would keep that part as is.
On the --api-versions note, I would suggest branching the step on Kubernetes version instead, the way the Manifest tab of native-v3-crds.mdx already does. Three reasons:
The Manifest tab on that same page already splits into "If your cluster is based on Kubernetes 1.36 or later" and "If your cluster is based on Kubernetes 1.34 or 1.35". With the note, the two tabs present the same decision in two different shapes.
There are only two branches to write. Native v3 CRDs require Kubernetes 1.34 or later, so there is no long tail of versions to enumerate.
Notes are skippable, and the penalty for skipping this one is a failed install with a no matches for kind "MutatingAdmissionPolicy" error. A fork in the steps has to be read.
The main reason is the point you raised in Slack. As written, the note is only correct while the chart's fallback stays v1beta1. If the chart default flips to v1, the unflagged command that 1.34 and 1.35 users run starts failing, and the note becomes wrong in the other direction. If both branches carry an explicit --api-versions, nothing depends on the chart default at all, and the docs stay correct whichever way you and Casey land that question. If the policies later move into the operator, the flag becomes redundant rather than wrong.
Branching also lets the explanation go away. "Without it, Helm renders the MutatingAdmissionPolicy resources at v1beta1" is chart internals in the middle of a how-to, and the Concepts section of native-v3-crds.mdx already covers the alpha to beta to GA progression for anyone who wants it.
Suggestions below for the five pages where the v3 chart is a step on the main path. Two things I have not suggested changes for, with reasons in the inline comments:
The 3.32 pages, where the v3 chart is a tech preview tip rather than a step. First question there is whether 3.32 claims Kubernetes 1.36 support at all.
kubernetes-upgrade.mdx, which needs a bigger cleanup than this PR should carry.
One thing to verify before merge: your kind testing covered the 1.36 half, but the 1.34 or 1.35 command with an explicit v1beta1 flag is new and unverified.
Also flagging that the tigera deploy preview failed on this PR, while calico-docs-preview-next passed.
helm template is client-only, so the projectcalico.org.v3 chart renders
MutatingAdmissionPolicy at v1beta1, which 1.36 does not serve. --validate
fixed the first install but fails any re-run: the kubectl-applied CRDs lack
Helm ownership metadata. Use --api-versions on 1.36+ instead.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Replace the --api-versions note with explicit 1.36+ and 1.34/1.35
commands so the docs don't depend on the chart's fallback default.
Co-authored-by: Christopher Tauchen <ctauchen@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The prerequisites said v1beta1 on every 1.34+ cluster, contradicting the
new 1.36 commands: 1.36 serves only v1.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Tested the 1.34/1.35 command on kind (Kubernetes 1.35.1, MutatingAdmissionPolicy gate + v1beta1 enabled, Helm v3.16.2, chart v3.32.2):
Renders MAPs at v1beta1; kubectl apply --server-side succeeds, and again on re-run.
MAPs actually default: a new NetworkPolicy got tier: default, the tier label, and types: [Ingress].
The 1.36 command on the same cluster fails (no matches for kind "MutatingAdmissionPolicy" in version "admissionregistration.k8s.io/v1"), so the split is needed.
tigera preview failure was a stale base; fixed by rebase.
The link text names MutatingAdmissionPolicies, but its URL opens Kubernetes' Validating Admission Policy page. Point it to the Mutating Admission Policy reference so readers get the API and feature details described here.
Link points to Validating instead of Mutating Admission Policy
calico/operations/native-v3-crds.mdx:35
The link text names MutatingAdmissionPolicies, but its URL opens Kubernetes' Validating Admission Policy page. Point it to the Mutating Admission Policy reference so readers get the API and feature details described here.
Link points to Validating instead of Mutating Admission Policy
The link text names MutatingAdmissionPolicies, but its URL opens Kubernetes' Validating Admission Policy page. Point it to the Mutating Admission Policy reference so readers get the API and feature details described here.
Link points to Validating instead of Mutating Admission Policy
The link text names MutatingAdmissionPolicies, but its URL opens Kubernetes' Validating Admission Policy page. Point it to the Mutating Admission Policy reference so readers get the API and feature details described here.
This now says the v1 API is required on Kubernetes 1.36, but the v3.32 install step below still downloads manifests/calico-v3-crds.yaml. The published v3.32.2 file embeds every MutatingAdmissionPolicy and binding as admissionregistration.k8s.io/v1beta1, so kubectl apply fails on 1.36. Add a separate 1.36 path that uses a v1-rendered artifact (or explicitly limit this manifest installation method to 1.34–1.35).
This issue also appears on line 226 of the same file.
Split migration manifests by Kubernetes API version
The documented 1.34–1.35 path cannot follow this migration: v3.32.2's v3_projectcalico_org.yaml, applied at line 68, is generated with the v1 MutatingAdmissionPolicy capability and no v1beta1 counterpart is published. Those clusters therefore reject the first migration manifest. Split the command by Kubernetes version and provide a beta-rendered source for 1.34–1.35.
Provide beta-compatible manifests for Kubernetes 1.34–1.35
The manifest-install tab does not meet this 1.34–1.35 requirement. In v3.32.2, v3_projectcalico_org.yaml is generated with --api-versions admissionregistration.k8s.io/v1/MutatingAdmissionPolicy, and no v1beta1 variant is published, so the command at line 110 applies v1 resources that those clusters do not serve. Add a beta-compatible manifest path for 1.34–1.35 or restrict that tab to 1.36+.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
ctauchen
left a comment
Product Version(s):
Calico OSS next, v3.33, v3.32; Calico Enterprise next.
Issue:
None. Found while reviewing tigera/banzai-core#1791 / #1793, which fixed the same bug in CI.
Link to docs preview:
TBD (preview build)
SME review:
DOCS review:
Additional information:
helm templateis client-only, so theprojectcalico.org.v3chart can't see the cluster's APIs and renders MutatingAdmissionPolicy atv1beta1. Kubernetes 1.36 serves onlyv1, so those objects fail to apply.--validate(next / v3.33 install pages) rendersv1, but fails on any re-run: the kubectl-applied CRDs have no Helm ownership metadata, so Helm refuses with... exists and cannot be imported into the current release. Removed.v1beta1and fails on 1.36.--api-versions admissionregistration.k8s.io/v1/MutatingAdmissionPolicyon 1.36+. 1.34 / 1.35 keep the default. Same approach as calico-private'smanifests/generate.sh.Verified on kind (Kubernetes 1.36.1, Helm v3.16.2, published
projectcalico/projectcalico.org.v3v3.32.2):v1beta1--validate, fresh cluster--validate, re-runCustomResourceDefinition "bgpconfigurations.projectcalico.org" ... exists and cannot be imported into the current release--api-versions ..., re-runNot changed: CE 3.24-1 / 3.24-2 / 3.23-2. Those charts hard-code
v1beta1(no.Capabilitiesswitch), so no flag helps; that needs a chart backport if 1.36 is supported there.Merge checklist:
🤖 Generated with Claude Code