Add documentation for v3 CRD mode

caseydavenport · caseydavenport · commit 6a88e6e4e501 · 2026-02-23T14:50:29.000-08:00
diff --git a/calico/getting-started/kubernetes/helm.mdx b/calico/getting-started/kubernetes/helm.mdx
@@ -85,6 +85,18 @@ For more information about configurable options via `values.yaml` please see [He
    helm install calico-crds projectcalico/crd.projectcalico.org.v1 --version $[releaseTitle] --namespace tigera-operator
    ```
 
+   :::tip
+
+   To install with [native v3 CRDs](../../operations/native-v3-crds.mdx) (tech preview) instead, use the v3 CRD chart:
+
+   ```bash
+   helm install calico-crds projectcalico/projectcalico.org.v3 --version $[releaseTitle] --namespace tigera-operator
+   ```
+
+   Native v3 CRDs eliminate the need for the aggregation API server and allows `kubectl` to manage `projectcalico.org/v3` resources directly.
+
+   :::
+
 1. Install the Tigera Operator using the Helm chart:
 
    ```bash
diff --git a/calico/getting-started/kubernetes/k3s/multi-node-install.mdx b/calico/getting-started/kubernetes/k3s/multi-node-install.mdx
@@ -97,7 +97,7 @@ curl -sfL https://get.k3s.io | K3S_URL=https://serverip:6443 K3S_TOKEN=mytoken s
 Install the $[prodname] operator and custom resource definitions.
 
 ```bash
-kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+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/k3s/quickstart.mdx b/calico/getting-started/kubernetes/k3s/quickstart.mdx
@@ -68,7 +68,7 @@ you are assigning necessary permissions to the file and make it accessible for o
 1. Install the $[prodname] operator and custom resource definitions.
 
 ```bash
-kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+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/k8s-single-node.mdx b/calico/getting-started/kubernetes/k8s-single-node.mdx
@@ -92,7 +92,7 @@ The geeky details of what you get:
 1. Install the Tigera Operator and custom resource definitions.
 
    ```
-   kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+   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/kind.mdx b/calico/getting-started/kubernetes/kind.mdx
@@ -82,7 +82,7 @@ dev-worker2         NotReady    <none>          4m     v1.25.0   172.18.0.3    <
 1. Install the $[prodname] operator and custom resource definitions.
 
 ```bash
-kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+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/aks.mdx b/calico/getting-started/kubernetes/managed-public-cloud/aks.mdx
@@ -115,7 +115,7 @@ The geeky details of what you get:
 1. Install the Tigera Operator and custom resource definitions:
 
    ```bash
-   kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+   kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
    kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
    ```
 
@@ -216,7 +216,7 @@ The geeky details of what you get:
 1. Install the Tigera Operator and custom resource definitions.
 
    ```bash
-   kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+   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
@@ -64,7 +64,7 @@ When using the Amazon VPC CNI plugin, $[prodname] does not support enforcement o
 1. Install the Tigera Operator and custom resource definitions.
 
    ```bash
-   kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+   kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
    kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
    ```
 
@@ -167,7 +167,7 @@ Before you get started, make sure you have downloaded and configured the [necess
 1. Install the Tigera Operator and custom resource definitions.
 
    ```bash
-   kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+   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
@@ -61,7 +61,7 @@ minikube start --cni=calico
 2. Install the Tigera Operator and custom resource definitions.
 
    ```bash
-   kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+   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/nftables.mdx b/calico/getting-started/kubernetes/nftables.mdx
@@ -102,7 +102,7 @@ mode: nftables
 1. Install the Tigera Operator and custom resource definitions.
 
    ```bash
-   kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+   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/rancher.mdx b/calico/getting-started/kubernetes/rancher.mdx
@@ -46,7 +46,7 @@ The geeky details of what you get:
 1. Install the Tigera Operator and custom resource definitions.
 
    ```
-   kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+   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-onprem/onpremises.mdx b/calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx
@@ -44,7 +44,7 @@ $[prodname] can also be installed using raw manifests as an alternative to the o
 1. Install the Tigera Operator and custom resource definitions.
 
    ```
-   kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+   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
@@ -193,7 +193,7 @@ worker-2     NotReady   <none>   5s      v1.17.2
 1. On the controller, install the Tigera Operator and custom resource definitions:
 
   ```bash
-  kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+  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/vpp/getting-started.mdx b/calico/getting-started/kubernetes/vpp/getting-started.mdx
@@ -89,7 +89,7 @@ Before you get started, make sure you have downloaded and configured the [necess
 1. Now that you have an empty cluster configured, you can install the Tigera Operator and custom resource definitions.
 
    ```bash
-   kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+   kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
    kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
    ```
 
@@ -158,7 +158,7 @@ DPDK provides better performance compared to the standard install but it require
 1. Now that you have an empty cluster configured, you can install the Tigera Operator and custom resource definitions.
 
    ```bash
-   kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+   kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
    kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
    ```
 
@@ -259,7 +259,7 @@ For some hardware, the following hugepages configuration may enable VPP to use m
 1. Install the Tigera Operator and custom resource definitions.
 
    ```bash
-   kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+   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/windows-calico/rancher.mdx b/calico/getting-started/kubernetes/windows-calico/rancher.mdx
@@ -36,7 +36,7 @@ The following steps will outline the installation of $[prodname] networking on t
 1. Install the Tigera Operator and custom resource definitions.
 
    ```
-   kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml
+   kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml
    kubectl create -f $[manifestsUrl]/manifests/tigera-operator.yaml
    ```
 
diff --git a/calico/network-policy/policy-tiers/rbac-tiered-policies.mdx b/calico/network-policy/policy-tiers/rbac-tiered-policies.mdx
@@ -19,7 +19,13 @@ Self-service is an important part of CI/CD processes for containerization and mi
 
 ### Standard Kubernetes RBAC
 
-$[prodname] implements the standard **Kubernetes RBAC Authorization APIs** with `Role` and `ClusterRole` types. The $[prodname] API server integrates with Kubernetes RBAC Authorization APIs as an extension API server.
+$[prodname] implements the standard **Kubernetes RBAC Authorization APIs** with `Role` and `ClusterRole` types. In the default installation, the $[prodname] API server integrates with Kubernetes RBAC Authorization APIs as an extension API server. When using [native v3 CRDs](../../operations/native-v3-crds.mdx), tier RBAC is enforced via an admission webhook instead.
+
+:::note
+
+When using native `projectcalico.org/v3` CRDs, tier RBAC is enforced for **create, update, and delete** operations via the admission webhook. However, **GET, LIST, and WATCH** operations on tiered policies are not enforced because admission webhooks cannot intercept read requests. This is a known limitation.
+
+:::
 
 ### RBAC for policies and tiers
 
diff --git a/calico/networking/ingress-gateway/tutorial-ingress-gateway-canary.mdx b/calico/networking/ingress-gateway/tutorial-ingress-gateway-canary.mdx
@@ -107,7 +107,7 @@ If you've already got a suitable environment, start the tutorial at [Step 2: Cre
 
 1. Install Calico Open Source by adding custom resource definitions, the Tigera Operator, and the custom resources.
    <CodeBlock>
-   {`kubectl create -f ${files}/manifests/operator-crds.yaml
+   {`kubectl create -f ${files}/manifests/v1_crd_projectcalico_org.yaml
    kubectl create -f ${files}/manifests/tigera-operator.yaml
    kubectl create -f ${files}/manifests/custom-resources.yaml`}
    </CodeBlock>
diff --git a/calico/operations/calicoctl/install.mdx b/calico/operations/calicoctl/install.mdx
@@ -48,7 +48,7 @@ should still be used to manage other Kubernetes resources.
 :::note
 
 If you would like to use `kubectl` to manage `projectcalico.org/v3` API resources, you can use the
-[Calico API server](../install-apiserver.mdx).
+[Calico API server](../install-apiserver.mdx). Alternatively, when using [native v3 CRDs](../native-v3-crds.mdx), `kubectl` can manage `projectcalico.org/v3` resources directly as native CRDs without needing the API server or calicoctl for resource management.
 
 :::
 
diff --git a/calico/operations/install-apiserver.mdx b/calico/operations/install-apiserver.mdx
@@ -13,6 +13,12 @@ import TabItem from '@theme/TabItem';
 
 Install the Calico API server on an existing cluster to enable management of Calico APIs using kubectl.
 
+:::tip
+
+Starting in Calico v3.32.0, you can use [native v3 CRDs](native-v3-crds.mdx) to manage `projectcalico.org/v3` resources directly with `kubectl` without installing the aggregation API server. If you are setting up a new cluster and want a simpler architecture, consider native v3 CRDs instead.
+
+:::
+
 ## Value
 
 The API server provides a REST API for Calico, and allows management of `projectcalico.org/v3` APIs using kubectl without the need for calicoctl.
@@ -39,6 +45,8 @@ in this document are not required.
 In previous releases, calicoctl has been required to manage Calico API resources in the `projectcalico.org/v3` API group. The calicoctl CLI tool provides important validation and defaulting on these APIs. The Calico API server performs
 that defaulting and validation server-side, exposing the same API semantics without a dependency on calicoctl.
 
+Alternatively, when using [native v3 CRDs](native-v3-crds.mdx), `projectcalico.org/v3` resources are native CRDs, so `kubectl` works directly without needing either the API server or calicoctl for resource management.
+
 calicoctl is still required for the following subcommands:
 
 - [calicoctl node](../reference/calicoctl/node/index.mdx)
@@ -55,14 +63,16 @@ Select the method below based on your installation method.
 <Tabs>
 <TabItem label="Operator install" value="Operator install-0">
 
-1. Create an instance of an `operator.tigera.io/APIServer` with the following contents.
+1. Create an instance of an `operator.tigera.io/APIServer` with the following command.
 
-   ```yaml
+   ```bash
+   kubectl create -f - <<EOF
    apiVersion: operator.tigera.io/v1
    kind: APIServer
    metadata:
      name: default
    spec: {}
+   EOF
    ```
 
 1. Confirm it appears as `Available` with the following command.
@@ -183,7 +193,7 @@ To uninstall the API server, use the following instructions depending on your in
 </TabItem>
 </Tabs>
 
-Once removed, you will need to use calicoctl to manage projectcalico.org/v3 APIs.
+Once removed, you will need to use calicoctl to manage projectcalico.org/v3 APIs, unless you are using [native v3 CRDs](native-v3-crds.mdx) where `kubectl` works directly.
 
 ## Next steps
 
diff --git a/calico/operations/native-v3-crds.mdx b/calico/operations/native-v3-crds.mdx
diff --git a/calico/operations/operator-migration.mdx b/calico/operations/operator-migration.mdx
diff --git a/calico/operations/upgrading/kubernetes-upgrade.mdx b/calico/operations/upgrading/kubernetes-upgrade.mdx
diff --git a/calico/reference/architecture/overview.mdx b/calico/reference/architecture/overview.mdx
diff --git a/calico/reference/installation/helm_customization.mdx b/calico/reference/installation/helm_customization.mdx
diff --git a/calico/reference/resources/ippool.mdx b/calico/reference/resources/ippool.mdx
diff --git a/sidebars-calico.js b/sidebars-calico.js
