Add documentation for v3 CRD mode (tech preview)#2545
Conversation
❌ Deploy Preview for calico-docs-preview-next failed. Why did it fail? →
|
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
caseydavenport
force-pushed
the
casey-v3-crds
branch
from
1fb4cef to
6aeec2d
Compare
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for the new v3 CRD mode feature in Calico v3.32.0 (tech preview). In v3 CRD mode, projectcalico.org/v3 resources are backed directly by CRDs instead of requiring the Calico aggregation API server. This simplifies architecture, improves GitOps compatibility, and allows kubectl to manage Calico resources natively.
Changes:
- New dedicated page documenting v3 CRD mode installation, behavioral differences, limitations, and troubleshooting
- Updates to related documentation pages to reference the new mode as an alternative to the aggregation API server
- Documentation of key behavioral differences including asynchronous CIDR validation and partial tier RBAC enforcement
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
sidebars-calico.js |
Adds navigation entry for v3 CRD mode page in Operations section after install-apiserver |
calico/operations/enable-v3-crd-mode.mdx |
New comprehensive page covering v3 CRD mode concept, installation, behavioral differences, limitations, and troubleshooting |
calico/getting-started/kubernetes/helm.mdx |
Adds tip showing v3 CRD chart installation as alternative to default v1 chart |
calico/operations/install-apiserver.mdx |
Adds tip referencing v3 CRD mode and updates calicoctl/kubectl relationship explanations |
calico/operations/calicoctl/install.mdx |
Adds v3 CRD mode as alternative for kubectl access to Calico resources |
calico/reference/installation/helm_customization.mdx |
Clarifies that v3 apiVersion can always be used in v3 CRD mode |
calico/reference/architecture/overview.mdx |
Updates APIServer component description to explain different behavior in v3 CRD mode |
calico/network-policy/policy-tiers/rbac-tiered-policies.mdx |
Documents webhook enforcement and GET/LIST/WATCH limitation in v3 CRD mode |
calico/reference/resources/ippool.mdx |
Adds CIDR overlap validation section documenting asynchronous behavior in v3 CRD mode |
caseydavenport
force-pushed
the
casey-v3-crds
branch
9 times, most recently
from
ab594d3 to
f5e1385
Compare
|
|
||
| ```bash | ||
| kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml | ||
| kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml |
There was a problem hiding this comment.
FYI the old URL will continue to exist for a while for compatibility reasons, but this new URL is more explicit and is the counterpart to the v3 version.
There was a problem hiding this comment.
It would be good to give people a timeline. I expect the change is one that will need to planned for some automated systems.
There was a problem hiding this comment.
I'm not sure what that timeline is! But I think so long as it is 2+ releases then we'll be OK.
caseydavenport
force-pushed
the
casey-v3-crds
branch
9 times, most recently
from
b678557 to
00b5a78
Compare
ctauchen
left a comment
ctauchen
left a comment
There was a problem hiding this comment.
Needs fetch and rebase to clear already merged content. A few nits, and then let's get this merged for testing.
|
|
||
| ```bash | ||
| kubectl create -f $[manifestsUrl]/manifests/operator-crds.yaml | ||
| kubectl create -f $[manifestsUrl]/manifests/v1_crd_projectcalico_org.yaml |
There was a problem hiding this comment.
It would be good to give people a timeline. I expect the change is one that will need to planned for some automated systems.
Remove version-specific callouts (implied by being in 3.32 docs), capitalize Felix, remove stale GA feature status tag.
caseydavenport
force-pushed
the
casey-v3-crds
branch
from
00b5a78 to
05fa16e
Compare
Copy native-v3-crds guide and apply the same reference updates (RBAC tier enforcement, architecture overview, helm customization, IPPool CIDR overlap validation) to CE docs.
calicoctl docs do not exist in the calico-enterprise directory, so the cross-links break the build.
The "no automated migration" limitation and prereq language are stale now that the migration controller and docs (PR tigera#2595) exist. Replace with a link to the migration guide.
Summary
Adds documentation for the new v3 CRD mode feature in Calico v3.32.0.
In v3 CRD mode,
projectcalico.org/v3resources are backed directly by CRDs, eliminating the need for the Calico aggregation API server. This simplifies installation, removes ordering dependencies (benefiting GitOps tools like ArgoCD/Flux), and allowskubectlto manage Calico resources natively. For v3.32.0, this is tech preview — the default install still uses the API server and users must explicitly opt in. The feature is expected to advance toward GA over subsequent releases.Changes
calico/operations/enable-v3-crd-mode.mdx— primary docs covering what v3 CRD mode is, how to enable it via Helm, behavioral differences, known limitations, and troubleshootingprojectcalico.org.v3CRD chart alongside the default v1 chartReferences
Test plan
make start— verify new page renders, sidebar link works, admonitions display correctlyyarn test:components— ensure no React component regressions🤖 Generated with Claude Code