How to upgrade the Anka Build Cloud

Before you begin

We follow semantic versioning; minor and major version increases can have significant changes and should be carefully considered.
Before upgrading, check if your current version is noted in the Pre-Upgrade Considerations and adjust your upgrade plan accordingly.

The Controller and Anka Nodes communicate through an agent running separate from from the Anka Virtualization/CLI tool, but on the same machine. When you upgrade the Controller, the node agent notices that the agent and controller versions differ and will create a task for each Node. This task will trigger the agent to perform a self-update and restart. While most situations this is seamless, we recommend checking the agent version post-upgrade on each Node with ankacluster --version to ensure it was upgraded properly. Nodes must be joined to the controller to receive the task to upgrade.

If necessary, you can force the proper agent version task creation through the Controller API.. Alternatively you can also disjoin the Nodes first, do the upgrade of the Controller, and then manually execute curl -O http://**{controllerUrlHere}**/pkg/AnkaAgent.pkg && sudo installer -pkg AnkaAgent.pkg -tgt / (AnkaAgentArm.pkg if using Anka 3.0) on each node individually.

It is generally safe to upgrade the controller while VMs are running and nodes are joined. However, if you can, we do recommend temporarily pausing CI/CD jobs or assigning to agents and letting the currently running jobs drain before moving forward.
We recommend snapshotting your etcd database regularly, but especially before an upgrade.
If you are upgrading the host/node macOS version, please disjoin and join the node to the controller using the ankacluster command.

Pre-upgrade Considerations

Existing VersionTarget VersionRecommendation
< 1.21.0>= 1.21.0The docker package (.tar.gz) was redesigned and has lot of changes around the use of ENVs and method of binary execution. We recommend using the new https://docs.veertu.com/anka/anka-build-cloud/getting-started/setup-controller-and-registry/ guide, from scratch in your environment, if upgrading from a version prior to 1.21.0.
1.18.0> 1.18.0Please note that there is a temporary workaround required for a bug that started in versions after 1.18.0 of the Controller/Registry agent which runs on your nodes. All versions of the agent, when noticing that the version of itself does not match the version of the controller, will perform a self-upgrade and restart. The restart seems to be problematic on some setups and leaves a zombie anka_agent process and and Offline status in the controller UI. To work around the bug when upgrading your controller/registry, you’ll need to change the existing steps to include:
  • Disjoining all of the nodes first
  • Do the controller/registry upgrade
  • Run curl -O http://**{controllerUrlHere}**/pkg/AnkaAgent.pkg && sudo installer -pkg AnkaAgent.pkg -tgt / (AnkaAgentArm.pkg if using Anka 3.0) on each node to download the new version
  • And finally join each node back
We will be fixing the bug soon. Thanks for your understanding and we are sorry for the inconvenience this causes.
x.xx.x1.20.0Minimum Registry version required for Controller - 1.19.0
< certificates are no longer supported for TLS/HTTPS & Certificate Authentication.

Upgrade Procedure

The following steps also apply to downgrading, though, you need to forcefully downgrade the cluster agent on each of your nodes.


  1. Make a backup of your docker-compose.yml.
  2. Download and extract the latest package.
  3. Configure the values in the docker-compose.yml or copy your previous docker-compose.yml to the new directory and also any .env files you have under the various service directories.
  4. Run docker-compose build to prepare the new docker tag.
  5. Run docker-compose down to take down the older version.
  6. Run docker-compose up -d in the newer version directory.

Native macOS package

  1. Make a backup of your /usr/local/bin/anka-controllerd.
  2. Install the new .pkg (see the MacOS Guide).
  3. Run sudo anka-controller restart.