Document v3 CRD mode as the default for new installs#2805
Document v3 CRD mode as the default for new installs#2805caseydavenport wants to merge 10 commits into
Conversation
…ent v3 manifest path
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
❌ Deploy Preview for tigera failed. Why did it fail? →Built without sensitive environment variables
|
ctauchen
left a comment
ctauchen
left a comment
There was a problem hiding this comment.
A few suggestions for you. Thanks!
|
|
||
| 1. Install the necessary custom resource definitions. | ||
|
|
||
| :::note[What changed] |
There was a problem hiding this comment.
We should consider removing the note here and on the other installation guides. If someone performs an installation and notices the missing api server, they'll find plenty of information in your v3 CRDs pages and the release notes.
One reason to keep the note, or something similar, is to make things easier for people who really need the api server. Is this a significant group? From what I read, there is little reason that anyone would prefer that option.
Best path is to present one option in the main guide and provide the less common alternative in another location.
There was a problem hiding this comment.
Yeah, agreed. I pulled the note from all the install guides (OSS and Enterprise). The main guide just documents the v3 install now, and the API server opt-out lives on its own page - Native v3 CRDs for Enterprise, the API server page for Open Source.
|
|
||
| 1. Install the $[prodname] custom resource definitions. | ||
|
|
||
| :::note[CRD mode] |
There was a problem hiding this comment.
If we're maintaining both modes, then a more user-friendly path might look like this:
Prerequisite: You know what CRD mode you've got (Is there a simple check?)
- Install the custom resource definitions for your cluster's mode:
TAB 1 / TAB 2
code code code
There was a problem hiding this comment.
Good idea, restructured both upgrade guides this way. There is a simple check: kubectl api-versions | grep crd.projectcalico.org (output means the cluster is on the aggregation API server, no output means native v3). Added that as a step, then tabs for each mode.
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem label="Manifest install" value="apiserver-manifest"> |
There was a problem hiding this comment.
We don't support manifest installations in Calico Enterprise. Is there something special about this case?
There was a problem hiding this comment.
Perhaps this is just Tigera Operator and Helm installation types?
There was a problem hiding this comment.
Good catch, you're right. I relabeled to Helm and Tigera Operator and dropped the "manifest install" framing on the Enterprise page, both the install pointer near the top and the API server mode tab lower down.
|
|
||
| ## 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). |
There was a problem hiding this comment.
I'll do more closer to release, but I suspect it would be good to add more here about how this works for upgrades.
Would also be good to mention if we're deprecating the api server. Is that still the plan?
There was a problem hiding this comment.
Yep, still the plan. The aggregation API server is deprecated and will be removed in a future release (still supported for now). I added a deprecation entry to the release notes and the native v3 CRD pages, both pointing at the migration guide. Left the rest of the upgrade detail to you for closer to release.
Remove the transitional "What changed" notes from the install guides, restructure the Enterprise upgrade guides with a CRD-mode check and per-mode tabs, relabel the Enterprise manifest-install references to Helm and Tigera Operator, and document the API server deprecation in the release notes and native v3 CRD pages.
Makes v3 CRD mode the documented default for new Calico installs, matching the operator change in tigera/operator#4973. New installs now get
projectcalico.org/v3served directly by CRDs with no aggregation API server. The v1 / aggregation-API-server path stays documented as an opt-out. Existing and upgraded clusters are unaffected - the operator picks the mode from the CRDs present and never flips an existing cluster.What's here:
v3_projectcalico_org.yaml). The operator and manifest installs that stay on the aggregation API server got a v3 opt-out note instead.Note on Enterprise: this assumes
v3_projectcalico_org.yamlships at the published EE manifests location. The release tooling already builds and publishes it (hashreleases and tagged releases both include it), so it should line up with real releases. The one gap is theee/master/dev location, which is stale and hasn't picked up the granular bundles - flagged to the DE team separately.