Orka Release Notes

​

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.

​

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 here.
• 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 here.
• 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 the /Volumes/orkabut you will not be able to access any content on it.<br/>**Workaround:**Commitorsavethe 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 here.
• 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 here.
• 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.