Skip to content

Fix v3 CRD chart helm template commands for Kubernetes 1.36 #3046

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lwr20 merged 4 commits into from
Oct 1, 2026
Merged

Fix v3 CRD chart helm template commands for Kubernetes 1.36 #3046

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
102e18c
Fix v3 CRD chart commands for Kubernetes 1.36
lwr20 Sep 30, 2026
35cb06c
Branch v3 CRD chart step on Kubernetes version
lwr20 Sep 30, 2026
b674ee8
Say which MutatingAdmissionPolicy API each Kubernetes version needs
lwr20 Oct 1, 2026
bf403aa
Link MutatingAdmissionPolicies to the mutating admission policy page
lwr20 Oct 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion calico-enterprise/getting-started/install-on-clusters/kubernetes/helm.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,8 +95,16 @@ To install a standard $[prodname] cluster with Helm:

1. Install the necessary custom resource definitions.

If your cluster is based on Kubernetes 1.36 or later:
Comment thread
lwr20 marked this conversation as resolved.

```bash
helm template calico-crds projectcalico.org.v3-$[chart_version_name].tgz --api-versions admissionregistration.k8s.io/v1/MutatingAdmissionPolicy | kubectl apply --server-side -f -
```

If your cluster is based on Kubernetes 1.34 or 1.35:

```bash
helm template calico-crds projectcalico.org.v3-$[chart_version_name].tgz --validate | kubectl apply --server-side -f -
helm template calico-crds projectcalico.org.v3-$[chart_version_name].tgz --api-versions admissionregistration.k8s.io/v1beta1/MutatingAdmissionPolicy | kubectl apply --server-side -f -
```

1. Install the Tigera Operator using the Helm 3 chart:
Expand Down
4 changes: 2 additions & 2 deletions calico-enterprise/operations/native-v3-crds.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,12 +32,12 @@ When using native `projectcalico.org/v3` CRDs:

### Validation and defaulting

When using native `projectcalico.org/v3` CRDs, resource validation and defaulting are handled by native CRD validation and defaulting, as well as ValidatingAdmissionPolicies and MutatingAdmissionPolicies. $[prodname] uses [MutatingAdmissionPolicies](https://kubernetes.io/docs/reference/access-authn-authz/validating-admission-policy/) for defaulting, which require the beta `admissionregistration.k8s.io/v1beta1` API. That API is available in **Kubernetes 1.34 and later**. On Kubernetes 1.33 and earlier, MutatingAdmissionPolicy is only available as an alpha API (`v1alpha1`), which $[prodname] does not support. On Kubernetes 1.34 and 1.35, you must enable the `MutatingAdmissionPolicy` feature gate on your Kubernetes API server before using native `projectcalico.org/v3` CRDs, as it is not enabled by default. On Kubernetes 1.36 and later, the feature is GA and enabled by default.
When using native `projectcalico.org/v3` CRDs, resource validation and defaulting are handled by native CRD validation and defaulting, as well as ValidatingAdmissionPolicies and MutatingAdmissionPolicies. $[prodname] uses [MutatingAdmissionPolicies](https://kubernetes.io/docs/reference/access-authn-authz/mutating-admission-policy/) for defaulting, which require **Kubernetes 1.34 or later**: the beta `admissionregistration.k8s.io/v1beta1` API on Kubernetes 1.34 and 1.35, or the GA `admissionregistration.k8s.io/v1` API on 1.36 and later. On Kubernetes 1.33 and earlier, MutatingAdmissionPolicy is only available as an alpha API (`v1alpha1`), which $[prodname] does not support. On Kubernetes 1.34 and 1.35, you must enable the `MutatingAdmissionPolicy` feature gate on your Kubernetes API server before using native `projectcalico.org/v3` CRDs, as it is not enabled by default. On Kubernetes 1.36 and later, the feature is GA and enabled by default.

## Before you begin

- A Kubernetes cluster **without** $[prodname] installed, or a cluster where you are performing a fresh install. To migrate an existing cluster from API server mode, see [Migrate from API server to native CRDs](crd-migration.mdx).
- **Kubernetes 1.34 or later.** $[prodname] uses the beta `admissionregistration.k8s.io/v1beta1` MutatingAdmissionPolicy API for defaulting, which is not available on Kubernetes 1.33 and earlier (where MutatingAdmissionPolicy is alpha only). On Kubernetes 1.34 and 1.35, the `MutatingAdmissionPolicy` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) must be enabled on the API server, as it is not enabled by default. On Kubernetes 1.36 and later, the feature is GA and enabled by default.
- **Kubernetes 1.34 or later.** $[prodname] uses MutatingAdmissionPolicies for defaulting, which need the beta `admissionregistration.k8s.io/v1beta1` API on Kubernetes 1.34 and 1.35, or the GA `admissionregistration.k8s.io/v1` API on 1.36 and later. Neither is available on Kubernetes 1.33 and earlier (where MutatingAdmissionPolicy is alpha only). On Kubernetes 1.34 and 1.35, the `MutatingAdmissionPolicy` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) must be enabled on the API server, as it is not enabled by default. On Kubernetes 1.36 and later, the feature is GA and enabled by default.

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Expand Down
2 changes: 1 addition & 1 deletion calico-enterprise_versioned_docs/version-3.23-2/operations/native-v3-crds.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ When using native `projectcalico.org/v3` CRDs:

### Validation and defaulting

When using native `projectcalico.org/v3` CRDs, resource validation and defaulting are handled by native CRD validation and defaulting, as well as ValidatingAdmissionPolicies and MutatingAdmissionPolicies. $[prodname] uses [MutatingAdmissionPolicies](https://kubernetes.io/docs/reference/access-authn-authz/validating-admission-policy/) for defaulting, which require the beta `admissionregistration.k8s.io/v1beta1` API. That API is available in **Kubernetes 1.34 and later**. On Kubernetes 1.33 and earlier, MutatingAdmissionPolicy is only available as an alpha API (`v1alpha1`), which $[prodname] does not support. On Kubernetes 1.34 and 1.35, you must enable the `MutatingAdmissionPolicy` feature gate on your Kubernetes API server before using native `projectcalico.org/v3` CRDs, as it is not enabled by default. On Kubernetes 1.36 and later, the feature is GA and enabled by default.
When using native `projectcalico.org/v3` CRDs, resource validation and defaulting are handled by native CRD validation and defaulting, as well as ValidatingAdmissionPolicies and MutatingAdmissionPolicies. $[prodname] uses [MutatingAdmissionPolicies](https://kubernetes.io/docs/reference/access-authn-authz/mutating-admission-policy/) for defaulting, which require the beta `admissionregistration.k8s.io/v1beta1` API. That API is available in **Kubernetes 1.34 and later**. On Kubernetes 1.33 and earlier, MutatingAdmissionPolicy is only available as an alpha API (`v1alpha1`), which $[prodname] does not support. On Kubernetes 1.34 and 1.35, you must enable the `MutatingAdmissionPolicy` feature gate on your Kubernetes API server before using native `projectcalico.org/v3` CRDs, as it is not enabled by default. On Kubernetes 1.36 and later, the feature is GA and enabled by default.

## Before you begin

Expand Down
2 changes: 1 addition & 1 deletion calico-enterprise_versioned_docs/version-3.24-1/operations/native-v3-crds.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ When using native `projectcalico.org/v3` CRDs:

### Validation and defaulting

When using native `projectcalico.org/v3` CRDs, resource validation and defaulting are handled by native CRD validation and defaulting, as well as ValidatingAdmissionPolicies and MutatingAdmissionPolicies. $[prodname] uses [MutatingAdmissionPolicies](https://kubernetes.io/docs/reference/access-authn-authz/validating-admission-policy/) for defaulting, which require **Kubernetes 1.32 or later**. On clusters where the `MutatingAdmissionPolicy` API is not enabled by default, you must enable the `MutatingAdmissionPolicy` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) on the Kubernetes API server.
When using native `projectcalico.org/v3` CRDs, resource validation and defaulting are handled by native CRD validation and defaulting, as well as ValidatingAdmissionPolicies and MutatingAdmissionPolicies. $[prodname] uses [MutatingAdmissionPolicies](https://kubernetes.io/docs/reference/access-authn-authz/mutating-admission-policy/) for defaulting, which require **Kubernetes 1.32 or later**. On clusters where the `MutatingAdmissionPolicy` API is not enabled by default, you must enable the `MutatingAdmissionPolicy` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) on the Kubernetes API server.

## Before you begin

Expand Down
2 changes: 1 addition & 1 deletion calico-enterprise_versioned_docs/version-3.24-2/operations/native-v3-crds.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ When using native `projectcalico.org/v3` CRDs:

### Validation and defaulting

When using native `projectcalico.org/v3` CRDs, resource validation and defaulting are handled by native CRD validation and defaulting, as well as ValidatingAdmissionPolicies and MutatingAdmissionPolicies. $[prodname] uses [MutatingAdmissionPolicies](https://kubernetes.io/docs/reference/access-authn-authz/validating-admission-policy/) for defaulting, which require **Kubernetes 1.32 or later**. On clusters where the `MutatingAdmissionPolicy` API is not enabled by default, you must enable the `MutatingAdmissionPolicy` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) on the Kubernetes API server.
When using native `projectcalico.org/v3` CRDs, resource validation and defaulting are handled by native CRD validation and defaulting, as well as ValidatingAdmissionPolicies and MutatingAdmissionPolicies. $[prodname] uses [MutatingAdmissionPolicies](https://kubernetes.io/docs/reference/access-authn-authz/mutating-admission-policy/) for defaulting, which require **Kubernetes 1.32 or later**. On clusters where the `MutatingAdmissionPolicy` API is not enabled by default, you must enable the `MutatingAdmissionPolicy` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) on the Kubernetes API server.

## Before you begin

Expand Down
10 changes: 9 additions & 1 deletion calico/getting-started/kubernetes/helm.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,16 @@ For more information about configurable options via `values.yaml` please see [He

1. Install the necessary custom resource definitions.

If your cluster is based on Kubernetes 1.36 or later:

```bash
helm template calico-crds projectcalico/projectcalico.org.v3 --version $[releaseTitle] --api-versions admissionregistration.k8s.io/v1/MutatingAdmissionPolicy | kubectl apply --server-side -f -
```

If your cluster is based on Kubernetes 1.34 or 1.35:

```bash
helm template calico-crds projectcalico/projectcalico.org.v3 --version $[releaseTitle] --validate | kubectl apply --server-side -f -
helm template calico-crds projectcalico/projectcalico.org.v3 --version $[releaseTitle] --api-versions admissionregistration.k8s.io/v1beta1/MutatingAdmissionPolicy | kubectl apply --server-side -f -
```

1. Install the Tigera Operator using the Helm chart:
Expand Down
4 changes: 2 additions & 2 deletions calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ If you're setting up a new cluster and don't need to customize the underlying Ku

:::

Native `projectcalico.org/v3` CRDs rely on MutatingAdmissionPolicies for defaulting, which require the beta `admissionregistration.k8s.io/v1beta1` API. That API is available in **Kubernetes 1.34 and later**; on Kubernetes 1.33 and earlier, MutatingAdmissionPolicy is only available as an alpha API and is not supported. On Kubernetes 1.34 and 1.35, enable the `MutatingAdmissionPolicy` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) on the Kubernetes API server before installing, as it is not enabled by default. On Kubernetes 1.36 and later, the feature is GA and enabled by default.
Native `projectcalico.org/v3` CRDs rely on MutatingAdmissionPolicies for defaulting, which require **Kubernetes 1.34 or later**: the beta `admissionregistration.k8s.io/v1beta1` API on Kubernetes 1.34 and 1.35, or the GA `admissionregistration.k8s.io/v1` API on 1.36 and later; on Kubernetes 1.33 and earlier, MutatingAdmissionPolicy is only available as an alpha API and is not supported. On Kubernetes 1.34 and 1.35, enable the `MutatingAdmissionPolicy` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) on the Kubernetes API server before installing, as it is not enabled by default. On Kubernetes 1.36 and later, the feature is GA and enabled by default.

1. Download the $[prodname] v3 CRD manifest.

Expand Down Expand Up @@ -244,7 +244,7 @@ If you have an existing manifest-based $[prodname] install using the legacy `crd
- $[prodname] installed via `calico.yaml` manifest (not operator)
- `kubectl` access to the cluster
- A recent $[prodname] version that includes the migration controller
- **Kubernetes 1.34 or later.** Native `projectcalico.org/v3` CRDs rely on MutatingAdmissionPolicies for defaulting, which require the beta `admissionregistration.k8s.io/v1beta1` API. That API is not available on Kubernetes 1.33 and earlier, where MutatingAdmissionPolicy is alpha only. On Kubernetes 1.34 and 1.35, the `MutatingAdmissionPolicy` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) must be enabled on the Kubernetes API server before starting the migration, as it is not enabled by default. On Kubernetes 1.36 and later, the feature is GA and enabled by default.
- **Kubernetes 1.34 or later.** Native `projectcalico.org/v3` CRDs rely on MutatingAdmissionPolicies for defaulting, which need the beta `admissionregistration.k8s.io/v1beta1` API on Kubernetes 1.34 and 1.35, or the GA `admissionregistration.k8s.io/v1` API on 1.36 and later. Neither is available on Kubernetes 1.33 and earlier, where MutatingAdmissionPolicy is alpha only. On Kubernetes 1.34 and 1.35, the `MutatingAdmissionPolicy` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) must be enabled on the Kubernetes API server before starting the migration, as it is not enabled by default. On Kubernetes 1.36 and later, the feature is GA and enabled by default.

#### Migration steps

Expand Down
16 changes: 12 additions & 4 deletions calico/operations/native-v3-crds.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,12 +32,12 @@ When using native `projectcalico.org/v3` CRDs:

### Validation and defaulting

When using native `projectcalico.org/v3` CRDs, resource validation and defaulting are handled by native CRD validation and defaulting, as well as ValidatingAdmissionPolicies and MutatingAdmissionPolicies. $[prodname] uses [MutatingAdmissionPolicies](https://kubernetes.io/docs/reference/access-authn-authz/validating-admission-policy/) for defaulting, which require the beta `admissionregistration.k8s.io/v1beta1` API. That API is available in **Kubernetes 1.34 and later**. On Kubernetes 1.33 and earlier, MutatingAdmissionPolicy is only available as an alpha API (`v1alpha1`), which $[prodname] does not support. On Kubernetes 1.34 and 1.35, you must enable the `MutatingAdmissionPolicy` feature gate on your Kubernetes API server before using native `projectcalico.org/v3` CRDs, as it is not enabled by default. On Kubernetes 1.36 and later, the feature is GA and enabled by default.
When using native `projectcalico.org/v3` CRDs, resource validation and defaulting are handled by native CRD validation and defaulting, as well as ValidatingAdmissionPolicies and MutatingAdmissionPolicies. $[prodname] uses [MutatingAdmissionPolicies](https://kubernetes.io/docs/reference/access-authn-authz/mutating-admission-policy/) for defaulting, which require **Kubernetes 1.34 or later**: the beta `admissionregistration.k8s.io/v1beta1` API on Kubernetes 1.34 and 1.35, or the GA `admissionregistration.k8s.io/v1` API on 1.36 and later. On Kubernetes 1.33 and earlier, MutatingAdmissionPolicy is only available as an alpha API (`v1alpha1`), which $[prodname] does not support. On Kubernetes 1.34 and 1.35, you must enable the `MutatingAdmissionPolicy` feature gate on your Kubernetes API server before using native `projectcalico.org/v3` CRDs, as it is not enabled by default. On Kubernetes 1.36 and later, the feature is GA and enabled by default.

## Before you begin

- A Kubernetes cluster **without** $[prodname] installed, or a cluster where you are performing a fresh install. To migrate an existing cluster from API server mode, see [Migrate from API server to native CRDs](crd-migration.mdx).
- **Kubernetes 1.34 or later.** $[prodname] uses the beta `admissionregistration.k8s.io/v1beta1` MutatingAdmissionPolicy API for defaulting, which is not available on Kubernetes 1.33 and earlier (where MutatingAdmissionPolicy is alpha only). On Kubernetes 1.34 and 1.35, the `MutatingAdmissionPolicy` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) must be enabled on the API server, as it is not enabled by default. On Kubernetes 1.36 and later, the feature is GA and enabled by default.
- **Kubernetes 1.34 or later.** $[prodname] uses MutatingAdmissionPolicies for defaulting, which need the beta `admissionregistration.k8s.io/v1beta1` API on Kubernetes 1.34 and 1.35, or the GA `admissionregistration.k8s.io/v1` API on 1.36 and later. Neither is available on Kubernetes 1.33 and earlier (where MutatingAdmissionPolicy is alpha only). On Kubernetes 1.34 and 1.35, the `MutatingAdmissionPolicy` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) must be enabled on the API server, as it is not enabled by default. On Kubernetes 1.36 and later, the feature is GA and enabled by default.

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Expand All @@ -63,10 +63,18 @@ Select the method below based on your preferred installation method.
kubectl create namespace tigera-operator
```

1. Install the v3 CRD chart instead of the default v1 CRD chart:
1. Install the v3 CRD chart instead of the default v1 CRD chart.

If your cluster is based on Kubernetes 1.36 or later:
Comment thread
lwr20 marked this conversation as resolved.

```bash
helm template calico-crds projectcalico/projectcalico.org.v3 --version $[releaseTitle] --api-versions admissionregistration.k8s.io/v1/MutatingAdmissionPolicy | kubectl apply --server-side -f -
```

If your cluster is based on Kubernetes 1.34 or 1.35:

```bash
helm template calico-crds projectcalico/projectcalico.org.v3 --version $[releaseTitle] --validate | kubectl apply --server-side -f -
helm template calico-crds projectcalico/projectcalico.org.v3 --version $[releaseTitle] --api-versions admissionregistration.k8s.io/v1beta1/MutatingAdmissionPolicy | kubectl apply --server-side -f -
```

:::note
Expand Down
2 changes: 2 additions & 0 deletions calico/operations/upgrading/kubernetes-upgrade.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,8 @@ To apply the CRDs yourself:

The commands above apply the v1 CRDs, which is correct for clusters using the aggregation API server (the common case). If your cluster uses native v3 CRDs, substitute `v3_projectcalico_org.yaml` for `v1_crd_projectcalico_org.yaml`, or the `projectcalico/projectcalico.org.v3` chart for `projectcalico/crd.projectcalico.org.v1`.

When templating the v3 chart on Kubernetes 1.36 and later, also add `--api-versions admissionregistration.k8s.io/v1/MutatingAdmissionPolicy`; without it, Helm renders the MutatingAdmissionPolicy resources at `v1beta1`, which Kubernetes 1.36 does not serve.
Comment thread
lwr20 marked this conversation as resolved.

:::

1. Run the Helm upgrade:
Expand Down
12 changes: 10 additions & 2 deletions calico_versioned_docs/version-3.32/getting-started/kubernetes/helm.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,10 +87,18 @@ For more information about configurable options via `values.yaml` please see [He

:::tip

To install with [native v3 CRDs](../../operations/native-v3-crds.mdx) (tech preview) instead, use the v3 CRD chart:
To install with [native v3 CRDs](../../operations/native-v3-crds.mdx) (tech preview) instead, use the v3 CRD chart.

If your cluster is based on Kubernetes 1.36 or later:

```bash
helm template calico-crds projectcalico/projectcalico.org.v3 --version $[releaseTitle] --api-versions admissionregistration.k8s.io/v1/MutatingAdmissionPolicy | kubectl apply --server-side -f -
```

If your cluster is based on Kubernetes 1.34 or 1.35:

```bash
helm template calico-crds projectcalico/projectcalico.org.v3 --version $[releaseTitle] | kubectl apply --server-side -f -
helm template calico-crds projectcalico/projectcalico.org.v3 --version $[releaseTitle] --api-versions admissionregistration.k8s.io/v1beta1/MutatingAdmissionPolicy | kubectl apply --server-side -f -
```

Native v3 CRDs eliminate the need for the aggregation API server and allows `kubectl` to manage `projectcalico.org/v3` resources directly.
Expand Down
Loading
Loading