Upgrading Calico

Upgrade procedure

These documents detail the procedure for upgrading Calico in an OpenStack system. If a release does not upgrade a particular component, you should skip the steps for that component.

Important: You will be unable to issue API requests to your OpenStack system during the procedure. Please plan your upgrade window accordingly, and see the Service Impact section for more details.

Service impact

During the upgrade, all VMs will continue to function normally: there should be no impact on the data plane. However, control plane traffic may fail at different points throughout the upgrade.

Generally, users should be prevented from creating or updating virtual machines during this procedure, as these actions will fail. VM deletion may succeed, but will likely be delayed until the end of the upgrade.

For this reason, we highly recommend planning a maintenance window for the upgrade. During this window, you should disable all user API access to your OpenStack deployment.

Before you begin

  • You must first upgrade to Calico v2.6.x before you can upgrade to Calico v3.2.1.
  • If you have Calico data which was not generated from OpenStack networks/security groups (e.g. Host Endpoints, Host Protection policies, etc), you will need to have etcdctl installed.

Upgrade steps

  1. Set up an etcdv3 cluster, if you don’t already have etcdv3 capability, either by upgrading the etcd software of your existing etcdv2 cluster, or by installing an etcdv3 cluster on new servers.

    Tip: etcd v3.x still supports the etcdv2 API, as used by Calico v2.6.x. However, Calico v3.0.0+ does not support the etcdv2 API. The upgrade steps below move the data from the etcdv2 API to the etcdv3 API. This requires an etcd v3.x server.

  2. If you have added Calico objects in addition to those that are derived automatically (by our Neutron driver) from OpenStack networks/security groups (e.g. Host Endpoints, Host Protection policies, etc) you will need to follow these additional steps to migrate that data:

    1. Install and configure calico-upgrade

    2. Test the data migration and check for errors

    3. Migrate Calico data

  3. Upgrade Calico packages, first on each compute node, then on the controllers.

  4. Delete old data from etcd.

  5. Finally, if you have any calico resource manifests stored offline (e.g. files checked into code management systems), you should update them to the new API using the conversion tool: Convert any offline Calico data from V1 to V3