Calico Open Source 3.33 (latest) documentation

Upgrade Calico on Kubernetes

About upgrading Calico

Your CRD mode is preserved

Upgrading does not change your cluster's CRD mode. A cluster using the aggregation API server (v1 CRDs) stays on the aggregation API server; a cluster using native v3 CRDs stays on v3. The operator selects the mode from the CRDs present and never switches an existing cluster. To move from the aggregation API server to native v3 CRDs, see Migrate to native v3 CRDs.

Before you start, review the upgrade notes for changes in each release that need your attention.

This page covers upgrading to v3.33 from the two previous Calico releases.

The procedure varies by datastore type and install method.

If you are using Calico in etcd mode on a Kubernetes cluster, we recommend upgrading to the Kubernetes API datastore as discussed here.

If you have installed Calico using the calico.yaml manifest, we recommend upgrading to the Calico operator, as discussed here.

Upgrading an installation that was installed using Helm
Upgrading an installation that uses the operator
Upgrading an installation that uses manifests and the Kubernetes API datastore
Upgrading an installation that connects directly to an etcd datastore

note

Do not use older versions of calicoctl after the upgrade. This may result in unexpected behavior and data.

Upgrading an installation that was installed using Helm

The tigera-operator chart does not contain the Calico CRDs, since Helm does not upgrade CRDs on helm upgrade. There are two ways to get the v3.33 CRDs into your cluster:

Apply the CRDs yourself before running helm upgrade. This is the recommended option. The new CRDs are in place before the new operator starts, so you can configure any new fields ahead of the upgrade, and the CRDs are managed by whatever tooling you already use for the rest of your manifests.
Let the operator apply them. With manageCRDs: true in your values.yaml (the default), the operator applies the CRDs itself when the new pod starts. You do not need a separate step, but the new CRDs only exist once the new operator is running, so new configuration cannot be applied until after the upgrade.

To apply the CRDs yourself:

Apply the v3.33 CRDs:
```
kubectl apply --server-side --force-conflicts -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/v1_crd_projectcalico_org.yaml
```
Or, using the CRD chart:
```
helm template calico-crds projectcalico/crd.projectcalico.org.v1 --version v3.33.0 | kubectl apply --server-side --force-conflicts -f -
```
note
The commands above apply the v1 CRDs, which is correct for clusters using the aggregation API server (the common case). If your cluster uses native v3 CRDs, substitute v3_projectcalico_org.yaml for v1_crd_projectcalico_org.yaml, or the projectcalico/projectcalico.org.v3 chart for projectcalico/crd.projectcalico.org.v1.
When templating the v3 chart on Kubernetes 1.36 and later, also add --api-versions admissionregistration.k8s.io/v1/MutatingAdmissionPolicy; without it, Helm renders the MutatingAdmissionPolicy resources at v1beta1, which Kubernetes 1.36 does not serve.

Run the Helm upgrade:

helm upgrade calico projectcalico/tigera-operator

Upgrading an installation that uses the operator

Download the Tigera Operator manifest and custom resource definitions.

curl https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/v1_crd_projectcalico_org.yaml -O
curl https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/tigera-operator.yaml -O

Use the following command to initiate an upgrade.
```
kubectl apply --server-side --force-conflicts -f v1_crd_projectcalico_org.yaml
kubectl apply --server-side --force-conflicts -f tigera-operator.yaml
```
note
The command above applies the v1 CRDs, which is correct for clusters using the aggregation API server (the common case). If your cluster uses native v3 CRDs, substitute v3_projectcalico_org.yaml for v1_crd_projectcalico_org.yaml in the command above.
To enable the flow logs API and Calico Whisker (introduced in version 3.30), apply the Goldmane and Whisker custom resources.

tip
If you plan to use the observability tools in Calico Cloud Free Tier, you need to enable Goldmane to provide flow logs to the console.
```
kubectl apply -f - <<EOF
apiVersion: operator.tigera.io/v1
kind: Goldmane
metadata:
  name: default
---
apiVersion: operator.tigera.io/v1
kind: Whisker
metadata:
  name: default
EOF
```

Upgrading an installation that uses manifests and the Kubernetes API datastore

Download the v3.33 manifest that corresponds to your original installation method.

Calico for policy and networking

curl https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/calico.yaml -o upgrade.yaml

Calico for policy and flannel for networking

curl https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/canal.yaml -o upgrade.yaml

Calico for policy (advanced)

curl https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/calico-policy-only.yaml -o upgrade.yaml

note

If you manually modified the manifest, you must manually apply the same changes to the downloaded manifest.

Use the following command to initiate a rolling update.

kubectl apply --server-side --force-conflicts -f upgrade.yaml

Watch the status of the upgrade as follows.

watch kubectl get pods -n kube-system

Verify that the status of all Calico pods indicate Running.

calico-node-hvvg8     2/2   Running   0    3m
calico-node-vm8kh     2/2   Running   0    3m
calico-node-w92wk     2/2   Running   0    3m

Remove any existing calicoctl instances, install the new calicoctl and configure it to connect to your datastore.
Use the following command to check the Calico version number.
```
calicoctl version
```
It should return a Cluster Version of v3.33.x.
If you have enable application layer policy, follow the instructions below to complete your upgrade. Skip this if you are not using Istio with Calico.
Congratulations! You have upgraded to Calico v3.33.

Upgrading an installation that uses an etcd datastore

Download the v3.33 manifest that corresponds to your original installation method.

Calico for policy and networking
```
curl https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/calico-etcd.yaml -o upgrade.yaml
```
Calico for policy and flannel for networking
```
curl https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/canal-etcd.yaml -o upgrade.yaml
```
note
You must manually apply the changes you made to the manifest during installation to the downloaded v3.33 manifest. At a minimum, you must set the etcd_endpoints value.

Use the following command to initiate a rolling update.

kubectl apply --server-side --force-conflicts -f upgrade.yaml

Watch the status of the upgrade as follows.

watch kubectl get pods -n kube-system

Verify that the status of all Calico pods indicate Running.

calico-kube-controllers-6d4b9d6b5b-wlkfj   1/1       Running   0          3m
calico-node-hvvg8                          1/2       Running   0          3m
calico-node-vm8kh                          1/2       Running   0          3m
calico-node-w92wk                          1/2       Running   0          3m

tip

The calico-node pods will report 1/2 in the READY column, as shown.

Remove any existing calicoctl instances, install the new calicoctl and configure it to connect to your datastore.
Use the following command to check the Calico version number.
```
calicoctl version
```
It should return a Cluster Version of v3.33.
If you have enabled application layer policy, follow the instructions below to complete your upgrade. Skip this if you are not using Istio with Calico.
Congratulations! You have upgraded to Calico v3.33.

Upgrading if you have Application Layer Policy enabled

Dikastes is versioned the same as the rest of Calico, but an upgraded calico-node will still be able to work with a downlevel Dikastes so that you will not lose data plane connectivity during the upgrade. Once calico-node is upgraded, you can begin redeploying your service pods with the updated version of Dikastes.

If you have enabled application layer policy, take the following steps to upgrade the Dikastes sidecars running in your application pods. Skip these steps if you are not using Istio with Calico.

Update the Istio sidecar injector template to use the new version of Dikastes. Replace <your Istio version> below with the full version string of your Istio install, for example 1.4.2.
```
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/alp/istio-inject-configmap-<your Istio version>.yaml
```
Once the new template is in place, newly created pods use the upgraded version of Dikastes. Perform a rolling update of each of your service deployments to get them on the new version of Dikastes.

Migrating to auto host endpoints

caution

Auto host endpoints have an allow-all profile attached which allows all traffic in the absence of network policy. This may result in unexpected behavior and data.

In order to migrate existing all-interfaces host endpoints to Calico-managed auto host endpoints:

Add any labels on existing all-interfaces host endpoints to their corresponding Kubernetes nodes. Calico manages labels on automatic host endpoints by syncing labels from their nodes. Any labels on existing all-interfaces host endpoints should be added to their respective nodes. For example, if your existing all-interface host endpoint for node node1 has the label environment: dev, then you must add that same label to its node:
```
kubectl label node node1 environment=dev
```
Enable auto host endpoints by following the enable automatic host endpoints how-to guide. Note that automatic host endpoints are created with a profile attached that allows all traffic in the absence of network policy.
```
calicoctl patch kubecontrollersconfiguration default --patch ={"spec": {"controllers": {"node": {"hostEndpoint": {"autoCreate": "Enabled"}}}}}
```
Delete old all-interfaces host endpoints. You can distinguish host endpoints managed by Calico from others in several ways. First, automatic host endpoints have the label projectcalico.org/created-by: calico-kube-controllers. Secondly, automatic host endpoints' name have the suffix -auto-hep.
```
calicoctl delete hostendpoint <old_hostendpoint_name>
```

About upgrading Calico​

Upgrading an installation that was installed using Helm​

Upgrading an installation that uses the operator​

Upgrading an installation that uses manifests and the Kubernetes API datastore​

Upgrading an installation that uses an etcd datastore​

Upgrading if you have Application Layer Policy enabled​

Migrating to auto host endpoints​