Upgrade Guide

Kubernetes Cilium Upgrade

Cilium should be upgraded using Kubernetes rolling upgrade functionality in order to minimize network disruptions for running workloads.

The safest way to upgrade Cilium to version “v1.0” is by updating the RBAC rules and the DaemonSet file provided, which makes sure the ConfigMap, initially set up by cilium.yaml, already stored in the cluster will not be affected by the upgrade. Both files are dedicated to “v1.0” for each Kubernetes version.

$ kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/v1.0/examples/kubernetes/1.7/cilium-rbac.yaml
$ kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/v1.0/examples/kubernetes/1.7/cilium-ds.yaml
$ kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/v1.0/examples/kubernetes/1.8/cilium-rbac.yaml
$ kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/v1.0/examples/kubernetes/1.8/cilium-ds.yaml
$ kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/v1.0/examples/kubernetes/1.9/cilium-rbac.yaml
$ kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/v1.0/examples/kubernetes/1.9/cilium-ds.yaml
$ kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/v1.0/examples/kubernetes/1.10/cilium-rbac.yaml
$ kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/v1.0/examples/kubernetes/1.10/cilium-ds.yaml
$ kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/v1.0/examples/kubernetes/1.11/cilium-rbac.yaml
$ kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/v1.0/examples/kubernetes/1.11/cilium-ds.yaml

You can also substitute the desired Cilium version number for vX.Y.Z in the command below, but be aware that copy of the spec file stored in Kubernetes might run out-of-sync with the CLI flags, or options, specified by each Cilium version.

kubectl set image daemonset/cilium -n kube-system cilium-agent=cilium/cilium:vX.Y.Z

To monitor the rollout and confirm it is complete, run:

kubectl rollout status daemonset/cilium -n kube-system

To undo the rollout via rollback, run:

kubectl rollout undo daemonset/cilium -n kube-system

Cilium will continue to forward traffic at L3/L4 during the roll-out, and all endpoints and their configuration will be preserved across the upgrade rollout. However, because the L7 proxies implementing HTTP, gRPC, and Kafka-aware filtering currently reside in the same Pod as Cilium, they are removed and re-installed as part of the rollout. As a result, any proxied connections will be lost and clients must reconnect.


Occasionally, when encountering issues with a particular version of Cilium, it may be useful to alternatively downgrade an instance or deployment. The above instructions may be used, replacing the “v1.0” version with the desired version.

Particular versions of Cilium may introduce new features, however, so if Cilium is configured with the newer feature, and a downgrade is performed, then the downgrade may leave Cilium in a bad state. Below is a table of features which have been introduced in later versions of Cilium. If you are using a feature in the below table, then a downgrade cannot be safely implemented unless you also disable the usage of the feature.

Feature Minimum version Mitigation Feature Link
CIDR policies matching on IPv6 prefix ranges v1.0.2 Remove policies that contain IPv6 CIDR rules Github PR