Skip to content

DOCS-3001: Add an upgrade notes page for 3.33 #3044

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ctauchen merged 8 commits into from
Sep 29, 2026
Merged

DOCS-3001: Add an upgrade notes page for 3.33 #3044

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
f253198
DOCS-3001: Add an upgrade notes page
ctauchen Sep 29, 2026
02e53e1
DOCS-3001: Scope the upgrade guides to N-2
ctauchen Sep 29, 2026
3aeaa41
DOCS-3001: Say the supported upgrade range without naming releases
ctauchen Sep 29, 2026
a7d3c8e
DOCS-3001: Correct and extend the upgrade notes after review
ctauchen Sep 29, 2026
681e1aa
DOCS-3001: Act on the Copilot review
ctauchen Sep 29, 2026
b6f180e
DOCS-3001: Drop version floors that sit below the supported range
ctauchen Sep 29, 2026
a8154ec
DOCS-3001: Group the notes by the release that introduced them
ctauchen Sep 29, 2026
5ac6e43
DOCS-3001: Drop the release groupings from the page
ctauchen Sep 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions calico_versioned_docs/version-3.33/operations/upgrading/kubernetes-upgrade.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 2 additions & 0 deletions calico_versioned_docs/version-3.33/operations/upgrading/openshift-upgrade.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment thread
Copilot marked this conversation as resolved.
Outdated

## Upgrade OwnerReferences
Expand Down
2 changes: 2 additions & 0 deletions calico_versioned_docs/version-3.33/operations/upgrading/openstack-upgrade.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
133 changes: 133 additions & 0 deletions calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Comment thread
Copilot marked this conversation as resolved.
Outdated

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
Comment thread
Copilot marked this conversation as resolved.
Outdated

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.
Comment thread
Copilot marked this conversation as resolved.
Outdated

### 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.

Check failure on line 106 in calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'boringcrypto'?

Raw Output:
{"message":"[Vale.Spelling] Did you really mean 'boringcrypto'?","location":{"path":"calico_versioned_docs/version-3.33/operations/upgrading/upgrade-notes.mdx","range":{"start":{"line":106,"column":56},"end":{"line":106,"column":68}}},"severity":"ERROR","code":{"value":"Vale.Spelling"}}
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.
Comment thread
Copilot marked this conversation as resolved.
Outdated

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).
Comment thread
Copilot marked this conversation as resolved.
Outdated
44 changes: 3 additions & 41 deletions calico_versioned_docs/version-3.33/release-notes/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
1 change: 1 addition & 0 deletions calico_versioned_sidebars/version-3.33-sidebars.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
Loading