Orka release notes

​

Release summary

​

New features

​

VM User Data

# From a script file (encoded automatically)
orka vm deploy --image my-golden-image --userdata ./bootstrap.sh

# From a base64 string
orka vm deploy --image my-golden-image --userdata "$(base64 -i bootstrap.sh)"

• The script runs as root, in the background, and never delays the VM becoming available. The VM is reachable while the script runs.
• It runs once per VM. Completion is recorded after the script finishes, whether it succeeded or failed, so a failed run does not retry on the next boot. A VM that reboots or stops mid-script has not completed, and re-runs the script on its next boot, so write scripts that are safe to re-run.
• A VM deployed from an image that was saved or pushed after its own User Data ran still runs its own script. The run-once record is tied to the deployment, not the image.
• There is no timeout by default. Set ORKA_USERDATA_TIMEOUT inside the image if you want one.
• Output is written to /var/log/orka/userdata.log inside the VM.
• The base64-encoded script can be up to 64 KiB. For anything larger, have a small User Data script download the real payload.

​

Android emulators are generally available

orka emulator deploy --vm my-macos-vm --platform android-36 --image-type google_apis

​

Android emulator gRPC endpoint

orka emulator deploy --vm my-macos-vm --platform android-36 --image-type google_apis --grpc

​

Android emulator configurations

# Create a configuration
orka emulator-config create android-36-google-apis --platform android-36 --image-type google_apis

# Deploy from it
orka emulator deploy --vm my-macos-vm --config android-36-google-apis

# Override one setting at deploy time
orka emulator deploy --vm my-macos-vm --config android-36-google-apis --device-profile pixel_tablet

• Configurations are created in the orka-default namespace and are available to every user and service account with access to it.
• Any of --platform, --image-type, and --device-profile override the configuration at deploy time. Pass an empty --device-profile "" to use the avdmanager default instead of the configuration’s profile.
• Settings are copied into the emulator when it’s deployed, so editing or deleting a configuration never affects emulators already running.
• Manage configurations with orka emulator-config create, list, and delete (alias orka emc), or the /api/v1/namespaces/{namespace}/emulatorconfigs/android API endpoints.

​

Manage role subjects with orka rbac

# Grant the admin role to a service account
orka rbac add-subject --role admin --serviceaccount orka-default:sa-jenkins

# Grant the dev role in one namespace to a user
orka rbac add-subject --role dev --namespace orka-test --user user@company.com

# See who has a role, and remove a subject
orka rbac list-subjects --role dev --namespace orka-test
orka rbac remove-subject --role dev --namespace orka-test --user user@company.com

​

Improvements

​

Control plane resilience

• PodDisruptionBudgets protect orka-webhooks and the HA control-plane components during node drains and maintenance. Orka creates the orka-webhooks budget on every cluster, so don’t add one of your own: two budgets selecting the same pods make Kubernetes refuse to evict them, and a node drain during a Kubernetes upgrade hangs. See Kubernetes upgrade guide.
• Kubelet resources are reserved on control-plane nodes.
• MacStadium-hosted clusters only: Orka components also run under dedicated PriorityClass tiers, with kube-vip set to system-node-critical, and get per-component resource requests and limits. On AWS and on-prem clusters, Orka creates no priority classes, because they are cluster-wide and could preempt your own workloads, and leaves resource requests and limits empty so you can size them for your environment.

​

Observability

• The operator reports a pending-VM queue-depth metric and adds a vm_namespace label to its metrics, giving you a leading indicator of VM deployment backlog before deploy times start to climb.
• The deploy-duration histograms now use exponential buckets, so observations land in finite buckets and percentiles are meaningful. Bucket series and VM lifetime metrics are now included in the Prometheus allowlist.
• orka-webhooks now exposes a metrics endpoint that Prometheus scrapes, and previously missing control-plane metrics have been added to the scrape allowlists.

​

Node scheduling

• Image-cache and push jobs have their own per-node budget, default 2, tunable with the osx_node_orka_quota_job Ansible variable. Jobs no longer compete with VMs or emulators for a slot.
• The node pod quota is raised to 110, the Kubernetes default. It no longer limits how many VMs, emulators, and jobs run together, since VMs and jobs each have their own limit.
• Emulators aren’t capped. They’re counted per node, so kubectl describe node shows how many are running.
• Emulators are placed by the Kubernetes scheduler on their paired VM’s node. If the scheduler can’t place one, for example because that node is cordoned, the emulator stays Pending with the scheduler’s reason in its error message. After 5 minutes it fails with EmulatorUnschedulable.

​

Deprecations

• CLI: orka image (list, copy, delete, set-description), orka remote-image (list, pull), orka vm save, and orka vm commit print a deprecation warning to stderr and are marked (Deprecated) in their help.
• API: the images and remoteimages routes and POST /vms/{vm}/save and /vms/{vm}/commit return a Deprecation: true header and a Warning header naming the OCI replacement, and are marked deprecated in the API reference.
• orka imagecache, the cache/images routes, and VM deploy aren’t affected, because they serve OCI images too.

​

Breaking changes

​

CLI renamed to orka

• Update every script, CI job, and integration that calls orka3 to call orka. Commands, flags, and output are otherwise unchanged, apart from the Intel removals listed below.
• Download the 4.0 CLI from Orka tools, CLI downloads, and CI/CD plugins. On macOS, installing the 4.0 package leaves the 3.x orka3 binary in place, so you can keep both installed.
• On macOS with Homebrew, install the 4.0 CLI with brew install --cask orka. The orka3 cask stays on 3.x, and brew upgrade doesn’t move you from orka3 to orka.
• The 3.x CLI stays orka3. If you manage clusters on both Orka 3.6 and 4.0, use orka3 for 3.6 clusters and orka for 4.0 clusters.
• orka and orka3 read the same config file and the same orka kubeconfig context. Switching between a 3.6 cluster and a 4.0 cluster still means running config set --api-url and logging in again, whichever CLI you run.

• macOS and Linux: sudo ln -sf "$(command -v orka)" /usr/local/bin/orka3
• Windows: copy orka.exe to orka3.exe in the same folder.

​

Intel removals

CLI

• Removed commands: orka3 vm start, vm stop, vm suspend, vm resume, vm revert, and orka3 image generate.
• Removed command groups: orka3 iso (list, copy, delete, set-description) and orka3 remote-iso (list, pull).
• Removed flags on vm deploy and vmc create: --iso, --gpu, --disable-net-boost, --legacy-io, and --system-serial.
• Removed flags on vm resize: --user and --password. Resize on Apple silicon works exactly as before.
• orka vm and orka image now reject unknown subcommands with a non-zero exit code. Previously, an unknown subcommand such as orka3 vm bogus printed help and exited 0. Without this change, a script still calling a removed command such as vm stop would have read it as success.

API

• POST /api/v1/namespaces/{namespace}/vms/{vm}/exec
• POST /api/v1/namespaces/{namespace}/images (image generate)
• POST /api/v1/namespaces/{namespace}/upload/image and GET/HEAD /api/v1/namespaces/{namespace}/images/{image}/download. Apple silicon images move through OCI push and pull.
• All /isos, /remoteisos, and POST /upload/iso routes

Kubernetes resources

Web UI

• The VM Start, Stop, Suspend, Resume, and Revert actions have been removed. To restart a stopped VM, redeploy it.
• The Generate Image action and the ISOs page have been removed.
• The GPU, net boost, and ISO fields and columns have been removed from VM and VM config views.
• The Enable VNC checkbox has been removed from the Deploy VM and Create VM Config dialogs. It only applied to Intel configs. VM configs created from the Web UI keep VNC enabled, and deploys use the VM config’s own VNC setting.

​

Bug fixes

• Fixed: After a node outage, the disk sweeper could delete the disk of a VM whose pod still claimed it. VM disks are now kept for as long as a pod references them.
• Fixed: Resizing a VM could hang for up to 5 minutes and fail with a bare DeadlineExceeded error, because the repartition request was sent before the guest tools were ready to receive it. Resize now waits for the guest tools and bounds each wait with a clear error.
• Fixed: A VM deployed moments after creating its VM config could be rejected with an admission error because the config wasn’t visible to the webhook yet.
• Fixed: orka imagecache remove --all and --tags returned 404 for nodes that didn’t have the image cached. These nodes are now skipped: the request returns 207 Multi-Status with a 202 for each node. A node you name with --nodes that doesn’t have the image cached still returns 404.
• Fixed: Orphaned Failed and RemoveFailed cache entries lingered in orka imagecache info output. They’re now cleaned up, and removing an image with no cache record reports that clearly.
• Fixed: When a pull or import was short on space, cache eviction freed the full required size rather than the shortfall, so it evicted several cached images instead of one. An operation the whole cache couldn’t make room for deleted every cached image and was rejected anyway. Eviction now frees only what’s needed and rejects up front when evicting can’t help.
• Fixed: orka imagecache remove could stay RemoveFailed on every retry when the tag had already been deleted by an earlier, timed-out call. It now reports not found and clears the record.
• Fixed: Deploying a VM to a node without enough disk space reported Unable to deploy the VM as the underlying VM process has crashed. The VM now fails with Not enough disk space on node <NODE> to deploy the VM, followed by the space the VM needs and the space available, and the pod records a FailedCreate event with the same error.
• Fixed: Concurrent VM deployments and image pulls on the same node each checked free space without counting what the others were still writing, so a node could run out of disk mid-pull. Each operation now reserves the space it still needs until it finishes.
• Fixed: Cache eviction could delete the image a VM was being created from, so the deployment failed with The file "disk.img" couldn't be opened. Eviction now skips images that an in-progress deployment is using.
• Fixed: If a node ran out of disk space while importing an image, for example during two imports at once, Orka could keep the incomplete image instead of failing the import, and never download it again. VMs deployed from it on that node failed with Unable to deploy the VM as the underlying VM process has crashed. Orka now fails the import, and re-imports a cached image that’s shorter than its full size.
• Fixed: After a node evicted cached images to make room, the evicted images could still show as Ready in orka imagecache output until the next cache change. The node’s image list now refreshes after every deployment and after failed cache adds and removes.
• Fixed: Eviction could empty the cache and still reject the operation, because macOS reports freed disk space a few seconds late. Orka now counts the space eviction reports as freed.
• Fixed: Removing a large cached image could fail with DeadlineExceeded even though the removal completed on the node. Image removals now wait for the node to finish.
• Fixed: Creating a service account token could return an unhelpful error instead of a timeout error when the token wasn’t ready in time.
• Fixed: Tagging, untagging, or changing the namespace of a node could fail with 409 Conflict if the operator updated the node at the same moment. These requests now retry against the latest node state.
• Fixed: With bridged networking, a newly deployed VM could report the previous VM’s IP address, leaving it intermittently unreachable over SSH at the IP Orka returned.
• Fixed: On macOS 26.6.2 hosts, if macOS restarted its window server, the node could lose its GUI session. Running VMs kept running, but no new VMs could start until someone logged in to the node manually. Orka now restores the session before starting a VM.
• Fixed: In 3.7.0-alpha, when an emulator’s pod was removed, Orka could recreate it before the old pod finished terminating. The emulator could then be recreated more than once, or the replacement could fail to start on a port the old emulator still held.
• Fixed: After you commit changes to an existing image under the same name and tag, orka imagecache add could report the image as already cached on nodes where it had been cached automatically by a VM deployment, and skip re-caching it. imagecache add now re-caches the updated image on those nodes.

​

Security

• Updated golang.org/x/net (CVE-2026-78669), the Web UI’s npm dependencies, and the TLS certificate service’s proxy-addr and axios dependencies to address HIGH and CRITICAL vulnerabilities.

​

Known issues

​

Release summary

​

New features

​

Android emulators (early access)

​

Improvements

​

Observability

• The operator now reports a pending-VM queue-depth metric (a gauge counting VMs in Pending or pre-Running states) and adds a vm_namespace label to its metrics. Together these give a leading indicator of VM deployment backlog before deployment durations start to climb. See Consuming metrics from Prometheus.

​

Node scheduling

• Each Apple silicon node advertises a pod quota to the Kubernetes scheduler: how many VM, emulator, and image-cache job pods it can run at once (default 4, tunable via the osx_node_orka_quota_pod Ansible variable). If you run Android emulators, plan for headroom, a node running two VMs and their two paired emulators is already at the default quota, leaving no room for an image-cache job until one finishes. Contact MacStadium support to have the quota raised for your cluster.

​

Host node upgrades

• Orka can now upgrade existing Apple silicon host nodes to macOS Tahoe (26). Earlier 3.7.0-alpha builds only recognized macOS Sequoia as an upgrade target.
• Multi-node host OS upgrades are also more reliable: concurrent upgrade steps are now throttled to avoid overloading the control plane during large-cluster upgrades, and transient node-tooling failures during an upgrade retry automatically instead of failing the whole run.

​

Support

​

Release summary

​

Bug fixes

• Fixed: Caching jobs that could not be scheduled, or that got stuck mid-import, did not fail and release their resources. If four or more caching jobs on the same node were stuck this way, no new VMs could be deployed on that node. Caching jobs now fail after a bounded deadline (3 hours by default, tunable via the cache_job_active_deadline_seconds Ansible variable).
• Fixed: Cached images could be evicted unexpectedly (a regression introduced in 3.6.3). Orka now retains cached images as expected.
• Fixed: Namespaces created with orka3 namespace create --enable-custom-pods did not grant the orka-dev role binding to users added to the namespace afterward, leaving them without dev-level access. Namespaces created on 3.6.4 or later are unaffected. If you have an existing custom-pods namespace created before upgrading, this does not resolve automatically; contact MacStadium support to have the missing role binding applied.

​

Known issues

​

Release summary

​

New features

​

Image cache removal is generally available

​

Improvements

• Images cached automatically during VM deployment on Apple silicon nodes are now tracked as cache entries, the same as images cached explicitly with orka3 imagecache add. They appear in orka3 imagecache info output and can be removed with orka3 imagecache remove, without re-downloading the image.
• Image cache names are normalized when caching, so the same image referenced in different formats no longer creates duplicate cache entries.
• The (Admin-only) label has been removed from the orka3 imagecache add help text. The command does not require administrator privileges.

• VM network isolation allow-list rules are now enforced with explicit precedence over block rules, rather than relying on chain ordering. No effect on existing allow-list configurations.

​

Bug fixes

• Fixed: imagecache add with a :latest tag created duplicate and stale ImageCache CRDs due to missing tag normalization.
• Fixed: The API did not accept single-encoded image names in the imagecache path.
• Fixed: VMs deployed to a Mac node with an IP address recently freed by another VM could experience hung NFS mounts, caused by stale firewall connection state left over from the previous VM. VM lifecycle operations now flush this state on deploy and delete.

​

Security

• Updated golang.org/x/crypto, golang.org/x/net, swift-nio, and other dependencies to address CVEs.

​

Release summary

​

New features

​

Image cache removal (early access)

• Supports --nodes, --tags, and --all for targeted or cluster-wide removal, consistent with imagecache add
• Removal is asynchronous; use orka3 imagecache info to check status

​

Improvements

• Network isolation policy Ansible variables are now available for on-prem deployments. The VM network isolation feature introduced in Orka 3.6.0 can now be configured via Ansible for on-prem clusters. Contact MacStadium support to configure network isolation policies for your cluster.

• VM port reservations now support an optional protocol suffix. Use <NODE_PORT>:<VM_PORT>/udp or <NODE_PORT>:<VM_PORT>/tcp when deploying a VM. The protocol is case-insensitive and defaults to TCP if omitted.
• The Virtual Kubelet and Upgrade Service agent darwin-arm64 binaries are now code-signed with a Developer ID certificate in CI.
• CLI help text image references have been updated.

• The integration now tracks in-flight VM deployments to prevent over-provisioning when multiple jobs start at the same time.
• On restart, the integration reconciles existing VMs rather than ignoring them. Running VMs are adopted and cleaned up when their jobs finish; failed or non-running VMs are cleaned up immediately, preventing orphaned VMs from consuming cluster resources. Controlled by the new ENABLE_RECONCILIATION environment variable (default: True).
• The integration now reuses an existing runner scale set on restart instead of creating a new one, allowing in-progress jobs to continue uninterrupted. Controlled by the new MANAGE_RUNNER_SCALE_SETS environment variable (default: True).
• Improved resilience for curl download errors during VM provisioning.

​

Bug fixes

• Fixed: VM deadlock on long-lived VMs.
• Fixed: Intel node disk performance regression.

​

Known issues

​

Upgrade notes

orka3 config set --api-url https://<YOUR_PUBLIC_URL>

​

Release summary

​

New features

​

Orka Upgrade Service

Upgrade Service version visibility

​

Kubernetes 1.35 support

• Running VMs are not affected. Mac nodes are not part of the Kubernetes upgrade and do not restart.
• The Virtual Kubelet does not need to be upgraded and is forward-compatible with new Kubernetes versions.
• The API Server, Operator, and Webhooks may have brief downtime during node cordon/drain. Most orka3 CLI commands continue working during this window; only login and vm push require the API server. If the Operator pod is evicted during an upgrade, leader election takes up to 15 seconds. During this window VM deployments may be slower, but will not error.

​

VM network isolation

​

Automated Orka VM Tools updates

​

Improvements

​

AWS and on-prem deployments

• Orka no longer installs its own cert-manager if one is already present in the cluster. You can skip the bundled installation and use your existing cert-manager instead, eliminating version and configuration conflicts.
• The permissions required for Orka to run have been scoped to least-privilege: separate, minimal credential sets are now defined for Orka configuration, the Virtual Kubelet, ECR access, and backup operations.
• Webhook footprint has been reduced: the Pod webhook, ISO and image webhooks, and rolebinding webhook have been removed from AWS and on-prem installations.

​

Integrations

• Jenkins OCI image support: The Orka Jenkins plugin now supports OCI images. Previously the plugin only allowed selecting images from NFS storage; you can now specify an OCI image directly.
• Packer plugin bridge networking: The Orka Packer plugin now supports bridge networking, which was introduced in Orka 3.5 but was not supported in the plugin until this release.
• GitHub Actions runner metrics: The Orka GitHub Actions integration now exposes an optional Prometheus metrics endpoint for runner scale set statistics. When enabled, the endpoint publishes labeled metrics per scale set with a configurable polling interval. The endpoint is opt-in and disabled by default.
• GitHub Actions integration reliability: The Orka GitHub Actions runner now includes improved VM cleanup logic, an orphaned VM watcher that automatically removes VMs with no active runner, and expanded logging for better job observability.

​

Platform

• ECDSA SSH key support: The Orka API now accepts ECDSA keys when uploading certificates. Previously only RSA keys were supported.
• Prometheus metrics on port 443 with TLS: The Orka Prometheus data collector is now exposed on port 443 with TLS, unblocking use in environments that require all monitoring traffic to run over a secure port.
• Object storage for cluster config backups: Orka cluster configuration backups are now stored via object storage instead of NFS, improving backup reliability and decoupling them from NFS availability.
• Improved VM start error diagnostics: VM start failures during concurrent operations that previously produced empty error messages now surface actionable diagnostic information, including VZErrorDomain errors and configuration issues.
• Public artifact distribution via CloudFront: Orka binaries and container images are now distributed publicly via CloudFront. AWS and on-prem deployments no longer require AWS credentials to pull Orka artifacts.
• orka3 version reports Upgrade Service versions: The CLI now includes Upgrade Service operator and agent versions in version output.
• Improved error message reporting from the Orka Engine for VM start failures.

​

Bug fixes

• Fixed: Operator fails to configure Intel VMs
• Fixed: Calico network plugin setup fails on Orka 3.5 clusters
• Fixed: VM image push retries fail intermittently
• Fixed: VK kubeconfig creation fails for on-prem deployments
• Fixed: orka3 vm save fails when the cluster uses OCI image storage
• Fixed: Updated the Kubernetes API TCP ingress route to use the built-in kubernetes service. If you manage your own Orka deployment and use public NAT IPs, apply the update by running:

ansible-playbook -i hosts kubernetes.yml -e "k8s_reverse_proxy_enable=true" --tags k8s-reverse-proxy

​

Release summary

​

New features

​

VM shared attached disk configuration

Key capabilities

• Flexible deployment control: Enable or disable shared disk usage globally using the vm_shared_disk_enabled: true variable
• Instance-level disk sizing: Specify shared disk size for each Mac instance via user data script (AWS) or via Ansible (on-prem)
• Consistent VM storage: When enabled, all VMs deployed from the instance will automatically use the shared attached disk, ensuring standardized storage configuration across your infrastructure. On Apple silicon nodes, only one VM may run per node at a time when this feature is enabled. See Critical limitation for Apple silicon below.

Getting started

First-time disk installation (per-host)

1. Inside the guest VM, identify the shared disk:

diskutil list internal physical

2. Format and mount the disk:

   diskutil eraseDisk -noEFI JHFS+ shared /dev/<disk-identifier>

1. Set up a CodeBuild project (if one is not already configured) and set: vm_shared_disk_enabled: true
2. Configure each EC2 Mac Instance. Set the VM_SHARED_DISK_SIZE environment variable to the desired size as part of the user data script during instance launch:

#!/bin/bash
export VM_SHARED_DISK_SIZE=500
/usr/local/bin/bootstrap-orka <eks-cluster-name> <aws-region> <orka-engine-license-key>

3. The bootstrap script will automatically configure the instance to use the VM shared disk feature, and applies to all VM deployments from the instance
4. All subsequent VM deployments from this instance will utilize the shared attached disk

Technical requirements

• Your cluster has been upgraded to Orka v3.5.2 (Note that clusters must be at least on Orka 3.4 / k8s v1.33 to be upgraded to 3.5.2)
• Global configuration: The vm_shared_disk_enabled: true variable must be set in Ansible (this is disabled by default)
• AWS only: The VM_SHARED_DISK_SIZE environment variable must be set in the user data script for each EC2 Mac instance to enable the feature
• For Apple silicon nodes: Shared attached disk support is disabled by default: vm_shared_disk_enabled: false.
• On-prem only: Optionally set osx_node_orka_vm_shared_disk_size to specify disk size. This variable does not apply to AWS deployments.

• Users running AWS: Note that the VM_SHARED_DISK_SIZE environment variable must be set in the user data script to enable the feature

​

Default namespace detection in Orka CLI

Key capabilities

• Automatic namespace detection: The Orka CLI now automatically derives the default namespace from your orka kubeconfig context, eliminating the need to repeatedly specify namespaces in commands
• You can manually set the ORKA_DEFAULT_NAMESPACE in order to override the kubeconfig-derived namespace for specific workflows or environments

Getting started

Set a custom default namespace

export ORKA_DEFAULT_NAMESPACE=my-team-namespace
orka3 vm list


kubectl config set-context orka --namespace=orka-default

Technical requirements

• Orka CLI version 3.5.2 or later
• Valid orka kubeconfig file with configured context
• Optional: Set the ORKA_DEFAULT_NAMESPACE environment variable if a custom namespace override is needed
• Existing namespace-specific flags (e.g., --namespace) will continue to work and take precedence over default namespace settings

​

Improvements

• Reliability improvements for OCI image operations
• VM troubleshooting and logging improvements
• Orka Engine VM start timeout is now configurable via Ansible
• Image push/pull streaming operations now fail with a timeout if the Orka Engine server is unavailable
• Cache cleanup has been serialized to avoid concurrent cleanup failures, ensuring cache lock file permissions remain consistent
• Reduced noise and fixed behavior in non-default namespaces
• Orka no longer tries to process unsupported ECR refresh jobs when new namespaces are created
• The image caching state is updated correctly when caching an already-cached image after a node moves to a different namespace

​

Bug fixes

• macOS Tahoe 26.0 compatibility fixes for image deletion, copying, and tagging
• Pulling public images from GitHub Container Registry succeeds even when registry credentials are configured (automatic retry without credentials)
• Orka VM tools v3.5.2 now applies the configured display resolution correctly for Sequoia guests with custom resolution settings
  • Note: You must update Orka VM tools on your existing images to receive this fix. New images created with Orka 3.5.2 will include the updated VM tools automatically.

​

Release summary

​

Fixed issues

​

NAT networking on M4 Pro

​

Node resource display in custom namespaces

​

Image caching in custom namespaces

​

Service account permissions loss

​

SSO login JWT decoding

​

Deployment

​

Support

​

Release summary

​

New features

​

Bridged networking support

Key capabilities

Getting started

​

macOS 26 Tahoe guest support

Key capabilities

Getting started

Technical requirements

• A Sequoia 15.5 host is required in order to run a macOS Tahoe 26 guest image
• Orka does not currently officially support running Tahoe on a host machine. We aim to officially support macOS 26 hosts in the upcoming Orka 3.6.0 release.

​

OCI storage

Key capabilities

• Secure, OCI-compliant image storage and management
• Role-based access control and user management
• Activity auditing and compliance tracking
• Push and pull images directly from the Orka CLI to your Harbor registry
• Prometheus support for Harbor

Technical requirements

​

Improvements

• VM shared storage is now disabled by default for new Orka deployments. If you are a new Orka customer and require shared storage for your VMs, please open a support ticket to opt-in and enable this feature in your cluster. Existing Orka deployments are not impacted by this change, and will retain the previous setting (enabled).
• Performance and stability improvements have been made to the Orka Nodes.
• New Packer template examples are now available, adding popular developer tools such as Homebrew, Cocoapods, Swift, xcodes, Git, and Fastlane on top of our latest existing macOS Tahoe and macOS Sequoia 15.5 base images.
• NFS connection is now self-healing
• VM deletion time has been improved
• Runtime reporting has been improved

​

Bug fixes

• Orphan VM logic has been updated to include removing stopped VMs automatically
• Public IP feature awareness has been added to the Orka API server
• VMs will no longer pull images if an image is already running

​

Known issues

• VM data loss during upgrade: Upgrading from Orka 3.4 to Orka 3.5 will result in VM loss. Ensure you save/backup all virtual machines before proceeding with the upgrade, then redeploy them afterward.

​

Hotfix: image caching issues with NFS

​

Who is affected

​

Impact

• Customers using NFS storage may unknowingly run VMs with outdated images
• No errors or alerts are generated in Orka, making the issue difficult to detect
• Hosts may eventually run out of disk space due to accumulation of old or orphaned images

​

Customer downtime

​

Next steps

​

Improvements and bug fixes

• Orka does not delete VMs in certain cases, leading to VMs running out of space
• This leaves impacted VMs in a stopped state
• VMs are then unreachable

​

Who is affected

​

Impact

• Nodes may run out of space
• VMs may not be assigned a valid MAC address and will be inaccessible

​

Customer downtime

​

Next steps

​

New features

​

Set display settings at VM deployment

​

Examples

​

Set display settings for VM configurations

• Supports a minimum width of 320 px.
• Supports a maximum width of 3840 px.
• Supports a minimum height of 480 px.
• Supports maximum height of 2160 px.
• Supports a minimum DPI of 60 px.
• Supports a maximum DPI of 240 px.
• Supports an optional maximum DPI of 320 px.

​

Set display settings via Orka API at VM deployment

​

Set display settings via Orka API at VM configuration

• Supports a minimum width of 320 px.
• Supports a maximum width of 3840 px.
• Supports a minimum height of 480 px.
• Supports maximum height of 2160 px.
• Supports a minimum DPI of 60 px.
• Supports a maximum DPI of 240 px.
• Supports an optional maximum DPI of 320 px.

​

Improvements to existing features

​

Bug fixes

​

Improvements and fixes

• Orka does not delete VMs in certain cases, leading to VMs running out of space
• This leaves impacted VMs in a stopped state
• VMs are then unreachable

​

Who is affected

​

Impact

• Nodes may run out of space
• VMs may not be assigned a valid MAC address and will be inaccessible

​

Customer downtime

​

Next steps

​

Improvements and fixes

• Consistent Hardware UUID generation is good for use cases that require the same Hardware UUID and serial number for each deployment. This is often the case for code signing or other workflows that expect a specific machine identifier.
• Dynamic Hardware UUID generation is good for use cases that require unique identifiers, such as VDI or remote desktop use cases where each desktop is assigned to an individual user. MDM integration may also depend on having unique Hardware UUIDs.

​

Improvements and fixes

​

New features

• Orka Burst is now available to customers, providing dedicated, on-demand access to elastic cluster capacity as needed. If you are interested in adding burst nodes to your account, please get in touch with MacStadium through your Account Portal.
• Component versions are now shown with the orka3 version and orka3 node list -o wide commands.
• Orka worker nodes are upgraded to macOS 15.5.

​

Fixes and improvements

• Orka has been updated from Kubernetes v1.30 to v1.33. Upgrade Information.
  • Internal upgrades to Kubernetes networking components for greater stability on the control plane.
• Orka now handles the permission alert for non-privileged applications in Sequoia 15.4.
  • Starting with macOS Sequoia, macOS triggers a graphical permissions alert whenever a non-privileged application attempts to communicate with anything on the local network (e.g., pulling an image from an OCI registry hosted on a separate machine on the local network). As a result of this change, the Orka Engine is now deployed as a LaunchDaemon.
• Custom certificates uploaded by clients will persist on API restart and upgrades.
• VMs now generate unique identifiers under Apple’s guidelines. More details on the impact of this change are in the Known Issues section.
• All fixes released in the Orka 3.2 series are included. 3.2.2 3.2.1

​

Improvements and fixes

​

Fix: incomplete VM deletion

​

Fix: custom users created during authentication

​

New feature: Apple ID authentication

​

Requirements and limitations

Supported configurations

• Host machine: macOS Sequoia on Apple silicon
• Guest OS (VM): macOS Sequoia updated via IPSW

Limitations

• The Host OS must be running macOS Sequoia or later
• The Guest OS (VM) must be created using a Sequoia IPSW. Apple ID login will not work with VMs that were upgraded from previous versions of macOS like Sonoma.

​

Setup instructions

1. Download Orka Desktop to begin the VM creation process. Make sure your Host OS is Sequoia or later.
2. Build a new guest image using a Sequoia IPSW file with the requirements specified above.
3. Test and use your new VM locally.
4. If you want to deploy the image to your Orka cluster, use Orka Desktop to push your image to an OCI repository, and then use the Orka CLI to deploy to your Orka cluster.

​

Improvements and fixes

​

Image caching deletion fix

​

Fix: issue where image import directory was removed by the cache clearing process

​

Orka node status logic update

​

Improved Orka node architecture detection

​

GitHub Actions plugin null VM name issue

​

Scheduled caching

​

Sequoia support

​

Kubernetes update

​

Upgrading

1. Submit a ticket through the MacStadium portal.
2. Schedule a time for the maintenance window that works using the link provided in the ticket.
   The suggested time must be Monday through Thursday, 6 am or 10 pm PST (9 am or 1 pm EST), depending on MacStadium Global Operations calendar availability.
3. Follow this migration guide to configure your cluster and tools after the migration. If you are upgraded from Orka 2.4.x, review the 2.4.x to 3.0.0: CLI Mapping and 2.4.x to 3.0.0: API Mapping to decide how to migrate it.

​

New features

​

Orka 3.1.0 now provides support for public IPs in the CLI and integrations

orka3 config set --api-url <API_PUBLIC_IP>

​

(Intel-only) Support for old OS versions

orka3 vm deploy -i mojave.img --legacy-io --disable-net-boost

​

Image size details

orka3 image list -o wide

NAME                    DESCRIPTION                         SIZE   STORAGE SIZE   TYPE    STATE   ERROR
sonoma-90gb-orka3-arm   sonoma-90gb-orka3-arm  							90G    16G            arm64   Ready

​

Removed and deprecated features

​

Orka 2.x API

​

Orka 2.x CLI

​

Improvements

• Performance improvements in clusters > 20 nodes. All Orka commands should run faster and should not degrade under heavier load.
• Improved image resize behavior. In previous versions, if there is not enough disk space on the host, the system would cancel the image resize operation. The system now cleans old images from the cache to free space for the resized VM.

​

Known issues

• Nested virtualization is not available on macOS 14 Sonoma VMs. This is a limitation of the Apple virtualization framework.
  Workaround: None.
• You might experience performance issues when running Xcode 15 on your Orka VMs.
  Workaround: Try updating your OS to macOS 14 Sonoma.
• You cannot disable System Integrity Protection on the base Sonoma image.
  Workaround: MacStadium has published a new base Sonoma image with System Integrity Protection (SIP) disabled: see SIP-disabled images in orka-images.
• You cannot enable Kernel extensions. This is an Apple limitation.
  Workaround: None.
• You might be unable to update existing Intel-based VMs to macOS Ventura or later. This limitation relates to the Orka image design and the Apple virtualization framework.
  Workaround: Re-create your VM from one of the MacStadium official images for the respective macOS version you are trying to upgrade. Next, apply any missing updates within this OS version.
• VM isolation between Intel and Apple-silicon based VMs doesn’t work.
  Workaround: None.
• You might experience degraded performance on Intel-based VMs running macOS 14 Sonoma.
  Workaround: Disable animations for the VM. For more information, see Reduce motion on Mac.
• You cannot purge VMs from the VMs tab in the Web UI. When you try to purge a VM, the Web UI shows the following error message: No VMs with that name exist in Orka.
  Workaround: Run Purge from the VM Configs tab.
• The Web UI lets you manage only resources in the orka-default namespace.
  Workaround: For other workspaces, use the Orka3 CLI or the Orka3 API instead.
• When downloading a large-size ISO or image from the Swagger UI, the UI might become unresponsive, and you might lose your operation’s progress.
  Workaround: Use curl instead and provide a path on the local file system with the -o <FILE_PATH> flag.
• When checking the status of a VM, Orka 3.0.0 will list it as running even when stopped or suspended.
  Workaround: None.
• After you resize an Apple silicon-based VM running macOS Ventura and attempt to upgrade to a newer macOS version, the upgrade might fail, or you might experience other issues with your VM. This is a limitation of the current resize design and the Apple virtualization framework.
  Workaround: If possible, upgrade the image before resizing.
• After you resize an Apple silicon-based VM running macOS Monterey and attempt to upgrade to a newer macOS version, the upgrade might fail, or you might experience other issues with your VM. This is a limitation of the current resize design and the Apple virtualization framework.
  Workaround: If possible, upgrade the image before resizing.
• After you resize an Apple silicon-based VM running macOS Ventura, you can no longer connect via VNC to the VM.
  Workaround: If possible, use SSH or Apple Screen Sharing.
• After you upgrade an existing Apple silicon-based VM to a non-latest macOS version (for example, 13.2.1 when 13.3 is the latest), the VM becomes unresponsive, and you can no longer use it. The Apple virtualization framework causes this issue. We have reported the issue to Apple.
  Workaround: Always upgrade to the latest macOS version.
• macOS Ventura VMs created from ISO return to the Recovery (ISO install) screen after restart if you don’t manually select to boot macOS from the boot menu.
  Workaround: Select the second option from the boot menu (macOS Installer during the final steps of the setup or Macintosh HD after you have completed the installation) after every restart. If you miss the boot menu and end up at the Recovery screen, restart the VM from the Apple menu in the top left corner.
  Once you’re done with your current OS configuration, commit the changes or save a new image from the VM. Use the image to create and deploy macOS Ventura VMs.
• Intel-based Ventura VMs created with the Orka Web UI might not work as expected. This occurs because the Net Boost option is disabled by default when creating new VM configs in the Web UI. However, Intel-based Ventura VMs require Net Boost to be enabled to work properly.
  Workaround: Select the Net Boost checkbox when creating Intel-based Ventura VMs.
• You cannot access your shared VM storage after you update your Orka VM Tools from 2.3.x or earlier to 2.4.0 or later on an existing Monterey VM. The storage will still be listed under /Volumes/orka but you will not be able to access any content on it.
  Workaround: Commit or save the base image with the updated Orka VM Tools and re-create your Monterey VMs. Alternatively, use the latest default .orkasi image to re-create your VMs.
• If you set the default output to JSON, you can no longer use the Orka CLI in interactive mode.
  Workaround: Use direct mode with the -y flag instead.
• You can simultaneously start multiple pull remote image or copy image operations in the Orka Web UI. This might cause Orka to become unresponsive until all operations are complete. You cannot use Orka with any Orka tools and integrations during that time.
  Workaround: Wait for all running operations to complete.
• Sometimes, Orka might become unresponsive during a pull remote image or copy image operation and might start returning authentication errors.
  Wait for the operation to complete.
• Apple silicon-based VMs are not able to run applications that require kernel extensions. We have filed the problem with Apple and are communicating with them through our contacts to solve it.
• Any VMs deployed on Apple silicon-based nodes before Orka 2.1.0 might not be functional after the upgrade to the latest Orka release.
  Workaround: Delete and redeploy the VMs.
• Users running older versions of Orka will start seeing Apple silicon images when running orka image list-remote. These images are not supported in older versions of Orka, and attempting to pull them will result in an error.
  Workaround: Ignore the images or upgrade to Orka 2.1.0+.
• There is a known issue with authentication to certain OCI registries, such as AWS ECR. This will be remedied in a coming version of Orka.
• If you deploy a VM on an Apple silicon-based node and try to log in to your iCloud account, you might receive an error ‘The action could not be completed’. This is a limitation of the Apple Virtualization Framework.
  Workaround: Download the needed software via a web browser and install it manually.

• If your git-related operations are hanging, and nothing happens on an Orka VM, your Xcode is probably stuck in the “Verifying Xcode dialog” state. To ensure this is the case, you can connect to your VM via VNC, start the Xcode application and check if you will get a small window saying “Verifying Xcode”.
  Workaround: VNC to the VM and wait for the verification process to complete or execute the following command from the Terminal to disable Xcode verification:

xattr -d com.apple.quarantine '/Applications/Xcode.app'

​

How to upgrade

1. Submit a ticket through the MacStadium portal.
2. Schedule a time for the maintenance window that works for you through the link provided in the ticket.
   The suggested time(s) must be Monday through Thursday, 6 am or 10 pm PST (9 am or 1 pm EST), depending on MacStadium Global Operations calendar availability.
3. Follow this migration guide to configure your cluster and tools after the migration. If you are upgraded from Orka 2.4.x, review the 2.4.x to 3.0.0: CLI Mapping and 2.4.x to 3.0.0: API Mapping to decide how to migrate it.

​

Improvements and fixes

• Deploying two or more Intel VMs from the same config or with no config at all on the same node resulted in incorrect networking rules. This could cause connections (SSH, VNC, etc…) to one of the VMs to be redirected to another VM on the same node

​

Improvements and fixes

• Allow creation of non-expiring ServiceAccount tokens
• Improve VM stability when deploying on Mac Studios
• Allow running VMs with 128GB memory on Mac Studios
• Fix pushing OCI images to some private registries
• Improve VM Metadata stability. In some cases VM Tools were not starting, causing metadata to not be available

​

Improvements and fixes

• Fixed a sporadic issue when saving an image
• Enhance cluster resource management when arm nodes encounter limitations that prevent the deployment of more than 2 VMs.

​

OCI images

• Image pull performance has improved and is faster now.
• Memory consumption during image pull operations is reduced for a smoother experience.
• Enhanced the efficiency of batched layers pull, optimizing the overall image handling process.
• Fixed an issue when bad credentials are provided when pulling an image.

​

CLI

• The CLI now ensures stable connectivity by addressing an issue where it sporadically connected to the IPv6 address of Cognito, leading to login failures.
• The image save command is fixed now to provide accurate error messages when using image names with uppercase letters. Previously, an incorrect error message was displayed in such scenarios.

​

New features

​

Orka 3.0.0 now provides vanilla macOS 14 Sonoma images and ISOs

orka3 remote-image list
orka3 remote-image pull <SONOMA_IMAGE_NAME>

orka3 vm deploy --image ghcr.io/macstadium/orka-images/sonoma:latest

​

Orka 3.0.0 now provides truly native Kubernetes functionality

​

Orka 3.0.0 lets you work with images from OCI-compatible registries

orka3 vm deploy -i ghcr.io/my-organization/orka-images/orka-arm:latest

orka3 vm push <VM_NAME> server.com/repository/image:tag

​

Orka 3.0.0 now runs on Kubernetes 1.27

​

The new Orka 3.0.0 API is more straightforward and capable

​

The new Orka 3.0.0 CLI is automation-friendly and kubectl-inspired

​

Orka 3.0.0 brings Single Sign-On, RBAC, and service accounts

​

Orka 3.0.0 introduces namespaces, native resource isolation, and dedication

orka3 ns create orka-dedicated
orka3 node namespace <NODE> orka-dedicated
orka3 rb add-subject --namespace orka-dedicated --user user@company.com,user2@company.com --serviceaccount orka-default:sa-jenkins,orka-test:sa-githubactions

​

Orka 3.0.0 handles sandboxing via namespaces

orka3 ns create orka-sandbox --enable-custom-pods
orka node <NODE> orka-sandbox
orka3 rb add-subject --namespace orka-dedicated --user user@company.com,user2@company.com --serviceaccount orka-default:sa-jenkins,orka-test:sa-githubactions

{"key": "orka.macstadium.com/namespace-reserved", "value": "orka-sandbox"}

​

Orka 3.0.0 no longer requires VM configurations

orka3 vm deploy --image <IMAGE_NAME>

​

Orka 3.0.0 lets you download ISOs on your local machine

curl -X 'GET' \
  'http://<ORKA_API_URL>/api/v1/namespaces/orka-default/isos/<ISO_NAME>/download' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -o '<FILE_PATH>'

​

Orka 3.0.0 lets you add comprehensive descriptions for images and ISOs

​

Removed and deprecated features

​

Orka 2.x API

​

Orka 2.x CLI

​

User logs

​

Shared VM storage for Apple silicon-based Monterey VMs

​

Saved state

• Saving the state of a running VM to the respective VM configuration
• Deploying a VM from a VM configuration with a saved state
• Deleting a saved state from a VM configuration

​

Attached storage (from Orka images)

• Creating VM configurations with an attached Orka image for additional storage
• Attaching an Orka image for additional storage during deployment
• Listing the currently attached disks

​

Node dedication

​

Sandboxing

​

Yes/no argument values

​

Re-configuring I/O Boost

• Configuring I/O Boost for VM configurations
• Overriding I/O Boost during deployment

​

Improvements

• The caching of Apple silicon-based images is now improved to reduce deployment and boot times.
• Apple silicon-based images now take up significantly less space (on average) on your cluster’s storage. Existing images in the local cluster storage are not automatically converted to the new format. You must save or commit your existing images from a newly deployed VM to take advantage of this benefit.
• When listing the deployed VMs, Orka 3.0.0 lists all VMs for all users in the respective namespace.
• When listing VM configurations, Orka 3.0.0 now lists all VM configurations for all users in the cluster.
• Pull, generate, and copy operations for images and ISOs are now async operations and no longer block the console. You can check the progress of the operation by running orka3 image list -o wide or orka3 iso list -o wide.
• VM commit and VM save are now async operations and no longer block the console. You can check the progress of the operation by running orka3 image list -o wide or orka3 iso list -o wide.

​

Known issues

• Nested virtualization is not available on macOS 14 Sonoma VMs. This is a limitation of the Apple virtualization framework.
  Workaround: None.
• Orka 3.0.0 and 3.0.1 CLI do not allow users with NAT’ed public IPs to authenticate with the new Portal-based format. This capability will be introduced soon.
  Workaround: Deploy the CLI within Orka’s network.
• You might experience performance issues when running Xcode 15 on your Orka VMs.
  Workaround: Try updating your OS to macOS 14 Sonoma.
• You cannot disable System Integrity Protection on the base Sonoma image.
  Workaround: MacStadium has published a new base Sonoma image with System Integrity Protection (SIP) disabled: see SIP-disabled images in orka-images.
• You cannot enable Kernel extensions. This is an Apple limitation.
  Workaround: None.
• You might be unable to update existing Intel-based VMs to macOS Ventura or later. This limitation relates to the Orka image design and the Apple virtualization framework.
  Workaround: Re-create your VM from one of the MacStadium official images for the respective macOS version you are trying to upgrade. Next, apply any missing updates within this OS version.
• VM isolation between Intel and Apple-silicon based VMs doesn’t work.
  Workaround: None.
• You might experience degraded performance on Intel-based VMs running macOS 14 Sonoma.
  Workaround: Disable animations for the VM. For more information, see Reduce motion on Mac.
• You cannot purge VMs from the VMs tab in the Web UI. When you try to purge a VM, the Web UI shows the following error message: No VMs with that name exist in Orka.
  Workaround: Run Purge from the VM Configs tab.
• The Web UI lets you manage only resources in the orka-default namespace.
  Workaround: For other workspaces, use the Orka3 CLI or the Orka3 API instead.
• When downloading a large-size ISO or image from the Swagger UI, the UI might become unresponsive, and you might lose your operation’s progress.
  Workaround: Use curl instead and provide a path on the local file system with the -o <FILE_PATH> flag.
• When checking the status of a VM, Orka 3.0.0 will list it as running even when stopped or suspended.
  Workaround: None.
• The Orka 2.x CLI doesn’t respect the tag required setting from the VM configuration and defaults its value to no.
  Workaround: If you want to deploy a VM with an enabled tag required, manually set it to yes in the interactive prompt or via the --tag-required yes flag in direct mode.
• After you resize an Apple silicon-based VM running macOS Ventura and attempt to upgrade to a newer macOS version, the upgrade might fail, or you might experience other issues with your VM. This is a limitation of the current resize design and the Apple virtualization framework.
  Workaround: If possible, upgrade the image before resizing.
• After you resize an Apple silicon-based VM running macOS Monterey and attempt to upgrade to a newer macOS version, the upgrade might fail, or you might experience other issues with your VM. This is a limitation of the current resize design and the Apple virtualization framework.
  Workaround: If possible, upgrade the image before resizing.
• After you resize an Apple silicon-based VM running macOS Ventura, you can no longer connect via VNC to the VM.
  Workaround: If possible, use SSH or Apple Screen Sharing.
• After you upgrade an existing Apple silicon-based VM to a non-latest macOS version (for example, 13.2.1 when 13.3 is the latest), the VM becomes unresponsive, and you can no longer use it. The Apple virtualization framework causes this issue. We have reported the issue to Apple.
  Workaround: Always upgrade to the latest macOS version.
• macOS Ventura VMs created from ISO return to the Recovery (ISO install) screen after restart if you don’t manually select to boot macOS from the boot menu.
  Workaround: Select the second option from the boot menu (macOS Installer during the final steps of the setup or Macintosh HD after you have completed the installation) after every restart. If you miss the boot menu and end up at the Recovery screen, restart the VM from the Apple menu in the top left corner.
  Once you’re done with your current OS configuration, commit the changes or save a new image from the VM. Use the image to create and deploy macOS Ventura VMs.
• Intel-based Ventura VMs created with the Orka Web UI might not work as expected. This occurs because the Net Boost option is disabled by default when creating new VM configs in the Web UI. However, Intel-based Ventura VMs require Net Boost to be enabled to work properly.
  Workaround: Select the Net Boost checkbox when creating Intel-based Ventura VMs.
• You cannot access your shared VM storage after you update your Orka VM Tools from 2.3.x or earlier to 2.4.0 or later on an existing Monterey VM. The storage will still be listed under /Volumes/orka but you will not be able to access any content on it.
  Workaround: Commit or save the base image with the updated Orka VM Tools and re-create your Monterey VMs. Alternatively, use the latest default .orkasi image to re-create your VMs.
• If you set the default output to JSON, you can no longer use the Orka CLI in interactive mode.
  Workaround: Use direct mode with the -y flag instead.
• You can simultaneously start multiple pull remote image or copy image operations in the Orka Web UI. This might cause Orka to become unresponsive until all operations are complete. You cannot use Orka with any Orka tools and integrations during that time.
  Workaround: Wait for all running operations to complete.
• Sometimes, Orka might become unresponsive during a pull remote image or copy image operation and might start returning authentication errors.
  Wait for the operation to complete.
• Apple silicon-based VMs are not able to run applications that require kernel extensions. We have filed the problem with Apple and are communicating with them through our contacts to solve it.
• Any VMs deployed on Apple silicon-based nodes before Orka 2.1.0 might not be functional after the upgrade to the latest Orka release.
  Workaround: Delete and redeploy the VMs.
• Users running older versions of Orka will start seeing Apple silicon images when running orka image list-remote. These images are not supported in older versions of Orka, and attempting to pull them will result in an error.
  Workaround: Ignore the images or upgrade to Orka 2.1.0+.
• There is a known issue with authentication to certain OCI registries, such as AWS ECR. This will be remedied in a coming version of Orka.
• If you deploy a VM on an Apple silicon-based node and try to log in to your iCloud account, you might receive an error ‘The action could not be completed’. This is a limitation of the Apple Virtualization Framework.
  Workaround: Download the needed software via a web browser and install it manually.

• If your git-related operations are hanging, and nothing happens on an Orka VM, your Xcode is probably stuck in the “Verifying Xcode dialog” state. To ensure this is the case, you can connect to your VM via VNC, start the Xcode application and check if you will get a small window saying “Verifying Xcode”.
  Workaround: VNC to the VM and wait for the verification process to complete or execute the following command from the Terminal to disable Xcode verification:

xattr -d com.apple.quarantine '/Applications/Xcode.app'

​

How to upgrade

1. Submit a ticket through the MacStadium portal.
2. Schedule a time for the maintenance window that works for you through the link provided in the ticket.
   The suggested time(s) must be Monday through Thursday, 6 am or 10 pm PST (9 am or 1 pm EST), depending on MacStadium Global Operations calendar availability.
3. Follow this migration guide to configure your cluster and tools after the migration. If you have any CLI-based or API-based custom automation, review the 2.4.x to 3.0.0: CLI Mapping and 2.4.x to 3.0.0: API Mapping to decide how to migrate it.