From f253198b2d1de46dab677eda7538bef5a85ed015 Mon Sep 17 00:00:00 2001 From: Chris Tauchen Date: Tue, 29 Sep 2026 15:23:39 +0100 Subject: [PATCH 1/8] DOCS-3001: Add an upgrade notes page 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. --- .../upgrading/kubernetes-upgrade.mdx | 2 + .../upgrading/openshift-upgrade.mdx | 2 + .../upgrading/openstack-upgrade.mdx | 2 + .../operations/upgrading/upgrade-notes.mdx | 133 ++++++++++++++++++ .../version-3.33/release-notes/index.mdx | 44 +----- .../version-3.33-sidebars.json | 1 + 6 files changed, 143 insertions(+), 41 deletions(-) create mode 100644 calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/kubernetes-upgrade.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/kubernetes-upgrade.mdx index 03c9fafcf1..b17fa8b1fe 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/kubernetes-upgrade.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/kubernetes-upgrade.mdx @@ -14,6 +14,8 @@ Upgrading does not change your cluster's CRD mode. A cluster using the aggregati ::: +Before you start, review the [upgrade notes](upgrade-notes.mdx) for changes in each release that need your attention. + This page describes how to upgrade to $[version] from $[prodname] v3.15 or later. The procedure varies by datastore type and install method. diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx index b063a4a74f..1746a7ff8b 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx @@ -9,6 +9,8 @@ import InstallOpenShiftManifests from '@site/calico_versioned_docs/version-3.33/ ## About upgrading $[prodname] +Before you start, review the [upgrade notes](upgrade-notes.mdx) for changes in each release that need your attention. + This page describes how to upgrade to $[version] for OpenShift 4 from an existing $[prodname] cluster. ## Upgrade OwnerReferences diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx index 91e306dd17..91a6968d4d 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx @@ -6,6 +6,8 @@ description: Upgrade Calico Open Source on OpenStack from v3.0 or later by updat ## $[prodname] package update +Before you start, review the [upgrade notes](upgrade-notes.mdx) for changes in each release that need your attention. + This page describes how to upgrade to $[version] from $[prodname] v3.0 or later. The procedure varies by Linux distribution. diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx new file mode 100644 index 0000000000..34cb0e115b --- /dev/null +++ b/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx @@ -0,0 +1,133 @@ +--- +description: Changes in each Calico Open Source release that need your attention before or during an upgrade, with the action to take for each. +title: Upgrade notes +--- + +# Upgrade notes + +Review this page before you upgrade. +It lists the changes in each release that alter behavior you may depend on, and says what to do about each one. +Notes are grouped by the release that introduced them, so if you are skipping releases, read every group between the version you are on and the version you are upgrading to. + +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. + +## Upgrading to 3.33 + +These apply when you upgrade to 3.33 from an earlier release. + +### Calico ships as a single image + +This affects you if you mirror $[prodname] images into a private registry, pin image names or digests, or scan specific images. + +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 `calico/typha`, `calico/cni`, `calico/ctl`, `calico/apiserver`, `calico/kube-controllers` or `calico/goldmane` fails to pull after the upgrade. +Release artifacts changed for the same reason. + +1. **Before you upgrade**, mirror `calico/calico` into your registry. +2. Update any image pins, digests, or scanner configuration that name the replaced images. +3. Upgrade $[prodname]. + +### Limits on policy rules and selectors + +This affects you if you generate $[prodname] network policy programmatically, or have policies with very large rule lists, address lists, or selectors. + +$[prodname] network policy types now declare size limits in their CRD schemas, which the Kubernetes API server enforces on every write: + +| Field | Limit | +| --- | --- | +| Ingress rules, egress rules | 1024 each | +| `selector`, `notSelector`, `namespaceSelector`, `serviceAccountSelector` | 1024 characters | +| `nets`, `notNets` | 256 entries per rule | +| `ports`, `notPorts` | 50 entries per rule | +| HTTP `methods`, `paths` | 20 entries per rule | + +Policies already stored in the datastore keep working. +The limits apply when a policy is written, so a policy that exceeds one is rejected the next time anything updates it, including your own tooling. + +1. **Before you upgrade**, check whether any existing policy exceeds a limit, and whether the tooling that generates your policy can produce one that does. +2. Split any policy that exceeds a limit, or narrow the field that does. +3. Upgrade $[prodname]. + +### Calico Ingress Gateway proxies move namespace + +:::warning[Breaking change] + +Gateway proxies move namespace on upgrade, and merged gateways are no longer supported. + +::: + +This affects you if you use $[prodname] Ingress Gateway. + +Each gateway's proxy now runs in the same namespace as its `Gateway`, and the controller moves to `calico-system`. +Existing proxies move out of the `tigera-gateway` namespace, so anything pinned to `tigera-gateway` — network policy, monitoring, and external DNS — stops matching them. +Merged gateways (`mergeGateways: true`) are no longer supported, so each gateway gets its own load balancer. + +1. **Before you upgrade**, if you run a global default deny policy, create a network policy in each Gateway's namespace that allows the proxy pods, so they can start as soon as they move. For the policy, see [Create an ingress gateway](../../networking/ingress-gateway/create-ingress-gateway.mdx). +2. Upgrade $[prodname]. +3. Re-point monitoring and external DNS from `tigera-gateway` to each Gateway's namespace. If you used merged gateways, plan for one load balancer, DNS record, and certificate per gateway. + +### Calico Ingress Gateway requires Kubernetes 1.33 + +This affects you if you use $[prodname] Ingress Gateway. +It does not change the Kubernetes versions $[prodname] itself supports, which remain 1.32, 1.33 and 1.34. + +The bundled Envoy Gateway moves to v1.9.1, which raises its own minimum Kubernetes version to 1.33. + +1. **Before you upgrade**, if you use Ingress Gateway on Kubernetes 1.32, upgrade the cluster to 1.33 or later. + +### eBPF data plane requires kernel 5.10 or later + +This affects you if you run the eBPF data plane on nodes with a kernel earlier than 5.10, or a kernel built without BTF and CO-RE support. + +The runtime fallback paths for older kernels are gone. +Instead of degrading, $[prodname] now reports a clear health message and does not program the data plane on an unsupported node. + +1. **Before you upgrade**, check the kernel version and BTF support on every node running the eBPF data plane. +2. Upgrade nodes that are too old, or move them to the standard data plane. +3. Upgrade $[prodname]. + +Check the [release notes](../../release-notes/index.mdx) for known issues affecting specific kernel versions before you plan the upgrade. + +### 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`. + +The default changes from `RequireAndVerifyClientCert` to `NoClientCert`. +Nothing fails, and no scrape breaks. +The endpoint simply stops requiring a client certificate, so a protection you had by default is gone after the upgrade. + +1. **Before you upgrade**, if you rely on that protection, set `prometheusMetricsClientAuth: RequireAndVerifyClientCert` explicitly in your `FelixConfiguration`. + +### FIPS mode is removed + +This affects you if you run the `-fips` image variants. + +$[prodname] no longer publishes `-fips` tagged images or boringcrypto binaries. +FIPS mode was deprecated in 3.30. +The `fipsMode` field remains on the operator Installation API for now, because that field belongs to the operator and is removed separately. + +1. **Before you upgrade**, move off the `-fips` images. + +### New installs default to native v3 CRDs + +No action is required. This note is here because the default changed, not because an upgrade changes your cluster. + +An upgrade never switches an existing cluster between the aggregation API server and native v3 CRDs. +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, and which requires Kubernetes 1.32 or later. + +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). The datastore is briefly locked during the migration. + +### OpenStack no longer resyncs on a timer + +This affects you if you run $[prodname] for OpenStack and relied on the periodic resync to recover from drift. + +The periodic resync is gone. +`resync_interval_secs` and `resync_max_interval_secs` are now no-ops, retained only so that an existing `neutron.conf` does not break. +The driver resyncs once when the Neutron server starts, and on demand after that. + +1. Upgrade $[prodname]. +2. Remove `resync_interval_secs` and `resync_max_interval_secs` from `neutron.conf` at your convenience. +3. Run `calico-resync` when you need an immediate reconciliation. To drive reconciliation entirely by hand, set `startup_resync = never`. See [Resync between Neutron and etcd](../../networking/openstack/resync.mdx). diff --git a/calico_versioned_docs/version-3.33/release-notes/index.mdx b/calico_versioned_docs/version-3.33/release-notes/index.mdx index 157a94a388..09d7c447eb 100644 --- a/calico_versioned_docs/version-3.33/release-notes/index.mdx +++ b/calico_versioned_docs/version-3.33/release-notes/index.mdx @@ -268,47 +268,9 @@ You should consider migrating away from a deprecated feature before it is remove ## Upgrade notes -### Calico Ingress Gateway +3.33 changes several things that may need action before or during an upgrade, including the move to a single `calico/calico` image, new size limits on policy rules and selectors, and a namespace move for Calico Ingress Gateway proxies. -:::warning[Breaking change] - -Gateway proxies move namespace on upgrade, and merged gateways are no longer supported. - -::: - -Calico Ingress Gateway now runs each gateway's proxy in the same namespace as its `Gateway`, and the controller moves to `calico-system`. -Existing proxies move out of the `tigera-gateway` namespace into each Gateway's namespace, so anything pinned to `tigera-gateway` — network policy, monitoring, and external DNS — must move with them. -Merged gateways (`mergeGateways: true`) are no longer supported, so each gateway gets its own load balancer. - -1. **Before you upgrade**, if you run a global default deny policy, create a network policy in each Gateway's namespace that allows the proxy pods, so they can start as soon as they move. For the policy, see [Create an ingress gateway](../networking/ingress-gateway/create-ingress-gateway.mdx). -2. Upgrade $[prodname]. -3. Re-point monitoring and external DNS from `tigera-gateway` to each Gateway's namespace. If you used merged gateways, plan for one load balancer, DNS record, and certificate per gateway. - -### Native v3 CRDs by default - -This is not a breaking change. An upgrade leaves an existing cluster on the mechanism it already uses. - -New installs now default to v3 CRD mode, where `projectcalico.org/v3` resources are served directly by CRDs with no aggregation API server. -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. -3. To move an existing cluster onto native v3 CRDs, follow [Migrate from API server to native CRDs](../operations/crd-migration.mdx). The datastore is briefly locked during the migration. - -For more information, see [Native v3 CRDs](../operations/native-v3-crds.mdx). - -### OpenStack resync - -This is not a breaking change. An existing `neutron.conf` keeps working untouched. - -The periodic resync is gone. -`resync_interval_secs` and `resync_max_interval_secs` are now no-ops, retained only so that an existing configuration does not break. - -1. Upgrade $[prodname]. The driver resyncs once when the Neutron server restarts. -2. Remove `resync_interval_secs` and `resync_max_interval_secs` from `neutron.conf` at your convenience. -3. If you relied on the periodic resync to recover from drift, run `calico-resync` when you need an immediate reconciliation. To resync from somewhere other than the Neutron server's own startup, set `startup_resync = never` and drive it entirely from the command. - -For more information, see [Resync between Neutron and etcd](../networking/openstack/resync.mdx). +Review the [upgrade notes](../operations/upgrading/upgrade-notes.mdx) before you upgrade. ## Release details @@ -320,7 +282,7 @@ Calico Open Source release 3.33.0 is now generally available. #### Updating -To update a previous version of Calico, see [our upgrade guides](../operations/upgrading/index.mdx). +Review the [upgrade notes](../operations/upgrading/upgrade-notes.mdx), then follow [our upgrade guides](../operations/upgrading/index.mdx). {/* ### Calico Open Source 3.33.1 bug fix release diff --git a/calico_versioned_sidebars/version-3.33-sidebars.json b/calico_versioned_sidebars/version-3.33-sidebars.json index 2646bf649e..46d4df79bf 100644 --- a/calico_versioned_sidebars/version-3.33-sidebars.json +++ b/calico_versioned_sidebars/version-3.33-sidebars.json @@ -173,6 +173,7 @@ "id": "operations/upgrading/index" }, "items": [ + "operations/upgrading/upgrade-notes", "operations/upgrading/kubernetes-upgrade", "operations/upgrading/openshift-upgrade", "operations/upgrading/openstack-upgrade" From 02e53e13224acc8627f520dc018cbb5274f39359 Mon Sep 17 00:00:00 2001 From: Chris Tauchen Date: Tue, 29 Sep 2026 15:37:02 +0100 Subject: [PATCH 2/8] DOCS-3001: Scope the upgrade guides to N-2 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. --- .../components/HostEndpointsUpgrade.js | 84 ------------------- .../partials/_upgrade-supported-versions.mdx | 7 ++ .../upgrading/kubernetes-upgrade.mdx | 26 ++---- .../upgrading/openshift-upgrade.mdx | 19 +---- .../upgrading/openstack-upgrade.mdx | 17 ++-- 5 files changed, 27 insertions(+), 126 deletions(-) delete mode 100644 calico_versioned_docs/version-3.33/_includes/components/HostEndpointsUpgrade.js create mode 100644 calico_versioned_docs/version-3.33/_includes/partials/_upgrade-supported-versions.mdx diff --git a/calico_versioned_docs/version-3.33/_includes/components/HostEndpointsUpgrade.js b/calico_versioned_docs/version-3.33/_includes/components/HostEndpointsUpgrade.js deleted file mode 100644 index 9917435247..0000000000 --- a/calico_versioned_docs/version-3.33/_includes/components/HostEndpointsUpgrade.js +++ /dev/null @@ -1,84 +0,0 @@ -import React from 'react'; -import Admonition from '@theme/Admonition'; -import CodeBlock from '@theme/CodeBlock'; -import Heading from '@theme/Heading'; - -import { prodname, version } from '../../variables'; - -export default function HostEndpointsUpgrade(props) { - return ( - <> - - Host endpoints - - - If your cluster has host endpoints with interfaceName: * you must prepare your cluster before - upgrading. Failure to do so will result in an outage. - -

- In versions of {prodname} prior to v3.14, all-interfaces host endpoints (host endpoints with{' '} - interfaceName: *) only supported pre-DNAT policy. The default behavior of all-interfaces host - endpoints, in the absence of any policy, was to allow all traffic. -

-

- Beginning from v3.14, all-interfaces host endpoints support normal policy in addition to pre-DNAT policy. The - support for normal policy includes a change in default behavior for all-interfaces host endpoints: in the - absence of policy the default behavior is to drop traffic. This default behavior is consistent - with "named" host endpoints (which specify a named interface such as "eth0"); named host - endpoints drop traffic in the absence of policy. -

-

- Before upgrading to {version}, you must ensure that global network policies are in place that select existing - all-interfaces host endpoints and explicitly allow existing traffic flows. As a starting point, you can create - an allow-all policy that selects existing all-interfaces host endpoints. First, we'll add a label to the - existing host endpoints. Get a list of the nodes that have an all-interfaces host endpoint: -

- calicoctl get hep -owide | grep | awk '"{'print $1'}"' -

- With the names of the all-interfaces host endpoints, we can label each host endpoint with a new label (for - example, host-endpoint-upgrade: ""): -

- - calicoctl get hep -owide | grep '*' | awk '"{'print $1'}"' \ -
- {props.orch === 'OpenShift' - ? '| xargs -I {} oc exec -i -n kube-system calicoctl -- calicoctl label hostendpoint {} host-endpoint-upgrade=' - : '| xargs -I {} kubectl exec -i -n kube-system calicoctl -- calicoctl label hostendpoint {} host-endpoint-upgrade= '} - -

- Now that the nodes with an all-interfaces host endpoint are labeled with host-endpoint-upgrade, - we can create a policy to log and allow all traffic going into or out of the host endpoints temporarily: -

- - {`cat > allow-all-upgrade.yaml < -

Apply the policy:

- calicoctl apply -f - {'<'} allow-all-upgrade.yaml -

- After applying this policy, all-interfaces host endpoints will log and allow all traffic through them. This - policy will allow all traffic not accounted for by other policies. After upgrading, please review syslog logs - for traffic going through the host endpoints and update the policy as needed to secure traffic to the host - endpoints. -

- - ); -} diff --git a/calico_versioned_docs/version-3.33/_includes/partials/_upgrade-supported-versions.mdx b/calico_versioned_docs/version-3.33/_includes/partials/_upgrade-supported-versions.mdx new file mode 100644 index 0000000000..4133043dd9 --- /dev/null +++ b/calico_versioned_docs/version-3.33/_includes/partials/_upgrade-supported-versions.mdx @@ -0,0 +1,7 @@ +:::note[Supported upgrade paths] + +You can upgrade to $[version] from either of the two previous releases, v3.31 and v3.32. + +To upgrade from an earlier release, upgrade to v3.32 first, following the upgrade documentation for that release. + +::: diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/kubernetes-upgrade.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/kubernetes-upgrade.mdx index b17fa8b1fe..27771d326c 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/kubernetes-upgrade.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/kubernetes-upgrade.mdx @@ -1,7 +1,9 @@ --- -description: Upgrade Calico Open Source on Kubernetes from v3.15 or later for Helm, operator-managed, and manifest-based installs on both Kubernetes API and etcd datastores. +description: Upgrade Calico Open Source on Kubernetes from v3.31 or later for Helm, operator-managed, and manifest-based installs on both Kubernetes API and etcd datastores. --- +import UpgradeSupportedVersions from '../../_includes/partials/_upgrade-supported-versions.mdx'; + import AutoHostendpointsMigrate from '@site/calico_versioned_docs/version-3.33/_includes/components/AutoHostendpointsMigrate'; # Upgrade Calico on Kubernetes @@ -16,7 +18,9 @@ Upgrading does not change your cluster's CRD mode. A cluster using the aggregati Before you start, review the [upgrade notes](upgrade-notes.mdx) for changes in each release that need your attention. -This page describes how to upgrade to $[version] from $[prodname] v3.15 or later. The + + +This page describes how to upgrade to $[version] from $[prodname] v3.31 or later. The procedure varies by datastore type and install method. If you are using $[prodname] in etcd mode on a Kubernetes cluster, we recommend upgrading to the Kubernetes API datastore [as discussed here](../datastore-migration.mdx). @@ -38,18 +42,6 @@ This may result in unexpected behavior and data. ::: -## Upgrade OwnerReferences - -If you do not use OwnerReferences on resources in the projectcalico.org/v3 API group, you can skip this section. - -Starting in $[prodname] v3.28, a change in the way UIDs are generated for projectcalico.org/v3 resources requires that you update any OwnerReferences -that refer to projectcalico.org/v3 resources as an owner. After upgrade, the UID for all projectcalico.org/v3 resources will be changed, resulting in any -owned resources being garbage collected by Kubernetes. - -1. Remove any OwnerReferences from resources in your cluster that have `apiGroup: projectcalico.org/v3`. -1. Perform the upgrade normally. -1. Add new OwnerReferences to your resources referencing the new UID. - ## Upgrading an installation that was installed using Helm The `tigera-operator` chart does not contain the $[prodname] CRDs, since Helm does not upgrade CRDs on `helm upgrade`. There are two ways to get the $[version] CRDs into your cluster: @@ -186,9 +178,6 @@ To apply the CRDs yourself: 1. If you have [enable application layer policy](../../network-policy/istio/app-layer-policy.mdx), follow [the instructions below](#upgrading-if-you-have-application-layer-policy-enabled) to complete your upgrade. Skip this if you are not using Istio with $[prodname]. -1. If you were upgrading from a version of Calico prior to v3.14 and followed the pre-upgrade steps for host endpoints above, review traffic logs from the temporary policy, - add any global network policies needed to allow traffic, and delete the temporary network policy **allow-all-upgrade**. - 1. Congratulations! You have upgraded to $[prodname] $[version]. ## Upgrading an installation that uses an etcd datastore @@ -256,9 +245,6 @@ To apply the CRDs yourself: 1. If you have [enabled application layer policy](../../network-policy/istio/app-layer-policy.mdx), follow [the instructions below](#upgrading-if-you-have-application-layer-policy-enabled) to complete your upgrade. Skip this if you are not using Istio with $[prodname]. -1. If you were upgrading from a version of Calico prior to v3.14 and followed the pre-upgrade steps for host endpoints above, review traffic logs from the temporary policy, - add any global network policies needed to allow traffic, and delete the temporary network policy **allow-all-upgrade**. - 1. Congratulations! You have upgraded to $[prodname] $[version]. ## Upgrading if you have Application Layer Policy enabled diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx index 1746a7ff8b..aba071e47c 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx @@ -2,6 +2,8 @@ description: Upgrade Calico Open Source on OpenShift 4 by reapplying manifests and updating OwnerReferences for projectcalico.org/v3 resources. --- +import UpgradeSupportedVersions from '../../_includes/partials/_upgrade-supported-versions.mdx'; + import AutoHostendpointsMigrate from '@site/calico_versioned_docs/version-3.33/_includes/components/AutoHostendpointsMigrate'; import InstallOpenShiftManifests from '@site/calico_versioned_docs/version-3.33/_includes/components/InstallOpenShiftManifests'; @@ -11,19 +13,9 @@ import InstallOpenShiftManifests from '@site/calico_versioned_docs/version-3.33/ Before you start, review the [upgrade notes](upgrade-notes.mdx) for changes in each release that need your attention. -This page describes how to upgrade to $[version] for OpenShift 4 from an existing $[prodname] cluster. - -## Upgrade OwnerReferences - -If you do not use OwnerReferences on resources in the projectcalico.org/v3 API group, you can skip this section. + -Starting in Calico v3.28, a change in the way UIDs are generated for projectcalico.org/v3 resources requires that you update any OwnerReferences -that refer to projectcalico.org/v3 resources as an owner. After upgrade, the UID for all projectcalico.org/v3 resources will be changed, resulting in any -owned resources being garbage collected by Kubernetes. - -1. Remove any OwnerReferences from resources in your cluster that have `apiGroup: projectcalico.org/v3`. -1. Perform the upgrade normally. -1. Add new OwnerReferences to your resources referencing the new UID. +This page describes how to upgrade to $[version] for OpenShift 4 from an existing $[prodname] cluster. ## Upgrading Calico on OpenShift 4 @@ -55,7 +47,4 @@ You can now monitor the upgrade progress with the following command: watch oc get tigerastatus ``` -If you were upgrading from a version of Calico prior to v3.14 and followed the pre-upgrade steps for host endpoints above, review traffic logs from the temporary policy, -add any global network policies needed to allow traffic, and delete the temporary network policy **allow-all-upgrade**. - diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx index 91a6968d4d..d492462c7d 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx @@ -1,14 +1,18 @@ --- -description: Upgrade Calico Open Source on OpenStack from v3.0 or later by updating system packages on CentOS or Ubuntu compute and control nodes. +description: Upgrade Calico Open Source on OpenStack from v3.31 or later by updating system packages on CentOS or Ubuntu compute and control nodes. --- +import UpgradeSupportedVersions from '../../_includes/partials/_upgrade-supported-versions.mdx'; + # Upgrade Calico on OpenStack ## $[prodname] package update Before you start, review the [upgrade notes](upgrade-notes.mdx) for changes in each release that need your attention. -This page describes how to upgrade to $[version] from $[prodname] v3.0 or later. The procedure + + +This page describes how to upgrade to $[version] from $[prodname] v3.31 or later. The procedure varies by Linux distribution. - [Upgrading an OpenStack cluster based on CentOS](#upgrading-an-openstack-cluster-based-on-centos) @@ -35,9 +39,8 @@ This may result in unexpected behavior and data. sudo sed -i 's/calico-X.X/calico-Y.Y/g' /etc/yum.repos.d/calico.repo ``` - Replace `X.X` in the above command with the version you're upgrading from (must be v3.0 or later). - Replace `Y.Y` with the version of the release you're upgrading to. Example: if you are upgrading from v3.1 - to v3.5, replace `X.X` with `3.1` and replace `Y.Y` with `3.5`. + Replace `X.X` in the above command with the version you're upgrading from, and `Y.Y` with $[version]. + For example, upgrading from v3.32 to v3.33, replace `X.X` with `3.32` and replace `Y.Y` with `3.33`. 1. On all compute nodes, update packages: @@ -122,8 +125,8 @@ This may result in unexpected behavior and data. EOF ``` - Replace `X_X` and `X.X` with the version you're upgrading to. Example: if you're upgrading to v3.5, replace `X_X` with - `3_5` and replace `X.X` with `3.5`. Also replace `trusty` with the code name of your Ubuntu version. + Replace `X_X` and `X.X` with the version you're upgrading to. For example, upgrading to v3.33, replace `X_X` with + `3_33` and replace `X.X` with `3.33`. Also replace `trusty` with the code name of your Ubuntu version. 1. On all compute nodes, update packages: From 3aeaa4188c856c7154ba3a585722d1bf1fd01ab2 Mon Sep 17 00:00:00 2001 From: Chris Tauchen Date: Tue, 29 Sep 2026 15:45:24 +0100 Subject: [PATCH 3/8] DOCS-3001: Say the supported upgrade range without naming releases 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. --- .../partials/_upgrade-supported-versions.mdx | 8 +------- .../operations/upgrading/kubernetes-upgrade.mdx | 5 ++--- .../operations/upgrading/openshift-upgrade.mdx | 2 +- .../operations/upgrading/openstack-upgrade.mdx | 13 ++++++------- 4 files changed, 10 insertions(+), 18 deletions(-) diff --git a/calico_versioned_docs/version-3.33/_includes/partials/_upgrade-supported-versions.mdx b/calico_versioned_docs/version-3.33/_includes/partials/_upgrade-supported-versions.mdx index 4133043dd9..bbd4a320ea 100644 --- a/calico_versioned_docs/version-3.33/_includes/partials/_upgrade-supported-versions.mdx +++ b/calico_versioned_docs/version-3.33/_includes/partials/_upgrade-supported-versions.mdx @@ -1,7 +1 @@ -:::note[Supported upgrade paths] - -You can upgrade to $[version] from either of the two previous releases, v3.31 and v3.32. - -To upgrade from an earlier release, upgrade to v3.32 first, following the upgrade documentation for that release. - -::: +This page covers upgrading to $[version] from the two previous $[prodname] releases. diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/kubernetes-upgrade.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/kubernetes-upgrade.mdx index 27771d326c..11e19caed6 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/kubernetes-upgrade.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/kubernetes-upgrade.mdx @@ -1,5 +1,5 @@ --- -description: Upgrade Calico Open Source on Kubernetes from v3.31 or later for Helm, operator-managed, and manifest-based installs on both Kubernetes API and etcd datastores. +description: Upgrade Calico Open Source on Kubernetes for Helm, operator-managed, and manifest-based installs on both Kubernetes API and etcd datastores. --- import UpgradeSupportedVersions from '../../_includes/partials/_upgrade-supported-versions.mdx'; @@ -20,8 +20,7 @@ Before you start, review the [upgrade notes](upgrade-notes.mdx) for changes in e -This page describes how to upgrade to $[version] from $[prodname] v3.31 or later. The -procedure varies by datastore type and install method. +The procedure varies by datastore type and install method. If you are using $[prodname] in etcd mode on a Kubernetes cluster, we recommend upgrading to the Kubernetes API datastore [as discussed here](../datastore-migration.mdx). diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx index aba071e47c..8cc4396498 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx @@ -15,7 +15,7 @@ Before you start, review the [upgrade notes](upgrade-notes.mdx) for changes in e -This page describes how to upgrade to $[version] for OpenShift 4 from an existing $[prodname] cluster. +It applies to an existing $[prodname] cluster on OpenShift 4. ## Upgrading Calico on OpenShift 4 diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx index d492462c7d..484a2d039f 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx @@ -1,5 +1,5 @@ --- -description: Upgrade Calico Open Source on OpenStack from v3.31 or later by updating system packages on CentOS or Ubuntu compute and control nodes. +description: Upgrade Calico Open Source on OpenStack by updating system packages on CentOS or Ubuntu compute and control nodes. --- import UpgradeSupportedVersions from '../../_includes/partials/_upgrade-supported-versions.mdx'; @@ -12,8 +12,7 @@ Before you start, review the [upgrade notes](upgrade-notes.mdx) for changes in e -This page describes how to upgrade to $[version] from $[prodname] v3.31 or later. The procedure -varies by Linux distribution. +The procedure varies by Linux distribution. - [Upgrading an OpenStack cluster based on CentOS](#upgrading-an-openstack-cluster-based-on-centos) @@ -39,8 +38,8 @@ This may result in unexpected behavior and data. sudo sed -i 's/calico-X.X/calico-Y.Y/g' /etc/yum.repos.d/calico.repo ``` - Replace `X.X` in the above command with the version you're upgrading from, and `Y.Y` with $[version]. - For example, upgrading from v3.32 to v3.33, replace `X.X` with `3.32` and replace `Y.Y` with `3.33`. + Replace `X.X` in the above command with the version you're upgrading from, and `Y.Y` with $[version], + in both cases written as the major and minor version only. 1. On all compute nodes, update packages: @@ -125,8 +124,8 @@ This may result in unexpected behavior and data. EOF ``` - Replace `X_X` and `X.X` with the version you're upgrading to. For example, upgrading to v3.33, replace `X_X` with - `3_33` and replace `X.X` with `3.33`. Also replace `trusty` with the code name of your Ubuntu version. + Replace `X_X` and `X.X` with the version you're upgrading to, written with an underscore and a dot + respectively. Also replace `trusty` with the code name of your Ubuntu version. 1. On all compute nodes, update packages: From a7d3c8e2c399440bfa2677ac532a74cf5970dc28 Mon Sep 17 00:00:00 2001 From: Chris Tauchen Date: Tue, 29 Sep 2026 16:15:52 +0100 Subject: [PATCH 4/8] DOCS-3001: Correct and extend the upgrade notes after review 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. --- .../upgrading/openshift-upgrade.mdx | 2 +- .../operations/upgrading/upgrade-notes.mdx | 94 +++++++++++++++---- 2 files changed, 79 insertions(+), 17 deletions(-) diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx index 8cc4396498..b3b63488c1 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx @@ -1,5 +1,5 @@ --- -description: Upgrade Calico Open Source on OpenShift 4 by reapplying manifests and updating OwnerReferences for projectcalico.org/v3 resources. +description: Upgrade Calico Open Source on OpenShift 4 by reapplying the manifests for the new release. --- import UpgradeSupportedVersions from '../../_includes/partials/_upgrade-supported-versions.mdx'; diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx index 34cb0e115b..fd342ac623 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx @@ -21,8 +21,9 @@ These apply when you upgrade to 3.33 from an earlier release. This affects you if you mirror $[prodname] images into a private registry, pin image names or digests, or scan specific images. 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 `calico/typha`, `calico/cni`, `calico/ctl`, `calico/apiserver`, `calico/kube-controllers` or `calico/goldmane` fails to pull after the upgrade. -Release artifacts changed for the same reason. +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. 1. **Before you upgrade**, mirror `calico/calico` into your registry. 2. Update any image pins, digests, or scanner configuration that name the replaced images. @@ -42,8 +43,9 @@ $[prodname] network policy types now declare size limits in their CRD schemas, w | `ports`, `notPorts` | 50 entries per rule | | HTTP `methods`, `paths` | 20 entries per rule | -Policies already stored in the datastore keep working. -The limits apply when a policy is written, so a policy that exceeds one is rejected the next time anything updates it, including your own tooling. +Policies already stored in the datastore keep working, and an update that does not touch an over-limit field is still accepted, because Kubernetes ratchets CRD validation. +What fails is creating a policy over a limit, or updating the field that exceeds one. +These limits live in the CRDs, so they do not apply on the etcdv3 datastore. 1. **Before you upgrade**, check whether any existing policy exceeds a limit, and whether the tooling that generates your policy can produce one that does. 2. Split any policy that exceeds a limit, or narrow the field that does. @@ -70,24 +72,68 @@ Merged gateways (`mergeGateways: true`) are no longer supported, so each gateway ### Calico Ingress Gateway requires Kubernetes 1.33 This affects you if you use $[prodname] Ingress Gateway. -It does not change the Kubernetes versions $[prodname] itself supports, which remain 1.32, 1.33 and 1.34. +The floor belongs to the bundled Envoy Gateway, not to $[prodname] itself. -The bundled Envoy Gateway moves to v1.9.1, which raises its own minimum Kubernetes version to 1.33. +The bundled Envoy Gateway moves to v1.9.1, which raises its own minimum Kubernetes version to 1.33, and moves the bundled Gateway API CRDs from v1.5.1 to v1.6.1. +Gateway API v1.6 removes `sessionPersistence.idleTimeout` from `HTTPRoute`, and Envoy Gateway v1.9 rejects an empty `clientIPDetection` in `ClientTrafficPolicy`. -1. **Before you upgrade**, if you use Ingress Gateway on Kubernetes 1.32, upgrade the cluster to 1.33 or later. +1. **Before you upgrade**, if your cluster is below Kubernetes 1.33, upgrade it first. +2. Remove `sessionPersistence.idleTimeout` from any `HTTPRoute`, and any empty `clientIPDetection` from a `ClientTrafficPolicy`. ### eBPF data plane requires kernel 5.10 or later This affects you if you run the eBPF data plane on nodes with a kernel earlier than 5.10, or a kernel built without BTF and CO-RE support. +Red Hat 8.4 with kernel 4.18.0-305 or above is supported, because Red Hat backported the required features to that build. The runtime fallback paths for older kernels are gone. Instead of degrading, $[prodname] now reports a clear health message and does not program the data plane on an unsupported node. -1. **Before you upgrade**, check the kernel version and BTF support on every node running the eBPF data plane. +1. **Before you upgrade**, check every node running the eBPF data plane with `uname -r`, and confirm BTF support with `ls /sys/kernel/btf/vmlinux`. 2. Upgrade nodes that are too old, or move them to the standard data plane. 3. Upgrade $[prodname]. -Check the [release notes](../../release-notes/index.mdx) for known issues affecting specific kernel versions before you plan the upgrade. +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. + +### eBPF programs attach through netkit by default + +This affects you if you run the eBPF data plane and may need to roll back to 3.32 or earlier. + +`BPFAttachType` gains a `Netkit` value, which is now the default. +Felix attaches BPF programs through the netkit API on workload netkit devices, and through TCX elsewhere. +A release before 3.33 does not understand netkit devices, so rolling back without preparing first leaves those devices unmanaged. + +1. Upgrade $[prodname]. +2. **Before rolling back** to a release without netkit support, set `BPFAttachType` to `TCX` or `TC` in your `FelixConfiguration`, so Felix drives the existing netkit devices with that mechanism instead. + +### eBPF overlay traffic now uses the node's main IP + +This affects you if you run the eBPF data plane with VXLAN or IPIP, and have policy or firewall rules that match the tunnel device address. + +VXLAN and IPIP devices no longer carry their own IP. +When a node talks to a pod over the overlay it now uses the host's main device address, the one Kubernetes reports as the node's internal IP. +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`. + +### Default CNI configuration requires a newer container runtime + +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. +Older runtimes do not understand that version, so CNI ADD fails and pods cannot start on those nodes. + +1. **Before you upgrade**, check the container runtime version on every node. +2. Upgrade any node below containerd v1.6 or CRI-O v1.24. + +### Overlapping IP pools are rejected + +This affects you if any two of your IP pools have overlapping CIDRs. + +Creating or updating an IP pool is now rejected when its CIDR overlaps an existing pool. +Pools already stored keep working, but you cannot edit one that overlaps another until the overlap is resolved. + +1. **Before you upgrade**, check your pools for overlapping CIDRs if you expect to edit them afterwards. ### Felix metrics endpoint no longer requires client certificates by default @@ -101,13 +147,13 @@ The endpoint simply stops requiring a client certificate, so a protection you ha ### FIPS mode is removed -This affects you if you run the `-fips` image variants. +This affects you if your `Installation` sets `fipsMode: Enabled`, which is how an operator-managed cluster runs the `-fips` images. -$[prodname] no longer publishes `-fips` tagged images or boringcrypto binaries. -FIPS mode was deprecated in 3.30. -The `fipsMode` field remains on the operator Installation API for now, because that field belongs to the operator and is removed separately. +$[prodname] no longer publishes `-fips` tagged images or boringcrypto binaries, and FIPS mode was deprecated in 3.30. +The `fipsMode` field still exists on the Installation API, but it is deprecated, and leaving it set to `Enabled` marks the installation degraded after the upgrade. -1. **Before you upgrade**, move off the `-fips` images. +1. **Before you upgrade**, remove `fipsMode` from your `Installation`, or set it to `Disabled`. +2. If you pin image tags anywhere, move off the `-fips` variants. ### New installs default to native v3 CRDs @@ -115,10 +161,11 @@ No action is required. This note is here because the default changed, not becaus An upgrade never switches an existing cluster between the aggregation API server and native v3 CRDs. 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, and which requires Kubernetes 1.32 or later. +What changed is the default for a brand new install, which is now v3 CRD mode. +That mode needs Kubernetes 1.34 or later, and on 1.34 and 1.35 it also needs the `MutatingAdmissionPolicy` feature gate enabled on the API server, because it is not on by default there. 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). The datastore is briefly locked during the migration. +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. ### OpenStack no longer resyncs on a timer @@ -131,3 +178,18 @@ The driver resyncs once when the Neutron server starts, and on demand after that 1. Upgrade $[prodname]. 2. Remove `resync_interval_secs` and `resync_max_interval_secs` from `neutron.conf` at your convenience. 3. Run `calico-resync` when you need an immediate reconciliation. To drive reconciliation entirely by hand, set `startup_resync = never`. See [Resync between Neutron and etcd](../../networking/openstack/resync.mdx). + +## Upgrading to 3.32 + +These apply when you upgrade from 3.31, and not when you upgrade from 3.32. + +### OpenStack policy names change in the etcd datastore + +This affects you if you run $[prodname] for OpenStack on the etcd datastore. + +In 3.32 the naming convention for stored policies changed: policies in the default tier are stored under their plain name, where 3.29.4 through 3.31.x stored them under a tier-prefixed name. +Kubernetes clusters migrate this automatically through kube-controllers. +OpenStack clusters do not run kube-controllers, so the migration has to be run once, by hand. + +1. Upgrade $[prodname]. +2. Run the one-time migration described in [Migrating policy data](openstack-upgrade.mdx#migrating-policy-data-when-upgrading-from-earlier-than-v332). From 681e1aa7c2d679f852a3812437beccf2eeb47780 Mon Sep 17 00:00:00 2001 From: Chris Tauchen Date: Tue, 29 Sep 2026 20:24:53 +0100 Subject: [PATCH 5/8] DOCS-3001: Act on the Copilot review - 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. --- .../operations/upgrading/openstack-upgrade.mdx | 8 ++++---- .../operations/upgrading/upgrade-notes.mdx | 14 +++++++++++++- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx index 484a2d039f..98b299a75d 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx @@ -38,8 +38,8 @@ This may result in unexpected behavior and data. sudo sed -i 's/calico-X.X/calico-Y.Y/g' /etc/yum.repos.d/calico.repo ``` - Replace `X.X` in the above command with the version you're upgrading from, and `Y.Y` with $[version], - in both cases written as the major and minor version only. + Replace `X.X` with the version you're upgrading from and `Y.Y` with the version you're upgrading to, + each written as major and minor numbers only, with no leading `v`. 1. On all compute nodes, update packages: @@ -124,8 +124,8 @@ This may result in unexpected behavior and data. EOF ``` - Replace `X_X` and `X.X` with the version you're upgrading to, written with an underscore and a dot - respectively. Also replace `trusty` with the code name of your Ubuntu version. + Replace `X_X` and `X.X` with the version you're upgrading to, with no leading `v`, written with an + underscore and a dot respectively. Also replace `trusty` with the code name of your Ubuntu version. 1. On all compute nodes, update packages: diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx index fd342ac623..72d9230aff 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx @@ -77,6 +77,8 @@ The floor belongs to the bundled Envoy Gateway, not to $[prodname] itself. The bundled Envoy Gateway moves to v1.9.1, which raises its own minimum Kubernetes version to 1.33, and moves the bundled Gateway API CRDs from v1.5.1 to v1.6.1. Gateway API v1.6 removes `sessionPersistence.idleTimeout` from `HTTPRoute`, and Envoy Gateway v1.9 rejects an empty `clientIPDetection` in `ClientTrafficPolicy`. +If your cluster is below Kubernetes 1.33, Ingress Gateway does not run after the upgrade. + 1. **Before you upgrade**, if your cluster is below Kubernetes 1.33, upgrade it first. 2. Remove `sessionPersistence.idleTimeout` from any `HTTPRoute`, and any empty `clientIPDetection` from a `ClientTrafficPolicy`. @@ -177,12 +179,22 @@ The driver resyncs once when the Neutron server starts, and on demand after that 1. Upgrade $[prodname]. 2. Remove `resync_interval_secs` and `resync_max_interval_secs` from `neutron.conf` at your convenience. -3. Run `calico-resync` when you need an immediate reconciliation. To drive reconciliation entirely by hand, set `startup_resync = never`. See [Resync between Neutron and etcd](../../networking/openstack/resync.mdx). +3. If you install from packages, install the `calico-resync` package on each control node. The command ships separately from `calico-control`. +4. Run `calico-resync` when you need an immediate reconciliation. To drive reconciliation entirely by hand, set `startup_resync = never`. See [Resync between Neutron and etcd](../../networking/openstack/resync.mdx). ## Upgrading to 3.32 These apply when you upgrade from 3.31, and not when you upgrade from 3.32. +### AdminNetworkPolicy and BaselineAdminNetworkPolicy are no longer enforced + +This affects you if you have `AdminNetworkPolicy` or `BaselineAdminNetworkPolicy` resources. + +3.32 removed support for both in favor of `ClusterNetworkPolicy`. +$[prodname] does not enforce them from 3.32 onward, so they stop taking effect silently: the resources remain in the cluster and nothing reports an error. + +1. **Before you upgrade**, replace each `AdminNetworkPolicy` and `BaselineAdminNetworkPolicy` with an equivalent `ClusterNetworkPolicy`, or remove it. + ### OpenStack policy names change in the etcd datastore This affects you if you run $[prodname] for OpenStack on the etcd datastore. From b6f180e6cd99c18e528507ae975793033dbf6e3c Mon Sep 17 00:00:00 2001 From: Chris Tauchen Date: Tue, 29 Sep 2026 20:39:44 +0100 Subject: [PATCH 6/8] DOCS-3001: Drop version floors that sit below the supported range 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. --- .../operations/upgrading/upgrade-notes.mdx | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx index 72d9230aff..2ee788923c 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx @@ -69,18 +69,15 @@ Merged gateways (`mergeGateways: true`) are no longer supported, so each gateway 2. Upgrade $[prodname]. 3. Re-point monitoring and external DNS from `tigera-gateway` to each Gateway's namespace. If you used merged gateways, plan for one load balancer, DNS record, and certificate per gateway. -### Calico Ingress Gateway requires Kubernetes 1.33 +### Calico Ingress Gateway moves to Gateway API v1.6 This affects you if you use $[prodname] Ingress Gateway. -The floor belongs to the bundled Envoy Gateway, not to $[prodname] itself. -The bundled Envoy Gateway moves to v1.9.1, which raises its own minimum Kubernetes version to 1.33, and moves the bundled Gateway API CRDs from v1.5.1 to v1.6.1. +The bundled Envoy Gateway moves to v1.9.1, which takes the bundled Gateway API CRDs from v1.5.1 to v1.6.1. Gateway API v1.6 removes `sessionPersistence.idleTimeout` from `HTTPRoute`, and Envoy Gateway v1.9 rejects an empty `clientIPDetection` in `ClientTrafficPolicy`. +A manifest using either is rejected once the CRDs are upgraded. -If your cluster is below Kubernetes 1.33, Ingress Gateway does not run after the upgrade. - -1. **Before you upgrade**, if your cluster is below Kubernetes 1.33, upgrade it first. -2. Remove `sessionPersistence.idleTimeout` from any `HTTPRoute`, and any empty `clientIPDetection` from a `ClientTrafficPolicy`. +1. **Before you upgrade**, remove `sessionPersistence.idleTimeout` from any `HTTPRoute`, and any empty `clientIPDetection` from a `ClientTrafficPolicy`. ### eBPF data plane requires kernel 5.10 or later @@ -164,7 +161,8 @@ No action is required. This note is here because the default changed, not becaus An upgrade never switches an existing cluster between the aggregation API server and native v3 CRDs. 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. -That mode needs Kubernetes 1.34 or later, and on 1.34 and 1.35 it also needs the `MutatingAdmissionPolicy` feature gate enabled on the API server, because it is not on by default there. +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. From a8154ec5aaa535dca89a9a75b12870d335a144ae Mon Sep 17 00:00:00 2001 From: Chris Tauchen Date: Tue, 29 Sep 2026 20:44:52 +0100 Subject: [PATCH 7/8] DOCS-3001: Group the notes by the release that introduced them 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. --- .../operations/upgrading/upgrade-notes.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx index 2ee788923c..22740ae1ce 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx @@ -7,14 +7,14 @@ title: Upgrade notes Review this page before you upgrade. It lists the changes in each release that alter behavior you may depend on, and says what to do about each one. -Notes are grouped by the release that introduced them, so if you are skipping releases, read every group between the version you are on and the version you are upgrading to. +Notes are grouped by the release that introduced them. Read every group newer than the version you are upgrading from. 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. -## Upgrading to 3.33 +## Changes introduced in 3.33 -These apply when you upgrade to 3.33 from an earlier release. +These apply to every upgrade to 3.33. ### Calico ships as a single image @@ -180,9 +180,9 @@ The driver resyncs once when the Neutron server starts, and on demand after that 3. If you install from packages, install the `calico-resync` package on each control node. The command ships separately from `calico-control`. 4. Run `calico-resync` when you need an immediate reconciliation. To drive reconciliation entirely by hand, set `startup_resync = never`. See [Resync between Neutron and etcd](../../networking/openstack/resync.mdx). -## Upgrading to 3.32 +## Changes introduced in 3.32 -These apply when you upgrade from 3.31, and not when you upgrade from 3.32. +These apply only if you are upgrading from 3.31, and so jumping over 3.32. If you are already on 3.32 you have them. ### AdminNetworkPolicy and BaselineAdminNetworkPolicy are no longer enforced From 5ac6e430c57750a06d795392d148239e64d2c0b0 Mon Sep 17 00:00:00 2001 From: Chris Tauchen Date: Tue, 29 Sep 2026 21:04:43 +0100 Subject: [PATCH 8/8] DOCS-3001: Drop the release groupings from the page 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. --- .../operations/upgrading/upgrade-notes.mdx | 70 ++++++++++++------- 1 file changed, 46 insertions(+), 24 deletions(-) diff --git a/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx b/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx index 22740ae1ce..897e72749e 100644 --- a/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx +++ b/calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx @@ -7,16 +7,14 @@ title: Upgrade notes Review this page before you upgrade. It lists the changes in each release that alter behavior you may depend on, and says what to do about each one. -Notes are grouped by the release that introduced them. Read every group newer than the version you are upgrading from. +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. -## Changes introduced in 3.33 +{/* 3.33 · calico#12225 */} -These apply to every upgrade to 3.33. - -### Calico ships as a single image +## Calico ships as a single image This affects you if you mirror $[prodname] images into a private registry, pin image names or digests, or scan specific images. @@ -29,7 +27,9 @@ Fourteen images are no longer published: `calico/typha`, `calico/cni`, `calico/c 2. Update any image pins, digests, or scanner configuration that name the replaced images. 3. Upgrade $[prodname]. -### Limits on policy rules and selectors +{/* 3.33 · calico#12250 */} + +## Limits on policy rules and selectors This affects you if you generate $[prodname] network policy programmatically, or have policies with very large rule lists, address lists, or selectors. @@ -51,7 +51,9 @@ These limits live in the CRDs, so they do not apply on the etcdv3 datastore. 2. Split any policy that exceeds a limit, or narrow the field that does. 3. Upgrade $[prodname]. -### Calico Ingress Gateway proxies move namespace +{/* 3.33 */} + +## Calico Ingress Gateway proxies move namespace :::warning[Breaking change] @@ -69,7 +71,9 @@ Merged gateways (`mergeGateways: true`) are no longer supported, so each gateway 2. Upgrade $[prodname]. 3. Re-point monitoring and external DNS from `tigera-gateway` to each Gateway's namespace. If you used merged gateways, plan for one load balancer, DNS record, and certificate per gateway. -### Calico Ingress Gateway moves to Gateway API v1.6 +{/* 3.33 · calico#14049 */} + +## Calico Ingress Gateway moves to Gateway API v1.6 This affects you if you use $[prodname] Ingress Gateway. @@ -79,7 +83,9 @@ A manifest using either is rejected once the CRDs are upgraded. 1. **Before you upgrade**, remove `sessionPersistence.idleTimeout` from any `HTTPRoute`, and any empty `clientIPDetection` from a `ClientTrafficPolicy`. -### eBPF data plane requires kernel 5.10 or later +{/* 3.33 · calico#12128 */} + +## eBPF data plane requires kernel 5.10 or later This affects you if you run the eBPF data plane on nodes with a kernel earlier than 5.10, or a kernel built without BTF and CO-RE support. Red Hat 8.4 with kernel 4.18.0-305 or above is supported, because Red Hat backported the required features to that build. @@ -93,7 +99,9 @@ Instead of degrading, $[prodname] now reports a clear health message and does no 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. -### eBPF programs attach through netkit by default +{/* 3.33 · calico#13576 */} + +## eBPF programs attach through netkit by default This affects you if you run the eBPF data plane and may need to roll back to 3.32 or earlier. @@ -104,7 +112,9 @@ A release before 3.33 does not understand netkit devices, so rolling back withou 1. Upgrade $[prodname]. 2. **Before rolling back** to a release without netkit support, set `BPFAttachType` to `TCX` or `TC` in your `FelixConfiguration`, so Felix drives the existing netkit devices with that mechanism instead. -### eBPF overlay traffic now uses the node's main IP +{/* 3.33 · calico#11919 */} + +## eBPF overlay traffic now uses the node's main IP This affects you if you run the eBPF data plane with VXLAN or IPIP, and have policy or firewall rules that match the tunnel device address. @@ -115,7 +125,9 @@ Any host endpoint policy, global network policy, or external firewall rule writt 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`. -### Default CNI configuration requires a newer container runtime +{/* 3.33 · calico#13352 */} + +## Default CNI configuration requires a newer container runtime This affects you if any node runs containerd earlier than v1.6, or CRI-O earlier than v1.24. @@ -125,7 +137,9 @@ Older runtimes do not understand that version, so CNI ADD fails and pods cannot 1. **Before you upgrade**, check the container runtime version on every node. 2. Upgrade any node below containerd v1.6 or CRI-O v1.24. -### Overlapping IP pools are rejected +{/* 3.33 · calico#13953 */} + +## Overlapping IP pools are rejected This affects you if any two of your IP pools have overlapping CIDRs. @@ -134,7 +148,9 @@ Pools already stored keep working, but you cannot edit one that overlaps another 1. **Before you upgrade**, check your pools for overlapping CIDRs if you expect to edit them afterwards. -### Felix metrics endpoint no longer requires client certificates by default +{/* 3.33 · calico#13072 */} + +## 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`. @@ -144,7 +160,9 @@ The endpoint simply stops requiring a client certificate, so a protection you ha 1. **Before you upgrade**, if you rely on that protection, set `prometheusMetricsClientAuth: RequireAndVerifyClientCert` explicitly in your `FelixConfiguration`. -### FIPS mode is removed +{/* 3.33 · calico#12883 */} + +## FIPS mode is removed This affects you if your `Installation` sets `fipsMode: Enabled`, which is how an operator-managed cluster runs the `-fips` images. @@ -154,7 +172,9 @@ The `fipsMode` field still exists on the Installation API, but it is deprecated, 1. **Before you upgrade**, remove `fipsMode` from your `Installation`, or set it to `Disabled`. 2. If you pin image tags anywhere, move off the `-fips` variants. -### New installs default to native v3 CRDs +{/* 3.33 */} + +## New installs default to native v3 CRDs No action is required. This note is here because the default changed, not because an upgrade changes your cluster. @@ -167,7 +187,9 @@ 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. -### OpenStack no longer resyncs on a timer +{/* 3.33 · calico#12658 */} + +## OpenStack no longer resyncs on a timer This affects you if you run $[prodname] for OpenStack and relied on the periodic resync to recover from drift. @@ -180,22 +202,22 @@ The driver resyncs once when the Neutron server starts, and on demand after that 3. If you install from packages, install the `calico-resync` package on each control node. The command ships separately from `calico-control`. 4. Run `calico-resync` when you need an immediate reconciliation. To drive reconciliation entirely by hand, set `startup_resync = never`. See [Resync between Neutron and etcd](../../networking/openstack/resync.mdx). -## Changes introduced in 3.32 - -These apply only if you are upgrading from 3.31, and so jumping over 3.32. If you are already on 3.32 you have them. +{/* 3.32 */} -### AdminNetworkPolicy and BaselineAdminNetworkPolicy are no longer enforced +## AdminNetworkPolicy and BaselineAdminNetworkPolicy are no longer enforced -This affects you if you have `AdminNetworkPolicy` or `BaselineAdminNetworkPolicy` resources. +This affects you if you are upgrading from 3.31 and have `AdminNetworkPolicy` or `BaselineAdminNetworkPolicy` resources. If you are already on 3.32 this has happened. 3.32 removed support for both in favor of `ClusterNetworkPolicy`. $[prodname] does not enforce them from 3.32 onward, so they stop taking effect silently: the resources remain in the cluster and nothing reports an error. 1. **Before you upgrade**, replace each `AdminNetworkPolicy` and `BaselineAdminNetworkPolicy` with an equivalent `ClusterNetworkPolicy`, or remove it. -### OpenStack policy names change in the etcd datastore +{/* 3.32 */} + +## OpenStack policy names change in the etcd datastore -This affects you if you run $[prodname] for OpenStack on the etcd datastore. +This affects you if you are upgrading from 3.31 and run $[prodname] for OpenStack on the etcd datastore. If you are already on 3.32 this has happened. In 3.32 the naming convention for stored policies changed: policies in the default tier are stored under their plain name, where 3.29.4 through 3.31.x stored them under a tier-prefixed name. Kubernetes clusters migrate this automatically through kube-controllers.