How to upgrade the Anka Virtualization package

Upgrade Procedure

  1. Download and install the latest version
Upgrading the Build Cloud too? Check out our upgrade procedure for the Anka Build Cloud Controller & Registry
We do not follow strict semantic versioning; minor and major version increases can have significant changes
Upgrading Anka Virtualization software while VMs are running is typically safe. Please see the Pre-upgrade Considerations below to be sure.
Upgrading the VM macOS version from within (using softwareupdate) typically works. However, starting in Monterey you will need to switch the hard_drive controller to ablk before attempting the upgrade: anka modify {TemplateName} set hard-drive --controller ablk

Pre-upgrade Considerations

Existing VersionTarget VersionRecommendation
1.4.32.x.xRequires upgrade of all existing VM templates with anka start --update and push to the registry
2.x2.1.2Only requires upgrade of existing Catalina VM templates with anka start --update and push to the registry
< 2.4>= 2.4Full feature support requires upgrading addons.
  • macOS 10.14.x does not contain the necessary Apple APIs for Nested Virtualization to work on 2.5.x of Anka. If you use Nested Virtualization, you will need to upgrade the host OS version before trying to install 2.5.x of Anka.
  • Avoid upgrading the anka package to 2.5.X on nodes with VMs running.
< 2.5.x2.5.xSuspended VMs < 2.5.x are not compatible with 2.5.x and will need to be force stopped (anka stop --force), started, and then re-suspended post-upgrade.

Upgrading VM Addons

If your existing version is noted in the Pre-Upgrade Considerations as requiring an addons upgrade, or, if you’re going between major/minor versions of Anka:

  1. Upgrade the guest addons inside existing VM templates with anka start -u
  2. Push the newly upgraded VM templates to registry with anka registry push {vmNameOrUUID} --tag <newTag>
We cannot guarantee that suspended VMs will start properly between major and minor versions of Anka, though, we do try and ensure the compatibility.