Skip to main content
Orka Anywhere is any Orka deployment you run and manage yourself, whether that’s AWS-hosted or fully on-premises, as opposed to a MacStadium-managed deployment. Upgrades are self-service: you run the same Ansible-based process you used to stand up your cluster, pointed at the Ansible image tagged for your target release. There are two parts to every upgrade:
  • Services upgrade: upgrades the Orka Kubernetes services.
  • Node tooling upgrade: updates the Virtual Kubelet and Orka Engine on your ARM Mac nodes in place, without replacing the node.
Review the release notes for your target version before upgrading.

​
AWS-hosted

Fully documented today. See Upgrading Orka on AWS for the full step-by-step, including node tag verification, SSH and SSM upgrade paths for ARM node tooling, and multi-region guidance.

​
On-premises

On-premises upgrades reuse the same ghcr.io/macstadium/orka-ansible-onprem container and the same cluster.yml, nodes.yml, and hosts files you used to install, from Orka On-Prem architecture and networking overview. The only thing that changes is the image tag. The playbooks are idempotent: re-running them brings your cluster to the version of the image you run.

​
Before you upgrade

  • Read the release notes for your target version, and check the versions to expect in Orka component versions by release. A release doesn’t always update every component, so some components can stay on an earlier patch version.
  • Remove any osx_node_orka_engine_version and osx_node_orka_vk_version lines from nodes.yml, unless MacStadium gave you a specific build to deploy. Each installer image already pins the node tooling that matches its release. A pin left over from an earlier upgrade overrides it, and pinning a version that doesn’t exist for that component fails the node upgrade with an HTTP 403 error.
  • Plan for the effect on running VMs. See Impact on running VMs.

​
Upgrade an on-premises cluster

The following example upgrades to <VERSION_TAG>, for example 3.6.4. Run both steps from the directory that holds your cluster.yml, nodes.yml, and hosts files.
1

Upgrade the Orka services

Start the new installer image with your kubeconfig and cluster.yml:
Inside the container, from the /ansible directory, run the services playbook:
2

Upgrade the node tooling

Start the same image with your node files and the SSH key for your Mac nodes:
Inside the container, from the /ansible directory, run the node playbook. Enter the password of the ansible_user from nodes.yml when prompted:
To upgrade some nodes first, add --limit with node addresses from your hosts file, then run it again for the rest:
3

Verify the upgrade

Check the cluster and node versions:
Compare the output with the versions listed for your target release in Orka component versions by release.
Node tooling (Virtual Kubelet and Orka Engine) is version-gated: the playbook compares the installed version with the target and only updates on a mismatch, so re-running it against nodes already on the target version changes nothing.

​
Impact on running VMs

The services upgrade (site.yml) updates the Orka services in Kubernetes and doesn’t change your Mac nodes. The node upgrade (configure-arm.yml) restarts the Virtual Kubelet and Orka Engine services on a node when their version changes. Running VMs keep running through that restart. The node upgrade also reboots the node, which stops every VM running on it, if any of the following happens on that node:
  • The playbook changes the node’s hostname, its sleep setting, or one of the macOS settings it manages, such as automatic updates. These normally change only on the first run, or if someone changed them on the node by hand.
  • The Orka Engine setup removes the default macOS Internet Sharing configuration.
  • The Virtual Kubelet’s packet filter (pf) rules change while VMs are running on the node.
  • The Virtual Kubelet or Orka Engine service fails to restart.
You can upgrade all nodes in one run. To limit the impact of an unexpected reboot, upgrade a few nodes first with --limit.

​
Roll back

If an upgrade fails partway, re-run both playbooks from the previous version’s image tag, with the same files.

​
Override installer settings

Your mounted files sit next to the installer’s own settings files, and Ansible reads the files in each folder in alphabetical order, so the last value read wins:
  • cluster.yml is mounted next to the installer’s group_vars/all/main.yml. Where both set the same variable, the installer’s main.yml wins. This applies to settings the installer pins, such as component version tags and vm_scheduler_name.
  • nodes.yml is mounted next to the installer’s group_vars/arm-nodes/main.yml. Here nodes.yml wins, which is why a version pin in nodes.yml takes effect.
  • A value passed on the command line with -e, for example ansible-playbook site.yml -e vm_scheduler_name=<SCHEDULER_NAME>, overrides both files.
Only override an installer setting if MacStadium has asked you to. Setting vm_scheduler_name to most-allocated-scheduler also needs a scheduler profile on your control plane. Without it, every VM that doesn’t name a scheduler stays Pending. See Set up the most-allocated scheduler on a self-managed control plane.
This page covers upgrading the Orka services and node tooling with Ansible. To install the Orka Upgrade Service on an Orka Anywhere cluster, or migrate it from v1 to v2, see Installing the Upgrade Service.

​
Hybrid deployments (EKS control plane + on-premises Mac nodes)

If your deployment combines an EKS control plane on AWS with Mac nodes on-premises, upgrade each part using the workflow for where it runs: the AWS guide above for the control plane and AWS-side services, and the on-premises path for your Mac nodes.

​
After the upgrade

Download and install the orka CLI version matching your upgraded cluster, if you haven’t already.