diff --git a/calico-enterprise/getting-started/install-on-clusters/docker-enterprise.mdx b/calico-enterprise/getting-started/install-on-clusters/docker-enterprise.mdx
index 3d381e1f9a..cf8474e217 100644
--- a/calico-enterprise/getting-started/install-on-clusters/docker-enterprise.mdx
+++ b/calico-enterprise/getting-started/install-on-clusters/docker-enterprise.mdx
@@ -69,8 +69,14 @@ The geeky details of what you get:
1. Install the Tigera Operator and custom resource definitions.
+ :::note[What changed]
+
+ New installs now default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. Requires Kubernetes 1.32+. To install with the aggregation API server instead, apply `operator-crds.yaml` in place of `v3_projectcalico_org.yaml`. See [Native v3 CRDs](../../operations/native-v3-crds.mdx).
+
+ :::
+
```bash
- kubectl create -f $[filesUrl]/manifests/operator-crds.yaml
+ kubectl create -f $[filesUrl]/manifests/v3_projectcalico_org.yaml
kubectl create -f $[filesUrl]/manifests/tigera-operator.yaml
```
diff --git a/calico-enterprise/getting-started/install-on-clusters/kubernetes/helm.mdx b/calico-enterprise/getting-started/install-on-clusters/kubernetes/helm.mdx
index 2e25991691..f8b5fcc35a 100644
--- a/calico-enterprise/getting-started/install-on-clusters/kubernetes/helm.mdx
+++ b/calico-enterprise/getting-started/install-on-clusters/kubernetes/helm.mdx
@@ -36,7 +36,7 @@ In this guide, you install the Tigera Calico operator and custom resource defini
helm repo add tigera-ee https://downloads.tigera.io/ee/charts
helm repo update
helm pull tigera-ee/tigera-operator --version $[releaseTitle]$[helmPre]
-helm pull tigera-ee/crd.projectcalico.org.v1 --version $[releaseTitle]$[helmPre]
+helm pull tigera-ee/projectcalico.org.v3 --version $[releaseTitle]$[helmPre]
```
### Prepare the Installation Configuration
@@ -95,8 +95,14 @@ To install a standard $[prodname] cluster with Helm:
1. Install the necessary custom resource definitions.
+ :::note[What changed]
+
+ New installs now default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. Requires Kubernetes 1.32+. To install with the aggregation API server instead, pull and install the `tigera-ee/crd.projectcalico.org.v1` chart in place of `projectcalico.org.v3`. See [Native v3 CRDs](../../../operations/native-v3-crds.mdx).
+
+ :::
+
```bash
- helm template calico-crds crd.projectcalico.org.v1-$[chart_version_name].tgz | kubectl apply --server-side -f -
+ helm template calico-crds projectcalico.org.v3-$[chart_version_name].tgz | kubectl apply --server-side -f -
```
1. Install the Tigera Operator using the Helm 3 chart:
diff --git a/calico-enterprise/getting-started/install-on-clusters/kubernetes/quickstart.mdx b/calico-enterprise/getting-started/install-on-clusters/kubernetes/quickstart.mdx
index 07094257fa..cc8552750f 100644
--- a/calico-enterprise/getting-started/install-on-clusters/kubernetes/quickstart.mdx
+++ b/calico-enterprise/getting-started/install-on-clusters/kubernetes/quickstart.mdx
@@ -89,8 +89,14 @@ A Linux host that meets the following requirements.
1. Install the Tigera Operator and custom resource definitions.
+ :::note[What changed]
+
+ New installs now default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. Requires Kubernetes 1.32+. To install with the aggregation API server instead, apply `operator-crds.yaml` in place of `v3_projectcalico_org.yaml`. See [Native v3 CRDs](../../../operations/native-v3-crds.mdx).
+
+ :::
+
```bash
- kubectl create -f $[filesUrl]/manifests/operator-crds.yaml
+ kubectl create -f $[filesUrl]/manifests/v3_projectcalico_org.yaml
kubectl create -f $[filesUrl]/manifests/tigera-operator.yaml
```
diff --git a/calico-enterprise/getting-started/install-on-clusters/rancher.mdx b/calico-enterprise/getting-started/install-on-clusters/rancher.mdx
index f52b9dec88..856e56ef8a 100644
--- a/calico-enterprise/getting-started/install-on-clusters/rancher.mdx
+++ b/calico-enterprise/getting-started/install-on-clusters/rancher.mdx
@@ -57,8 +57,14 @@ The geeky details of what you get:
1. Install the Tigera Operator and custom resource definitions.
+ :::note[What changed]
+
+ New installs now default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. Requires Kubernetes 1.32+. To install with the aggregation API server instead, apply `operator-crds.yaml` in place of `v3_projectcalico_org.yaml`. See [Native v3 CRDs](../../operations/native-v3-crds.mdx).
+
+ :::
+
```bash
- kubectl create -f $[filesUrl]/manifests/operator-crds.yaml
+ kubectl create -f $[filesUrl]/manifests/v3_projectcalico_org.yaml
kubectl create -f $[filesUrl]/manifests/tigera-operator.yaml
```
diff --git a/calico-enterprise/getting-started/install-on-clusters/rke2.mdx b/calico-enterprise/getting-started/install-on-clusters/rke2.mdx
index 86e4afd16a..7b1614fb34 100644
--- a/calico-enterprise/getting-started/install-on-clusters/rke2.mdx
+++ b/calico-enterprise/getting-started/install-on-clusters/rke2.mdx
@@ -54,8 +54,14 @@ The geeky details of what you get:
1. Install the Tigera Operator and custom resource definitions.
+ :::note[What changed]
+
+ New installs now default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. Requires Kubernetes 1.32+. To install with the aggregation API server instead, apply `operator-crds.yaml` in place of `v3_projectcalico_org.yaml`. See [Native v3 CRDs](../../operations/native-v3-crds.mdx).
+
+ :::
+
```bash
- kubectl create -f $[filesUrl]/manifests/operator-crds.yaml
+ kubectl create -f $[filesUrl]/manifests/v3_projectcalico_org.yaml
kubectl create -f $[filesUrl]/manifests/tigera-operator.yaml
```
diff --git a/calico-enterprise/getting-started/install-on-clusters/windows-calico/rancher.mdx b/calico-enterprise/getting-started/install-on-clusters/windows-calico/rancher.mdx
index b9c7cb8c7b..b0d1fd21e5 100644
--- a/calico-enterprise/getting-started/install-on-clusters/windows-calico/rancher.mdx
+++ b/calico-enterprise/getting-started/install-on-clusters/windows-calico/rancher.mdx
@@ -29,8 +29,14 @@ The following steps will outline the installation of $[prodname] networking on t
1. Install the Tigera Operator and custom resource definitions.
+ :::note[What changed]
+
+ New installs now default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. Requires Kubernetes 1.32+. To install with the aggregation API server instead, apply `operator-crds.yaml` in place of `v3_projectcalico_org.yaml`. See [Native v3 CRDs](../../../operations/native-v3-crds.mdx).
+
+ :::
+
```bash
- kubectl create -f $[filesUrl]/manifests/operator-crds.yaml
+ kubectl create -f $[filesUrl]/manifests/v3_projectcalico_org.yaml
kubectl create -f $[filesUrl]/manifests/tigera-operator.yaml
```
diff --git a/calico-enterprise/getting-started/upgrading/upgrading-calico-to-calico-enterprise/upgrade-to-tsee/helm.mdx b/calico-enterprise/getting-started/upgrading/upgrading-calico-to-calico-enterprise/upgrade-to-tsee/helm.mdx
index dbd5a2bfa6..072f253f53 100644
--- a/calico-enterprise/getting-started/upgrading/upgrading-calico-to-calico-enterprise/upgrade-to-tsee/helm.mdx
+++ b/calico-enterprise/getting-started/upgrading/upgrading-calico-to-calico-enterprise/upgrade-to-tsee/helm.mdx
@@ -45,6 +45,12 @@ The following steps assume the Calico deployment is installed on `tigera-operato
1. Install the $[prodname] custom resource definitions.
+ :::note[CRD mode]
+
+ These steps apply to clusters using the aggregation API server, the default for existing and upgraded $[prodname] clusters. Upgrading does not change your cluster's CRD mode. If your cluster uses native v3 CRDs, apply `v3_projectcalico_org.yaml` in place of `operator-crds.yaml` below. See [Native v3 CRDs](../../../../operations/native-v3-crds.mdx).
+
+ :::
+
```bash
kubectl apply --server-side --force-conflicts -f $[filesUrl]/manifests/operator-crds.yaml
kubectl create -f $[filesUrl]/manifests/prometheus-operator-crds.yaml
diff --git a/calico-enterprise/getting-started/upgrading/upgrading-enterprise/kubernetes-upgrade-tsee/helm.mdx b/calico-enterprise/getting-started/upgrading/upgrading-enterprise/kubernetes-upgrade-tsee/helm.mdx
index 69516120df..521c8cff3e 100644
--- a/calico-enterprise/getting-started/upgrading/upgrading-enterprise/kubernetes-upgrade-tsee/helm.mdx
+++ b/calico-enterprise/getting-started/upgrading/upgrading-enterprise/kubernetes-upgrade-tsee/helm.mdx
@@ -71,6 +71,12 @@ These steps differ based on your cluster type. If you are unsure of your cluster
1. Install the $[prodname] custom resource definitions.
+ :::note[CRD mode]
+
+ These steps apply to clusters using the aggregation API server, the default for existing and upgraded $[prodname] clusters. Upgrading does not change your cluster's CRD mode. If your cluster uses native v3 CRDs, apply `v3_projectcalico_org.yaml` in place of `operator-crds.yaml` below. See [Native v3 CRDs](../../../../operations/native-v3-crds.mdx).
+
+ :::
+
```bash
kubectl apply --server-side --force-conflicts -f $[filesUrl]/manifests/operator-crds.yaml
kubectl apply --server-side --force-conflicts -f $[filesUrl]/manifests/prometheus-operator-crds.yaml
diff --git a/calico-enterprise/installation/install-calico-enterprise-mke-4k.mdx b/calico-enterprise/installation/install-calico-enterprise-mke-4k.mdx
index 3ca41c20a7..0fc966759c 100644
--- a/calico-enterprise/installation/install-calico-enterprise-mke-4k.mdx
+++ b/calico-enterprise/installation/install-calico-enterprise-mke-4k.mdx
@@ -88,8 +88,14 @@ In a new terminal, install the $[prodname] CNI.
1. Install the Tigera Operator and custom resource definitions.
+ :::note[What changed]
+
+ New installs now default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. Requires Kubernetes 1.32+. To install with the aggregation API server instead, apply `operator-crds.yaml` in place of `v3_projectcalico_org.yaml`. See [Native v3 CRDs](../operations/native-v3-crds.mdx).
+
+ :::
+
```bash
- kubectl apply --server-side -f $[filesUrl]/manifests/operator-crds.yaml
+ kubectl apply --server-side -f $[filesUrl]/manifests/v3_projectcalico_org.yaml
kubectl apply -f $[filesUrl]/manifests/tigera-operator.yaml
```
diff --git a/calico-enterprise/operations/crd-migration.mdx b/calico-enterprise/operations/crd-migration.mdx
index 74bf1638e6..da05c9203f 100644
--- a/calico-enterprise/operations/crd-migration.mdx
+++ b/calico-enterprise/operations/crd-migration.mdx
@@ -4,12 +4,6 @@ description: Migrate Calico Enterprise resources from the aggregated API server
# Migrate from API server to native CRDs
-:::note
-
-This feature is tech preview. Tech preview features may be subject to significant changes before they become GA.
-
-:::
-
## Big picture
Automatically migrate $[prodname] resources from the aggregated API server's `crd.projectcalico.org/v1` backing storage to native `projectcalico.org/v3` CRDs, allowing you to remove the API server component.
diff --git a/calico-enterprise/operations/native-v3-crds.mdx b/calico-enterprise/operations/native-v3-crds.mdx
index 49de1cc9cd..eaf6e026ae 100644
--- a/calico-enterprise/operations/native-v3-crds.mdx
+++ b/calico-enterprise/operations/native-v3-crds.mdx
@@ -1,18 +1,12 @@
---
-description: Switch Calico Enterprise to native projectcalico.org/v3 CRDs so resources are stored directly as CRDs without the aggregated API server component.
+description: New installs of Calico Enterprise use native projectcalico.org/v3 CRDs by default. This page explains how native v3 CRD mode works and how to install with the aggregation API server instead.
---
-# Enable native v3 CRDs
-
-:::note
-
-This feature is tech preview. Tech preview features may be subject to significant changes before they become GA.
-
-:::
+# Native v3 CRDs
## Big picture
-Enable native `projectcalico.org/v3` CRDs so that Calico resources are backed directly by CRDs, eliminating the need for the Calico aggregation API server.
+New installs of $[prodname] use native `projectcalico.org/v3` CRDs by default: Calico resources are backed directly by CRDs, eliminating the need for the Calico aggregation API server. This page explains how the mode works and how to install with the aggregation API server instead.
## Value
@@ -36,12 +30,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/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.
## 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.32 or later.** $[prodname] uses the `MutatingAdmissionPolicy` API for defaulting. On clusters where it is not enabled by default, enable the `MutatingAdmissionPolicy` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) on the API server.
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@@ -50,76 +44,10 @@ import TabItem from '@theme/TabItem';
### Install $[prodname] with native `projectcalico.org/v3` CRDs
-Select the method below based on your preferred installation method.
-
-
-
-
-1. Add the $[prodname] Helm repo:
-
- ```bash
- helm repo add projectcalico https://docs.tigera.io/calico/charts
- ```
-
-1. Create the `tigera-operator` namespace:
-
- ```bash
- kubectl create namespace tigera-operator
- ```
-
-1. Install the v3 CRD chart instead of the default v1 CRD chart:
-
- ```bash
- helm template calico-crds projectcalico/projectcalico.org.v3 --version $[releaseTitle] | kubectl apply --server-side -f -
- ```
+On $[prodname], the standard install guides default to native `projectcalico.org/v3` CRD mode, so follow your preferred method to install:
- :::note
-
- This replaces the `crd.projectcalico.org.v1` chart used in the default installation. Do not install both CRD charts.
-
- :::
-
-1. Install the Tigera Operator:
-
- ```bash
- helm install $[prodnamedash] projectcalico/tigera-operator --version $[releaseTitle] --namespace tigera-operator
- ```
-
- If you have a `values.yaml` with custom configuration:
-
- ```bash
- helm install $[prodnamedash] projectcalico/tigera-operator --version $[releaseTitle] -f values.yaml --namespace tigera-operator
- ```
-
-
-
-
-1. Install the v3 CRDs:
-
- ```bash
- kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
- ```
-
- :::note
-
- This replaces the `v1_crd_projectcalico_org.yaml` manifest used in the default installation. Do not install both CRD manifests.
-
- :::
-
-1. Install the Tigera Operator:
-
- ```bash
- kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
- ```
-
-1. Install $[prodname] by creating the necessary custom resources:
-
- ```bash
- kubectl create -f $[manifestsUrl]/manifests/custom-resources.yaml
- ```
-
-
-
+- [Helm install](../getting-started/install-on-clusters/kubernetes/helm.mdx) installs the `projectcalico.org.v3` CRD chart.
+- [Manifest install](../getting-started/install-on-clusters/kubernetes/quickstart.mdx) applies the `v3_projectcalico_org.yaml` CRD bundle.
After installing, complete the following steps:
@@ -181,6 +109,34 @@ In API server mode, tier RBAC is enforced for all operations (create, update, de
When using native `projectcalico.org/v3` CRDs, tier RBAC is enforced via the admission webhook for **create, update, and delete** operations. However, **GET, LIST, and WATCH** operations on tiered policies are **not enforced** because admission webhooks cannot intercept read operations. This is a known limitation.
+## Install in API server mode (v1 CRDs)
+
+New installs default to v3 CRD mode. To install in the aggregation API-server mode instead, install the v1 CRDs before the operator decides the mode - the operator runs in API-server mode whenever the `crd.projectcalico.org/v1` CRDs are present.
+
+
+
+
+Pull and install the v1 CRD chart before the Tigera Operator:
+
+```bash
+helm pull tigera-ee/crd.projectcalico.org.v1 --version $[releaseTitle]$[helmPre]
+helm template calico-crds crd.projectcalico.org.v1-$[chart_version_name].tgz | kubectl apply --server-side -f -
+```
+
+
+
+
+Apply the v1 CRDs before the Tigera Operator:
+
+```bash
+kubectl create -f $[filesUrl]/manifests/operator-crds.yaml
+```
+
+
+
+
+Then continue with your normal install. The aggregation API server is deployed automatically.
+
## Known limitations
- **GET/LIST/WATCH tier RBAC not enforced** — Admission webhooks cannot intercept read operations, so tier-based RBAC for GET, LIST, and WATCH is not enforced when using native `projectcalico.org/v3` CRDs.
diff --git a/calico-enterprise/operations/nftables.mdx b/calico-enterprise/operations/nftables.mdx
index d3ba164e1d..53fd0d3837 100644
--- a/calico-enterprise/operations/nftables.mdx
+++ b/calico-enterprise/operations/nftables.mdx
@@ -108,8 +108,14 @@ If you're using Kubernetes 1.33 or later, you can create a cluster with kubeadm
1. Install the Tigera Operator and custom resource definitions.
+ :::note[What changed]
+
+ New installs now default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. Requires Kubernetes 1.32+. To install with the aggregation API server instead, apply `operator-crds.yaml` in place of `v3_projectcalico_org.yaml`. See [Native v3 CRDs](./native-v3-crds.mdx).
+
+ :::
+
```bash
- kubectl create -f $[filesUrl]/manifests/operator-crds.yaml
+ kubectl create -f $[filesUrl]/manifests/v3_projectcalico_org.yaml
kubectl create -f $[filesUrl]/manifests/tigera-operator.yaml
```
diff --git a/calico-enterprise/release-notes/index.mdx b/calico-enterprise/release-notes/index.mdx
index 6d0f043247..2686e8e8f6 100644
--- a/calico-enterprise/release-notes/index.mdx
+++ b/calico-enterprise/release-notes/index.mdx
@@ -18,6 +18,8 @@ This version of Calico Enterprise is based on [Calico Open Source $[openSourceVe
## New features and enhancements
+- New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. Existing and upgraded clusters are unaffected. To install with the aggregation API server instead, apply the v1 CRDs before installing the operator. v3 CRD mode requires Kubernetes 1.32 or later. See [Native v3 CRDs](../operations/native-v3-crds.mdx).
+
### Deprecated and removed features
## Technology Preview features
diff --git a/calico/getting-started/kubernetes/helm.mdx b/calico/getting-started/kubernetes/helm.mdx
index 472892ee6e..04bbf91774 100644
--- a/calico/getting-started/kubernetes/helm.mdx
+++ b/calico/getting-started/kubernetes/helm.mdx
@@ -81,19 +81,13 @@ For more information about configurable options via `values.yaml` please see [He
1. Install the necessary custom resource definitions.
- ```bash
- helm template calico-crds projectcalico/crd.projectcalico.org.v1 --version $[releaseTitle] | kubectl apply --server-side -f -
- ```
-
- :::tip
-
- To install with [native v3 CRDs](../../operations/native-v3-crds.mdx) (tech preview) instead, use the v3 CRD chart:
-
```bash
helm template calico-crds projectcalico/projectcalico.org.v3 --version $[releaseTitle] | 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.
+ :::note[What changed]
+
+ New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
:::
diff --git a/calico/getting-started/kubernetes/k3s/multi-node-install.mdx b/calico/getting-started/kubernetes/k3s/multi-node-install.mdx
index 206692d650..ed18d8e125 100644
--- a/calico/getting-started/kubernetes/k3s/multi-node-install.mdx
+++ b/calico/getting-started/kubernetes/k3s/multi-node-install.mdx
@@ -94,19 +94,24 @@ curl -sfL https://get.k3s.io | K3S_URL=https://serverip:6443 K3S_TOKEN=mytoken s
-Install the $[prodname] operator and custom resource definitions.
+Install the $[prodname] custom resource definitions.
```bash
-kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
-kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
```
-:::note
+:::note[What changed]
-Due to the large size of the CRD bundle, `kubectl apply` might exceed request limits. Instead, use `kubectl create` or `kubectl replace`.
+New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
:::
+Install the Tigera Operator.
+
+```bash
+kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+```
+
Install $[prodname] by creating the necessary custom resource. For more information on configuration options available in this manifest, see [the installation reference](../../../reference/installation/api.mdx).
```bash
diff --git a/calico/getting-started/kubernetes/k3s/quickstart.mdx b/calico/getting-started/kubernetes/k3s/quickstart.mdx
index 4f93b0ce57..5d4b2fe30e 100644
--- a/calico/getting-started/kubernetes/k3s/quickstart.mdx
+++ b/calico/getting-started/kubernetes/k3s/quickstart.mdx
@@ -65,20 +65,25 @@ you are assigning necessary permissions to the file and make it accessible for o
-1. Install the $[prodname] operator and custom resource definitions.
+1. Install the $[prodname] custom resource definitions.
```bash
-kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
-kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
```
-:::note
+:::note[What changed]
-Due to the large size of the CRD bundle, `kubectl apply` might exceed request limits. Therefore, it is recommended to use `kubectl create` or `kubectl replace`.
+New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
:::
-2. Install $[prodname] by creating the necessary custom resource. For more information on configuration options available in this manifest, see [the installation reference](../../../reference/installation/api.mdx).
+2. Install the Tigera Operator.
+
+```bash
+kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+```
+
+3. Install $[prodname] by creating the necessary custom resource. For more information on configuration options available in this manifest, see [the installation reference](../../../reference/installation/api.mdx).
```bash
kubectl create -f $[manifestsUrl]/manifests/custom-resources.yaml
diff --git a/calico/getting-started/kubernetes/k8s-single-node.mdx b/calico/getting-started/kubernetes/k8s-single-node.mdx
index 8ae6ccf65f..9c0b2ef361 100644
--- a/calico/getting-started/kubernetes/k8s-single-node.mdx
+++ b/calico/getting-started/kubernetes/k8s-single-node.mdx
@@ -89,19 +89,24 @@ The geeky details of what you get:
### Install $[prodname]
-1. Install the Tigera Operator and custom resource definitions.
+1. Install the $[prodname] custom resource definitions.
```
- kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
- kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+ kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
```
- :::note
+ :::note[What changed]
- Due to the large size of the CRD bundle, `kubectl apply` might exceed request limits. Instead, use `kubectl create` or `kubectl replace`.
+ New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
:::
+1. Install the Tigera Operator.
+
+ ```
+ kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+ ```
+
1. Install $[prodname] by creating the necessary custom resource. For more information on configuration options available in this manifest, see [the installation reference](../../reference/installation/api.mdx).
```
diff --git a/calico/getting-started/kubernetes/kind.mdx b/calico/getting-started/kubernetes/kind.mdx
index 6df8fb83a1..bf50edc474 100644
--- a/calico/getting-started/kubernetes/kind.mdx
+++ b/calico/getting-started/kubernetes/kind.mdx
@@ -79,14 +79,25 @@ dev-worker2 NotReady 4m v1.25.0 172.18.0.3 <
-1. Install the $[prodname] operator and custom resource definitions.
+1. Install the $[prodname] custom resource definitions.
+
+```bash
+kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
+```
+
+:::note[What changed]
+
+New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
+
+:::
+
+2. Install the Tigera Operator.
```bash
-kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
```
-2. Install $[prodname] by creating the necessary custom resource. For more information on configuration options available in this manifest, see [the installation reference](../../reference/installation/api.mdx).
+3. Install $[prodname] by creating the necessary custom resource. For more information on configuration options available in this manifest, see [the installation reference](../../reference/installation/api.mdx).
:::note
diff --git a/calico/getting-started/kubernetes/managed-public-cloud/aks.mdx b/calico/getting-started/kubernetes/managed-public-cloud/aks.mdx
index bde58970d0..81400c6dea 100644
--- a/calico/getting-started/kubernetes/managed-public-cloud/aks.mdx
+++ b/calico/getting-started/kubernetes/managed-public-cloud/aks.mdx
@@ -112,10 +112,21 @@ The geeky details of what you get:
Now that you have a cluster configured, you can install $[prodname].
-1. Install the Tigera Operator and custom resource definitions:
+1. Install the $[prodname] custom resource definitions:
+
+ ```bash
+ kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
+ ```
+
+ :::note[What changed]
+
+ New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
+
+ :::
+
+1. Install the Tigera Operator.
```bash
- kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
```
@@ -213,10 +224,21 @@ The geeky details of what you get:
1. Now that you have a cluster configured, you can install $[prodname].
-1. Install the Tigera Operator and custom resource definitions.
+1. Install the $[prodname] custom resource definitions.
+
+ ```bash
+ kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
+ ```
+
+ :::note[What changed]
+
+ New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
+
+ :::
+
+1. Install the Tigera Operator.
```bash
- kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
```
diff --git a/calico/getting-started/kubernetes/managed-public-cloud/eks.mdx b/calico/getting-started/kubernetes/managed-public-cloud/eks.mdx
index dcb9546176..cda674c085 100644
--- a/calico/getting-started/kubernetes/managed-public-cloud/eks.mdx
+++ b/calico/getting-started/kubernetes/managed-public-cloud/eks.mdx
@@ -61,10 +61,21 @@ When using the Amazon VPC CNI plugin, $[prodname] does not support enforcement o
kubectl set env -n kube-system daemonset/aws-node ANNOTATE_POD_IP=true
```
-1. Install the Tigera Operator and custom resource definitions.
+1. Install the $[prodname] custom resource definitions.
+
+ ```bash
+ kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
+ ```
+
+ :::note[What changed]
+
+ New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
+
+ :::
+
+1. Install the Tigera Operator.
```bash
- kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
```
@@ -164,10 +175,21 @@ Before you get started, make sure you have downloaded and configured the [necess
-1. Install the Tigera Operator and custom resource definitions.
+1. Install the $[prodname] custom resource definitions.
+
+ ```bash
+ kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
+ ```
+
+ :::note[What changed]
+
+ New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
+
+ :::
+
+1. Install the Tigera Operator.
```bash
- kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
```
diff --git a/calico/getting-started/kubernetes/minikube.mdx b/calico/getting-started/kubernetes/minikube.mdx
index 1d44a6dacd..5f30d6aa14 100644
--- a/calico/getting-started/kubernetes/minikube.mdx
+++ b/calico/getting-started/kubernetes/minikube.mdx
@@ -58,20 +58,25 @@ minikube start --cni=calico
minikube start --cni=false --network-plugin=cni --extra-config=kubeadm.pod-network-cidr=192.168.0.0/16 --subnet=172.16.0.0/24
```
-2. Install the Tigera Operator and custom resource definitions.
+2. Install the $[prodname] custom resource definitions.
```bash
- kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
- kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+ kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
```
- :::note
+ :::note[What changed]
- Due to the large size of the CRD bundle, `kubectl apply` might exceed request limits. Instead, use `kubectl create` or `kubectl replace`.
+ New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
:::
-3. Install $[prodname] by creating the necessary custom resource. For more information on configuration options available in this manifest, see [the installation reference](../../reference/installation/api.mdx).
+3. Install the Tigera Operator.
+
+ ```bash
+ kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+ ```
+
+4. Install $[prodname] by creating the necessary custom resource. For more information on configuration options available in this manifest, see [the installation reference](../../reference/installation/api.mdx).
:::note
diff --git a/calico/getting-started/kubernetes/nftables.mdx b/calico/getting-started/kubernetes/nftables.mdx
index c5e234083b..581247dcb1 100644
--- a/calico/getting-started/kubernetes/nftables.mdx
+++ b/calico/getting-started/kubernetes/nftables.mdx
@@ -99,19 +99,24 @@ mode: nftables
### Install $[prodname] in nftables data plane mode
-1. Install the Tigera Operator and custom resource definitions.
+1. Install the $[prodname] custom resource definitions.
```bash
- kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
- kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+ kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
```
- :::note
+ :::note[What changed]
- Due to the large size of the CRD bundle, `kubectl apply` might exceed request limits. Instead, use `kubectl create` or `kubectl replace`.
+ New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
:::
+1. Install the Tigera Operator.
+
+ ```bash
+ kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+ ```
+
1. Install $[prodname] by creating the necessary custom resource. For more information on configuration options available in this manifest, see [the installation reference](../../reference/installation/api.mdx).
```bash
diff --git a/calico/getting-started/kubernetes/quickstart.mdx b/calico/getting-started/kubernetes/quickstart.mdx
index 71dc7e3a8b..8182da31ea 100644
--- a/calico/getting-started/kubernetes/quickstart.mdx
+++ b/calico/getting-started/kubernetes/quickstart.mdx
@@ -97,9 +97,15 @@ In this step, you will install Calico in your cluster.
1. Install the $[prodname] custom resource definitions.
```bash
- kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
+ kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
```
+ :::note[What changed]
+
+ New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
+
+ :::
+
2. Install the Tigera Operator.
```bash
diff --git a/calico/getting-started/kubernetes/rancher.mdx b/calico/getting-started/kubernetes/rancher.mdx
index d3761bbd82..d34f836155 100644
--- a/calico/getting-started/kubernetes/rancher.mdx
+++ b/calico/getting-started/kubernetes/rancher.mdx
@@ -43,19 +43,24 @@ The geeky details of what you get:
### Install $[prodname]
-1. Install the Tigera Operator and custom resource definitions.
+1. Install the $[prodname] custom resource definitions.
```
- kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
- kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+ kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
```
- :::note
+ :::note[What changed]
- Due to the large size of the CRD bundle, `kubectl apply` might exceed request limits. Instead, use `kubectl create` or `kubectl replace`.
+ New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
:::
+1. Install the Tigera Operator.
+
+ ```
+ kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+ ```
+
1. Install $[prodname] by creating the necessary custom resource. For more information on configuration options available in this manifest, see [the installation reference](../../reference/installation/api.mdx).
```
diff --git a/calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx b/calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx
index b89eb54a77..377bdb17f1 100644
--- a/calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx
+++ b/calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx
@@ -41,10 +41,21 @@ $[prodname] can also be installed using raw manifests as an alternative to the o
-1. Install the Tigera Operator and custom resource definitions.
+1. Install the $[prodname] custom resource definitions.
+
+ ```
+ kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
+ ```
+
+ :::note[What changed]
+
+ New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
+
+ :::
+
+1. Install the Tigera Operator.
```
- kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
```
diff --git a/calico/getting-started/kubernetes/self-managed-public-cloud/gce.mdx b/calico/getting-started/kubernetes/self-managed-public-cloud/gce.mdx
index 77e6e6acd1..64540331c7 100644
--- a/calico/getting-started/kubernetes/self-managed-public-cloud/gce.mdx
+++ b/calico/getting-started/kubernetes/self-managed-public-cloud/gce.mdx
@@ -190,20 +190,31 @@ worker-2 NotReady 5s v1.17.2
#### Install $[prodname]
-1. On the controller, install the Tigera Operator and custom resource definitions:
+1. On the controller, install the $[prodname] custom resource definitions:
+
+ ```bash
+ kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
+ ```
+
+ :::note[What changed]
+
+ New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
+
+ :::
+
+2. Install the Tigera Operator.
```bash
- kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
```
-2. Download the custom resources necessary to configure $[prodname]
+3. Download the custom resources necessary to configure $[prodname]
```bash
curl $[manifestsUrl]/manifests/custom-resources.yaml -O
```
-3. If you wish to customize the $[prodname] install, customize the downloaded custom-resources.yaml manifest. Then create the manifest to install $[prodname].
+4. If you wish to customize the $[prodname] install, customize the downloaded custom-resources.yaml manifest. Then create the manifest to install $[prodname].
```bash
kubectl create -f custom-resources.yaml
diff --git a/calico/getting-started/kubernetes/vpp/getting-started.mdx b/calico/getting-started/kubernetes/vpp/getting-started.mdx
index 0450117314..0d12c6f209 100644
--- a/calico/getting-started/kubernetes/vpp/getting-started.mdx
+++ b/calico/getting-started/kubernetes/vpp/getting-started.mdx
@@ -86,19 +86,24 @@ Before you get started, make sure you have downloaded and configured the [necess
### Install and configure Calico with the VPP data plane
-1. Now that you have an empty cluster configured, you can install the Tigera Operator and custom resource definitions.
+1. Now that you have an empty cluster configured, you can install the $[prodname] custom resource definitions.
```bash
- kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
- kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+ kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
```
- :::note
+ :::note[What changed]
- Due to the large size of the CRD bundle, `kubectl apply` might exceed request limits. Instead, use `kubectl create` or `kubectl replace`.
+ New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
:::
+1. Install the Tigera Operator.
+
+ ```bash
+ kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+ ```
+
1. Then, you need to configure the $[prodname] installation for the VPP data plane. The yaml in the link below contains a minimal viable configuration for EKS. For more information on configuration options available in this manifest, see [the installation reference](../../../reference/installation/api.mdx).
:::note
@@ -155,20 +160,25 @@ DPDK provides better performance compared to the standard install but it require
### Install and configure Calico with the VPP data plane
-1. Now that you have an empty cluster configured, you can install the Tigera Operator and custom resource definitions.
+1. Now that you have an empty cluster configured, you can install the $[prodname] custom resource definitions.
```bash
- kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
- kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+ kubectl create -f $[manifestsUrl]/manifests/v3_projectcalico_org.yaml
```
- :::note
+ :::note[What changed]
- Due to the large size of the CRD bundle, `kubectl apply` might exceed request limits. Instead, use `kubectl create` or `kubectl replace`.
+ New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. This requires Kubernetes 1.32 or later. To install with the aggregation API server instead, see [Install in API server mode](../../../operations/install-apiserver.mdx#install-in-api-server-mode-v1-crds).
:::
-2. Then, you need to configure the $[prodname] installation for the VPP data plane. The yaml in the link below contains a minimal viable configuration for EKS. For more information on configuration options available in this manifest, see [the installation reference](../../../reference/installation/api.mdx).
+2. Install the Tigera Operator.
+
+ ```bash
+ kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
+ ```
+
+3. Then, you need to configure the $[prodname] installation for the VPP data plane. The yaml in the link below contains a minimal viable configuration for EKS. For more information on configuration options available in this manifest, see [the installation reference](../../../reference/installation/api.mdx).
:::note
@@ -181,13 +191,13 @@ DPDK provides better performance compared to the standard install but it require
kubectl create -f https://raw.githubusercontent.com/projectcalico/vpp-dataplane/$[vppbranch]/yaml/calico/installation-eks.yaml
```
-3. Now is time to install the VPP data plane components.
+4. Now is time to install the VPP data plane components.
```bash
kubectl create -f https://raw.githubusercontent.com/projectcalico/vpp-dataplane/$[vppbranch]/yaml/generated/calico-vpp-eks-dpdk.yaml
```
-4. Finally, time to add nodes to the cluster. Since we need to customize the nodes for DPDK, we will use an `eksctl` config file with the `preBootstrapCommands` property to create the worker nodes. The following command will create a managed nodegroup with 2 t3.large worker nodes in the cluster:
+5. Finally, time to add nodes to the cluster. Since we need to customize the nodes for DPDK, we will use an `eksctl` config file with the `preBootstrapCommands` property to create the worker nodes. The following command will create a managed nodegroup with 2 t3.large worker nodes in the cluster:
```
cat <
+
+
+Install the v1 CRD chart before the Tigera Operator:
+
+```bash
+helm template calico-crds projectcalico/crd.projectcalico.org.v1 --version $[releaseTitle] | kubectl apply --server-side -f -
+```
+
+
+
+
+Apply the v1 CRDs before the Tigera Operator:
+
+```bash
+kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
+```
+
+
+
+
+Then continue with your normal install. The aggregation API server is deployed automatically.
+
## Before you begin
- Make sure you have a cluster with Calico installed using the Kubernetes API data store. If not, you can [migrate from etcd](datastore-migration.mdx).
diff --git a/calico/operations/native-v3-crds.mdx b/calico/operations/native-v3-crds.mdx
index 2e0e69c57c..d5e80c9f19 100644
--- a/calico/operations/native-v3-crds.mdx
+++ b/calico/operations/native-v3-crds.mdx
@@ -1,18 +1,12 @@
---
-description: Switch Calico Open Source to native projectcalico.org/v3 CRDs so resources are stored directly as CRDs without the aggregated API server component.
+description: New installs of Calico Open Source use native projectcalico.org/v3 CRDs by default. This page explains how native v3 CRD mode works and how to install with the aggregation API server instead.
---
-# Enable native v3 CRDs
-
-:::note
-
-This feature is tech preview. Tech preview features may be subject to significant changes before they become GA.
-
-:::
+# Native v3 CRDs
## Big picture
-Enable native `projectcalico.org/v3` CRDs so that Calico resources are backed directly by CRDs, eliminating the need for the Calico aggregation API server.
+New installs of $[prodname] use native `projectcalico.org/v3` CRDs by default: Calico resources are backed directly by CRDs, with no aggregation API server. This page explains how the mode works and how to install with the aggregation API server instead.
## Value
@@ -36,12 +30,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/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.
## 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.32 or later.** $[prodname] uses the `MutatingAdmissionPolicy` API for defaulting. On clusters where it is not enabled by default, enable the `MutatingAdmissionPolicy` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) on the API server.
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
diff --git a/calico/operations/upgrading/kubernetes-upgrade.mdx b/calico/operations/upgrading/kubernetes-upgrade.mdx
index eb8b81a08d..351f90086f 100644
--- a/calico/operations/upgrading/kubernetes-upgrade.mdx
+++ b/calico/operations/upgrading/kubernetes-upgrade.mdx
@@ -8,6 +8,12 @@ import AutoHostendpointsMigrate from '@site/calico/_includes/components/AutoHost
## About upgrading $[prodname]
+:::note[Your CRD mode is preserved]
+
+Upgrading does not change your cluster's CRD mode. A cluster using the aggregation API server (v1 CRDs) stays on the aggregation API server; a cluster using native v3 CRDs stays on v3. The operator selects the mode from the CRDs present and never switches an existing cluster. To move from the aggregation API server to native v3 CRDs, see [Migrate to native v3 CRDs](../crd-migration.mdx).
+
+:::
+
This page describes how to upgrade to $[version] from $[prodname] v3.15 or later. The
procedure varies by datastore type and install method.
@@ -50,6 +56,12 @@ owned resources being garbage collected by Kubernetes.
kubectl apply --server-side --force-conflicts -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
```
+ :::note
+
+ The command above applies 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` in the command above.
+
+ :::
+
1. Run the Helm upgrade:
```bash
@@ -72,6 +84,12 @@ owned resources being garbage collected by Kubernetes.
kubectl apply --server-side --force-conflicts -f tigera-operator.yaml
```
+ :::note
+
+ The command above applies 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` in the command above.
+
+ :::
+
1. To enable the flow logs API and Calico Whisker (introduced in version 3.30), apply the `Goldmane` and `Whisker` custom resources.
:::tip
If you plan to use the observability tools in [Calico Cloud Free Tier](/calico-cloud/free/overview), you need to enable Goldmane to provide flow logs to the console.
diff --git a/calico/release-notes/index.mdx b/calico/release-notes/index.mdx
index d2b022f4d6..23460347b7 100644
--- a/calico/release-notes/index.mdx
+++ b/calico/release-notes/index.mdx
@@ -9,6 +9,8 @@ Learn about the new features, bug fixes, and other updates in this release of $[
## New features and enhancements
+- New installs default to v3 CRD mode: `projectcalico.org/v3` resources are served directly by CRDs, with no aggregation API server. Existing and upgraded clusters are unaffected. To install with the aggregation API server instead, apply the v1 CRDs before installing the operator. v3 CRD mode requires Kubernetes 1.32 or later. See [Native v3 CRDs](../operations/native-v3-crds.mdx).
+
## Technology preview features
## Deprecated and removed features