Upgrading (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/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.36.1 | >= 1.36.1 | MacOS TLS users must set ANKA_REGISTRY_LISTEN_ADDRESS to a proper IP:PORT , vs the default :PORT , otherwise 127.0.0.1 will be used. |
< 1.36.0 | >= 1.36.0 |
|
< 1.34.0 | 1.34.0 | The Controller will exclusively use the Root Token for communication and authentication with the Registry in 1.34.0. This means that both the Registry and Controller must have AUTH enabled as well as the same Root Token in their configs. Several ENVs like ANKA_API_KEY_ , ANKA_CLIENT_ , and ANKA_OIDC_ (registry only) are no longer available and necessary. They can be removed from your configuration, but be sure to mirror the AUTH configuration for Root Token and other ENVS from the Controller. |
< 1.32.0 | >= 1.33.0 | This release removed Implicit Flow OIDC support. Customers will need to review the new Code/Explicit Flow and its requirements. |
< 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 (see step 7).
If you are not using our ETCD container, be sure that you upgrade ETCD to the version we require (see release notes) before trying to update the Controller and Registry.
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. You will need to manually copy ENVs you’re using in.env
files of older versions into thedocker-compose.yml
underenvironment:
. - 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. - (downgrading only) Disjoin any nodes which are connected, then run the following on each Anka Node:
curl -O http://**{controllerUrlHere}**/pkg/AnkaAgent.pkg && sudo installer -pkg AnkaAgent.pkg -tgt /
(AnkaAgentArm.pkg
if using Anka 3/ARM)
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
and/usr/local/bin/anka-registryd
. - Install the new packages (see the MacOS Guide).
- Run
sudo anka-controller restart
andsudo anka-registry restart
.