Upgrading
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 Version | Target Version | Recommendation |
---|---|---|
< 1.21.0 | >= 1.21.0 | The 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.0 | Please 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:
|
x.xx.x | 1.20.0 | Minimum Registry version required for Controller - 1.19.0 |
< 1.24.0 | 1.24.0 | SHA1 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.
Docker
- Make a backup of your
docker-compose.yml
. - Download and extract the latest package.
- Configure the values in the
docker-compose.yml
or copy your previousdocker-compose.yml
to the new directory and also any .env files you have under the various service directories. - Run
docker-compose build
in the new package directory to prepare the new docker tag. - Run
docker-compose down
in the previous package directory to take down the older version. - Run
docker-compose up -d
in the newer version directory to finally bring it up.
You can temporarily rundocker-compose up
which attached you immediately to the service logs so you can watch for errors. However, it will not stay running so once things are confirmed to be working, you’d need todocker-compose down
anddocker-compose up -d
before logging out of the server.
Post-upgrade of the controller you will need to wait for Anka Nodes to finish upgrading their agents. This can take a minute or two. Node statuses should say “Upgrading”. Please be patient for this process.
Native macOS package
- Make a backup of your
/usr/local/bin/anka-controllerd
. - Install the new .pkg (see the MacOS Guide).
- Run
sudo anka-controller restart
.