DOCS-3001: Publish Calico Open Source 3.33 - #3041
Merged
Merged
Conversation
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview succeeded!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
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
Comment on lines
+10
to
+11
| * [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 |
Contributor
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) |
ctauchen
commented
Sep 29, 2026
| title: Upgrade notes | ||
| --- | ||
|
|
||
| # Upgrade notes |
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.
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.
…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.
Collect the changes that need action at upgrade time onto one page, rather than leaving them in the release notes where a reader upgrading across several releases would have to find them one page at a time. Grouped by the release that introduced them, so skipping releases means reading every group in between. Every note follows the same shape: who it affects, named as something the reader can check; what changes and what happens if they do nothing; then numbered steps in upgrade order. Action-required notes come first. Nine notes for 3.33. Four are new from vetting the build PR discussion: the single calico image, the new policy rule and selector limits, the eBPF kernel floor, and the Felix metrics client auth default. Three move off the release notes. FIPS removal and the Envoy Gateway Kubernetes floor are drawn from the changelog. The three upgrade guides now name the page as the first thing to read, and the release notes point at it in both places an upgrade comes up.
Document only the upgrade paths we support. For 3.33 that is 3.31 and 3.32, so raise the floors the guides advertise, from v3.15 on Kubernetes and v3.0 on OpenStack, and say the supported range on every guide through a shared partial, so a release cut updates it in one place. Remove what only applied below that floor: - Upgrade OwnerReferences, which starts at v3.28, and was duplicated verbatim in the Kubernetes and OpenShift guides. - Three steps about cleaning up a temporary allow-all-upgrade policy after upgrading from earlier than v3.14. These were already broken: each told the reader to undo pre-upgrade steps "above" that no longer exist, because the component that creates that policy is imported by no page in 3.33 or 3.32. Delete the orphaned component with them. The OpenStack policy data migration stays. It applies to upgrades from earlier than v3.32, and 3.31 is a supported source.
Name no release numbers in the support statement. Hardcoding 3.31 and 3.32 puts a maintenance burden on every cut, and the numbers go stale silently. The partial and the guides now say the range relative to the release, and the surrounding sentences no longer pin a floor either. Drop the claim that upgrading from an earlier release means going to the previous one first. That is not true; $[prodname] has always documented upgrades across several releases, and N-2 scopes what we document rather than what is possible. Plain text rather than an admonition, merged with each guide's opening so the page does not introduce itself twice. The OpenStack policy data migration still names v3.32, which is correct. That is a behavior change in a specific release, not a support boundary.
Fixes found by reviewing the page against the pages and CRDs it describes, rather than against the release notes it was drafted from. Wrong, and would have cost a reader real time: - FIPS. Setting fipsMode to Enabled marks the installation degraded in 3.33, and that field is how an operator-managed cluster runs the -fips images. The note reassured the reader the field was staying and told them only to move off image tags, which is not the action that helps. - Native v3 CRDs need Kubernetes 1.34, not 1.32, and on 1.34 and 1.35 they also need the MutatingAdmissionPolicy feature gate, which is not on by default. - The single image note named 6 of the 14 images that stopped being published. The missing 8 include csi, node-driver-registrar and key-cert-provisioner, which are in the calico-node pod by default, so a mirrored registry would still have failed to pull. - Policy limits are ratcheted by Kubernetes, so an update that does not touch an over-limit field is accepted. Saying the policy is rejected by any update sends people into unnecessary policy splitting. The limits also do not apply on etcdv3, which has no CRDs. - The eBPF note contradicted both eBPF pages, which support Red Hat 8.4 on kernel 4.18.0-305 by backport. - The crd-migration pointer called the migration briefly locked. That page asks for a maintenance window. - The Ingress Gateway note asserted the Kubernetes versions $[prodname] supports. The 3.33 and 3.32 requirements pages disagree on that, so the note no longer makes the claim at all. Added, all of them changes that need action and had no coverage: - BPFAttachType defaults to Netkit, which must be changed before rolling back to a release without netkit support. - eBPF overlay traffic now uses the node's main IP, so rules matching a tunnel address stop matching. - The default CNI configuration requires containerd v1.6 or CRI-O v1.24. - Overlapping IP pools are rejected on write. Also: an Upgrading to 3.32 group, because the page tells readers to read every group between their version and the target, N-2 makes 3.31 a supported source, and the OpenStack policy-name migration lives there. Steps that named no command now name one. The OpenShift description no longer advertises the OwnerReferences section this branch removed.
- 3.32 dropped enforcement of AdminNetworkPolicy and BaselineAdminNetworkPolicy in favor of ClusterNetworkPolicy. Those resources stay in the cluster and stop taking effect, with no error, so a 3.31 source loses policy enforcement silently. Added to the 3.32 group, which previously held only the OpenStack migration. - The Ingress Gateway note gave a version floor without saying what happens below it. - The OpenStack note told readers to run calico-resync without saying it ships in its own package. - The yum and apt repository instructions told readers to substitute $[version], which renders v3.33 while the repository is calico-3.33. Following it literally gives calico-v3.33 and a failed update. Mine, from the N-2 commit.
3.33 tests against Kubernetes 1.35 to 1.37, so two notes warned about versions no supported cluster can be on. The Ingress Gateway note led with Envoy Gateway's 1.33 floor, which every supported cluster clears by two minors. What still bites is the Gateway API CRD bump to v1.6, so the note is now about that, and keeps the two fields it rejects. The native v3 CRDs note gave a 1.34 floor and a feature gate needed on 1.34 and 1.35. Only 1.35 is in range, so only 1.35 needs the gate, and from 1.36 the feature is generally available.
The group headings read "Upgrading to 3.33" and "Upgrading to 3.32", but nobody reading the 3.33 docs is upgrading to 3.32. The second group holds changes that arrived in 3.32 and still need action if you are coming from 3.31 and jumping over it, which is what its own subtitle said while the heading above it said the opposite. Headings now name the release the change came from, and the page introduction tells you to read every group newer than the version you are upgrading from.
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.
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.
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.
danudey
force-pushed
the
publish/oss-3.33
branch
from
October 2, 2026 00:20
bf824f8 to
56e7ad4
Compare
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Resolve the unavailable ImageSet references and contradictory upgrade guidance.
Review effort: Lite
Findings: 1
Open (6)
v3.33.0Git tag existing and being publicly readable; until the…/calico/latest/about, which will become incorrect once…
Comment on lines
+18
to
+20
| 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. | ||
| Thirteen 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` and `calico/whisker-backend`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.