Conversation
Turn 3.33 on and make it the latest version. The docs version joins onlyIncludeVersions so it is built at all, and becomes lastVersion, serving at /calico/latest without the unreleased banner. 3.32 moves off /calico/latest to /calico/3.32 and loses the "(latest)" label. The baseUrl in each version's variables.js follows, by way of scripts/switch-latest.sh. Redirects follow the same move: /calico/3.33 now points at /calico/latest, in place of the 3.32 rule, so the numbered path for the latest version keeps working, and the manifests redirect points at the v3.33.0 tag. The documentation archive lists 3.33 as latest and gives 3.32 its own numbered link. Do not merge before the v3.33.0 tag is published. The manifests redirect and manifestsUrl both resolve against it.
✅ 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? →
|
Cover the two features that carry a PMREQ for this release. eBPF QoS connection limits is a bullet rather than a section: the release lifts a restriction rather than adding a capability, and the annotations themselves are unchanged. The OpenStack resync work gets a section, because it adds a command and changes how reconciliation happens. Its upgrade note carries the removal of the periodic resync and the two options that are now no-ops.
Native v3 CRDs and selector-scoped Felix configuration both move from technology preview to generally available, as confirmed in the docs channel: Casey for v3 CRDs, Tomas for the selector-scoped configuration. FIPS mode moves from deprecated to removed. It has been deprecated since 3.30, the build support was removed upstream in projectcalico/calico PR 12883, and the page was removed from the next tree the following day. The fipsMode field stays in the installation API reference, because that field belongs to the operator and is removed separately.
The table shows each feature's status per release, but not what moved in this one, so a reader has to compare columns to find it. The deprecated section already carries that as a short list; give the technology preview section the same, with links to the two promoted features.
Take the 229 entries from release-notes/v3.33.0-release-notes.md in projectcalico/calico, which arrive in a single Other changes list, and split them into Enhancements, after the OpenStack feature, and Bug fixes. Dropped 27 entries that carry no information for a reader: 24 whose release note is the literal None or TBD, a revert of a change that never shipped, and two that describe only the test harness. Dropped two duplicates. That leaves 99 enhancements and 101 bug fixes. Other changes is removed, because every entry now sits in one of the two sections. One entry needed escaping: a comparison written as libvirt<9.5.0 starts a JSX tag as far as MDX is concerned, and failed the build.
The 3.33 variables were rebuilt from the 3.32 file, and vppbranch was bumped along with every other version. It should not have been: vpp-dataplane releases on its own cadence and its newest tag is v3.32.0, so the bump pointed all fifteen VPP manifest and script links at a tag that does not exist, and the link checker failed the build once 3.33 became latest. Point it back at v3.32.0 and say why, so the next cut does not repeat it.
Give every feature in New features and enhancements its own heading, as 3.32 does, rather than leaving two of the three as bullets: native v3 CRDs as the default for new installs, and eBPF enforcement of the established connection limit annotations. Rename Enhancements to Other changes and move it below Bug fixes, which is where 3.32 carries the same content. The generated entries are the upstream changelog either way, and grouping them under the heading 3.32 used keeps consecutive releases readable side by side. Drop the drafting note from New features and enhancements, now that the section is written.
Move native v3 CRDs out of New features and enhancements and into the upgrade notes. The change is about what a new install gets rather than what this release adds, and what a reader needs is to know an upgrade does not move them, so it belongs with the other upgrade guidance. That leaves the feature section as the two features that carry a PMREQ. Give all three notes the same shape: a heading, a statement of whether the change is breaking, a description, then numbered steps. The ingress gateway note kept its wording but its description and steps move out of the warning admonition, so the admonition says only that the change breaks things and the steps read the same as the others.
Selector-scoped Felix configuration is generally available in 3.33, as Tomas confirmed, so drop the tech preview admonition from the FelixConfiguration reference, the inline marker in the configuration precedence list, and the Tech Preview prefix the upstream changelog entry still carried. The feature status table already showed the promotion; the pages contradicted it. Set the general availability date to 29 September 2026, replacing the placeholder the template shipped with. Put the OpenStack resync feature ahead of the eBPF connection limits one.
There was a problem hiding this comment.
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Copilot review overview
Review effort: Lite
Findings: 2
| * [Calico Open Source 3.33](https://docs.tigera.io/calico/latest/about) | ||
| * [Calico Open Source 3.32](https://docs.tigera.io/calico/3.32/about) |
| /v3.15/manifests/* https://downloads.tigera.io/ee/v3.15.1/manifests/:splat 301! | ||
|
|
||
| /calico/latest/manifests/* https://raw.githubusercontent.com/projectcalico/calico/v3.32.0/manifests/:splat 302 | ||
| /calico/latest/manifests/* https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/:splat 302 |
Replace the placeholder with the generated FOSSA report for projectcalico/calico at 2fffb7e, the release-v3.33 branch head. The report is a different template from the one 3.32 shipped. It is table-based rather than heading-based, covers considerably more dependencies, and loads its fonts from cdn.app.fossa.com instead of a self-hosted path. The file is generated output and is committed as produced, without editing.
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Resolve the outstanding documentation inconsistencies, known-issue coverage, test updates, and tag prerequisite before approval.
Review effort: Lite
Findings: 1
Open (5)
v3.33.0Git tag existing and being publicly readable; until the…/calico/latest/about, which will become incorrect once…
| The default applies to new clusters only, so upgrading does not move you to it. | ||
|
|
||
| 1. Upgrade $[prodname]. Nothing is required to keep serving the API the way you do today. | ||
| 2. When you next install a new cluster, check that it runs Kubernetes 1.32 or later, which v3 CRD mode requires. To put a new cluster on the aggregation API server instead, apply the v1 CRDs before you install the operator. |
| calico: | ||
| "3.28": ga | ||
| "3.30": deprecated | ||
| "3.33": removed |
| - Felix configuration docs no longer claim `(case insensitive)` on the env-var/config-file encoding of `oneof` parameters. Felix's parser still accepts any case at runtime; only the docs change. [calico 12846](https://github.com/projectcalico/calico/pull/12846) (@tomastigera) | ||
| - HELM: Render MutatingAdmissionPolicy and MutatingAdmissionPolicyBinding as admissionregistration.k8s.io/v1 when the cluster serves it (Kubernetes 1.36+), falling back to v1beta1 otherwise. [calico 12833](https://github.com/projectcalico/calico/pull/12833) (@caseydavenport) | ||
| - Prevent deletion of built-in tiers in CRD mode. [calico 12824](https://github.com/projectcalico/calico/pull/12824) (@caseydavenport) | ||
| - The Calico driver for OpenStack now overrides the Neutron `[DEFAULT] service_plugins` setting to ensure that it includes `qos`, as required for our QoS support. This means that it's no longer necessary for to configure `service_plugins` in `neutron.conf`, when using Calico. [calico 12798](https://github.com/projectcalico/calico/pull/12798) (@nelljerram) |
…ed image Both Dikastes sidecar templates deployed quay.io/calico/dikastes, which is one of the images 3.33 stopped publishing, so the sidecars would have failed to pull. Dikastes itself is still there, inside calico/calico, so the templates now use that image with the component command the combined binary needs. Envoy-based application layer policy is deprecated in Calico Enterprise and Calico Cloud but carries no deprecation status for Open Source, and this page has no notice on it, so it is a supported path in 3.33 and the manifests have to work.
The list was 1.32, 1.33 and 1.34, byte-identical to the 3.31 list and older than the one 3.32 publishes, so it was carried over at the version cut rather than set for this release. 3.33 tests against 1.35, 1.36 and 1.37. One partial feeds the Kubernetes, OpenStack, bare metal and OpenShift requirements pages, and the Windows page links to it.
The page said $[prodname] will not work on Kubernetes v1.20 or below and that v1.21 may work but is untested. Against a tested range starting at 1.35 that tells a reader nothing, and the sentence above it already says untested versions may work.
The groupings were scaffolding for us, not something a reader needs. The page is now a flat list of notes, each at the same level, and each one already says who it affects. Provenance moves into an MDX comment above each note, giving the release it came from and the upstream PR where there is one, so we can still tell where a note originated without putting it on the page. The two notes that arrived in 3.32 now carry their own scoping, since the group heading that used to say so is gone. They state that they apply when upgrading from 3.31, and that a 3.32 cluster already has them.
| title: Upgrade notes | ||
| --- | ||
|
|
||
| # Upgrade notes |
Other changes sat between Bug fixes and Known issues, so the 99 enhancement entries read as a trailing appendix. They are enhancements, so they belong with the features, and nesting them puts them under New features and enhancements in the page contents rather than as a peer of it. Bug fixes keeps its own top-level section and its 101 entries.
The section holds the generated enhancement entries, and it now sits under New features and enhancements, so Other changes no longer describes it.
"eBPF: established connection limits" named the mechanism rather than the thing a reader is looking for, which is QoS controls. The heading now matches how the PMREQ frames it. The broader heading needs the body to be precise, or it reads as though QoS arrived on eBPF in this release. It did not: bandwidth and packet rate limits already worked there, and connection limits are what completes the set.
stevegaossou
left a comment
stevegaossou
left a comment
There was a problem hiding this comment.
Left come comments.
| Each note applies to every upgrade to $[version] unless it says otherwise. | ||
|
|
||
| Each note says who it affects, what changes, and what you need to do. | ||
| Where a note applies only to some upgrade paths, it says so. |
There was a problem hiding this comment.
Minor: This sentence feels like it's saying the same thing as a previous line, but in an inverted manner (line 10).
Each note applies to every upgrade to $[version] unless it says otherwise.
VS
Where a note applies only to some upgrade paths, it says so.
There was a problem hiding this comment.
Agreed, they were saying the same thing in two directions. The introduction is now three lines and states the default scope once.
| It lists the changes in each release that alter behavior you may depend on, and says what to do about each one. | ||
| Each note applies to every upgrade to $[version] unless it says otherwise. | ||
|
|
||
| Each note says who it affects, what changes, and what you need to do. |
There was a problem hiding this comment.
This line feels a bit unnecessary, like it's trying to be too expository.
| 2. Upgrade nodes that are too old, or move them to the standard data plane. | ||
| 3. Upgrade $[prodname]. | ||
|
|
||
| Some kernels inside the supported range have known problems in this release. Check the known issues in the [release notes](../../release-notes/index.mdx) before you plan the upgrade. |
There was a problem hiding this comment.
The Known Issues section on the release notes is currently empty. Would we remove this line if we end up not including any known issues?
There was a problem hiding this comment.
Fair question. The line is there because the eBPF note declares a 5.10 floor while a kernel inside that range is known to fail, and it seemed worse to state the floor and say nothing. It is tied to #3042, which carries that known issue and is still open against this branch. If #3042 is dropped, this line goes with it, and I will do that in the same change rather than leave a pointer to an empty section.
| The operator selects the mode from the CRDs already present. | ||
| What changed is the default for a brand new install, which is now v3 CRD mode. | ||
| On Kubernetes 1.35 that mode also needs the `MutatingAdmissionPolicy` feature gate enabled on the API server, because the beta API exists there but is not on by default. | ||
| From 1.36 the feature is generally available and enabled for you. | ||
|
|
||
| 1. Upgrade $[prodname]. Your cluster keeps the mechanism it already uses. | ||
| 2. To move an existing cluster onto native v3 CRDs deliberately, follow [Migrate from API server to native CRDs](../crd-migration.mdx). Plan a maintenance window: new pod scheduling and policy changes are blocked until the migration completes, and IPAM allocations are blocked during its final phase. |
There was a problem hiding this comment.
This information is generally useful. But since this doesn't affect upgrades, as the earlier statements mention, is this the right place to have it?
I suppose is there is no better alternative to put this, then it's better here than being left unsaid. I just wonder if it might make some users confused because it says that upgrades are affected but then talks about switching to native v3 CRDs. That's sort of an action that takes place after an upgrade is complete.
There was a problem hiding this comment.
I take the point, and it is the one note on the page that is not an action. It earns its place because the default changed underneath people: someone who installs a new cluster after upgrading gets a different API mechanism than they got last month, and the first thing they will want to know is whether the upgrade did that to their existing cluster. It did not, and the note exists to say so.
The migration link is the part you are right to question. Migrating is a deliberate later act, not an upgrade step. I have left it because a reader who has just learned the default changed will ask how to move, and sending them away with nothing seemed worse. Happy to cut the step and leave only the reassurance if you would rather the page held nothing post-upgrade.
|
|
||
| This affects you if any node runs containerd earlier than v1.6, or CRI-O earlier than v1.24. | ||
|
|
||
| The default CNI configuration now declares `cniVersion` 1.0.0, up from 0.3.1. |
There was a problem hiding this comment.
Hmm, I don't think is is new to v3.33.0.
It was backported from mater, and the change to 1.0.0 is also in v3.32.2 and v3.31.7.
It only affects upgrades from 3.31.0–3.31.6 and 3.32.0–3.32.1. Also, 3.33 supports only Kubernetes 1.35+, so a node running containerd older than 1.6 is unlikely. This section might not be worth keeping.
There was a problem hiding this comment.
Confirmed and removed in 83ec454. PRs 13378 and 13379 backported it to release-v3.31 and release-v3.32, so it affects only upgrades from 3.31.0 to 3.31.6 and 3.32.0 to 3.32.1. Your second point stands on its own too: with 3.33 supporting Kubernetes 1.35 and later, a node on containerd below v1.6 is not a realistic combination.
|
|
||
| Most components now ship inside one `calico/calico` image. | ||
| The images it replaces are not published for 3.33 at all, so a mirror or a pinned reference to any of them fails to pull after the upgrade. | ||
| Fourteen images are no longer published: `calico/typha`, `calico/cni`, `calico/ctl`, `calico/apiserver`, `calico/kube-controllers`, `calico/goldmane`, `calico/dikastes`, `calico/csi`, `calico/node-driver-registrar`, `calico/pod2daemon-flexvol`, `calico/key-cert-provisioner`, `calico/flannel-migration-controller`, `calico/whisker-backend`, and `flexvol`. |
There was a problem hiding this comment.
@ctauchen where did flexvol come from? I don't think that is a valid component image from previous release streams.
There was a problem hiding this comment.
Hmm, okay I went down a rabbit hole with this one. I noticed the older release notes mention both and
But when I did a deeper dive with Claude:
What I checked just now
- The release tooling. On release-v3.30, the pinned-versions template uses the key flexvol:. The tooling's image map resolves it with "flexvol": "calico/pod2daemon-flexvol". It's an old component alias, like "calicoctl": "calico/ctl".
- The docs page you linked. The table shows component keys from releases.json, not image names. For v3.30.7 that file has both calico/pod2daemon-flexvol and flexvol. The v3.32.2 file does the same, next to flannel, which maps to coreos/flannel and isn't a Calico image at all.
- Docker Hub.
- calico/flexvol:v3.30.7 and calico/flexvol:v3.32.2 return 404.
- calico/pod2daemon-flexvol returns 200 for both versions.
- Quay answered 401 for calico/flexvol, which proves nothing on its own: a private repo and a missing one can both return that.
So the page shows "flexvol" as a component, but no public image by that name exists. It's calico/pod2daemon-flexvol listed a second time. If you know of a registry where calico/flexvol is published, please send it and I'll correct this.
This also seems to explain the page's image list. The v3.32.2 releases.json doesn't list calico/webhooks or calico/guardian, yet both images exist on Docker Hub and Quay for v3.32.2 (I checked). Someone building the list from releases.json would include flexvol and leave out those two, which is exactly what the page does. So the webhooks and guardian finding still stands.
This is a bit of a deeper issue than just saying flexvol doesn't exist. I'll let you guys decide what you want to do with this information.
I suppose we could just leave it (harmless confusion) and in the latest minor it gets cleaned up either way (removed because it is consolidated now).
There was a problem hiding this comment.
Good dig, and the conclusion holds. calico/pod2daemon-flexvol resolves on quay and calico/flexvol does not, so flexvol is an alias that releases.json lists a second time rather than an image anyone can pull. Removed, and the count drops to thirteen, in 83ec454. The wider point about releases.json being an unreliable source for an image list is worth its own ticket, since it is wrong in both directions: it invents flexvol and omits images that do exist.
There was a problem hiding this comment.
Same thread as above; fixed.
| Most components now ship inside one `calico/calico` image. | ||
| The images it replaces are not published for 3.33 at all, so a mirror or a pinned reference to any of them fails to pull after the upgrade. | ||
| Fourteen images are no longer published: `calico/typha`, `calico/cni`, `calico/ctl`, `calico/apiserver`, `calico/kube-controllers`, `calico/goldmane`, `calico/dikastes`, `calico/csi`, `calico/node-driver-registrar`, `calico/pod2daemon-flexvol`, `calico/key-cert-provisioner`, `calico/flannel-migration-controller`, `calico/whisker-backend`, and `flexvol`. | ||
| `calico/node`, `calico/whisker`, the Windows images and the Envoy images are still published separately. |
There was a problem hiding this comment.
Should also mention the Istio images. They are third-party images we publish, similar to Envoy.
Might also want to mention calico/third-party-cni-plugins.
There was a problem hiding this comment.
Added in 83ec454. The line now reads: calico/node, calico/whisker, calico/third-party-cni-plugins, the Windows images, the Envoy images and the Istio images. I checked each against a release-v3.33 tag on quay rather than taking them from releases.json.
|
|
||
| ## Felix metrics endpoint no longer requires client certificates by default | ||
|
|
||
| This affects you if you scrape the Felix Prometheus metrics endpoint and have never set `prometheusMetricsClientAuth`. |
There was a problem hiding this comment.
I believe it's possible to set up the metrics endpoint without HTTPS.
If a user configures it with HTTP instead, this won't should not apply to them. I think it's worth calling out this is for those using HTTPS.
There was a problem hiding this comment.
Correct, and the default is the other way round from what the note assumed. prometheusMetricsCertFile and prometheusMetricsKeyFile both default to empty, so the endpoint serves plain HTTP unless you configure TLS, and client certificates never applied. The note is now scoped to readers who have set those two, and says plainly that nothing changes on HTTP. Fixed in 83ec454.
| Any host endpoint policy, global network policy, or external firewall rule written against the tunnel address stops matching. | ||
|
|
||
| 1. **Before you upgrade**, find any rule that matches a tunnel device address and rewrite it against the node's internal IP. | ||
| 2. To keep the old behavior instead, set `BPFOverlayIPOnDevice` to `true` in your `FelixConfiguration`. |
There was a problem hiding this comment.
Step 2 isn't possible, because it does not look like BPFOverlayIPOnDevice is an exposed setting in FelixConfiguration. So a user cannot access it.
There was a problem hiding this comment.
Okay, looked into this some more.
Looks like this is a problem with the original PR release note being stale.
projectcalico/calico#11919
The bottom line is:
- Upgrading doesn't change the behaviour, because the default keeps the IP on the tunnel device.
- The new behaviour is opt-in with bpfOverlayHostSourceIP: HostAddress.
- BPFOverlayIPOnDevice doesn't exist as a user setting in any release. It only existed in the PR's first commits.
Confirmed here in the PR:
cc @tomastigera what do you think about this section? I think we can remove it.
There was a problem hiding this comment.
You are right, and it is worse than a stale field name. Confirmed in the 3.33 Felix config reference: the setting is bpfOverlayHostSourceIP, and its default is TunnelAddress. BPFOverlayIPOnDevice appears nowhere. So the default preserves the old behaviour, the new behaviour is opt-in, and an upgrade changes nothing. That makes it not an upgrade note at all, and I have removed it in 83ec454. Thanks for reading the PR rather than the changelog entry.
There was a problem hiding this comment.
Covered by the reply on the later comment. The section is gone.
Two notes came from upstream changelog entries that do not match the code, and both are removed. The eBPF overlay note was wrong twice over. The field it told readers to set, BPFOverlayIPOnDevice, exists in no release; it appeared only in the first commits of the PR. The real setting is bpfOverlayHostSourceIP, and its default is TunnelAddress, so an upgrade keeps the old behavior and the new one is opt-in. There is nothing here for an upgrader to do. The CNI version note is not specific to this release. The change was backported to 3.31 and 3.32, so it affects only upgrades from 3.31.0 through 3.31.6 and 3.32.0 through 3.32.1, and the container runtime floor it warns about is implausible on the Kubernetes versions 3.33 supports. flexvol is not an image. It is an old component alias for pod2daemon-flexvol that releases.json lists a second time, so the count drops to thirteen. The images that survive now name the Istio images and third-party-cni-plugins alongside the rest. The Felix metrics note assumed HTTPS. The endpoint serves plain HTTP unless prometheusMetricsCertFile and prometheusMetricsKeyFile are set, and client certificates never applied in that case. Also trimmed two lines from the introduction that restated each other.
The generated notes were pulled before the release branch settled, so the docs were missing eight entries that landed afterwards. Six are bug fixes, including calico-node crash-looping on canal and policy-only installs, pods unable to restart when their IP pool is full, and 4-byte AS numbers above 2147483647 being rejected. Two are enhancements: the Envoy Gateway v1.9.1 bump and Felix and Typha applying the same schema checks to etcd reads that the API server applies on admission. Drop the entry for the reverted Sanitize log output change, which duplicated the version that actually landed. Fix four pieces of text that came across from the generated file: a calicoctl typo in the combined image entry, a garbled sentence in the OpenStack resync entry, and two smaller ones still present upstream. Three entries the upstream list carries stay out, because they describe the test harness and internal protobuf message names rather than anything a reader can act on.
Publishes 3.33 and adds its release notes. The version cut landed in #3040.
Do not merge before the v3.33.0 tag is published: the manifests redirect and manifestsUrl both resolve against it.