🚧

Orka Release Notes

Orka v3.0.3: New features | Removed and deprecated features | Improvements | Known issues

Released: November 7, 2023

Updated: March 22, 2024 (See update)

---

How to upgrade | Backward Compatibility | What Persists | After the Migration | CLI Mapping | API Mapping

Download CLI | Download Orka VM Tools

📘

IMPORTANT

Always ensure that your cluster, Orka tools and integrations, and Orka VM Tools run matching versions. For example, the respectively available 3.0.x versions.

Orka v3.0.3

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

Orka v3.0.2

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

Orka v3.0.1

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.

Orka v3.0.0

Orka 3.0.0 is a major Orka release that brings Single Sign-On and native Kubernetes capabilities to your Orka clusters. All Orka tools and services have been completely reworked to provide improved usability, native Kubernetes interaction, more scalability, and improved performance. To benefit from the latest Orka release, you must migrate to Orka 3.0.0. This is both an Orka and a virtualization and orchestration layer upgrade.

New features

Orka 3.0.0 now provides vanilla macOS 14 Sonoma images and ISOs

You can now deploy and work with Intel-based and Apple silicon-based VMs running on macOS 14 Sonoma. The latest vanilla Sonoma images and ISOs reside in the remote repository.

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

(Intel-only) If you experience degraded performance on Intel-based Sonoma VMs, you might want to disable all animations.

Orka 3.0.0 also provides an OCI-compatible Apple silicon-based macOS 14 Sonoma image in GitHub Packages. To deploy a VM with it, just run:

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

Orka 3.0.0 now provides truly native Kubernetes functionality

All Orka resources are rewritten to be Kubernetes native. This lets you use kubectl in addition to the Orka3 CLI and the new Orka3 API in Orka 3.0.0.

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

You can now deploy VMs that pull an image straight from an OCI-compatible registry (such as GitHub Packages).

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

Or you can push a VM's disk as an image to an OCI-compatible registry.

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

This feature is available only for Apple silicon-based VMs and images. Registry credentials are required to push an image. For more information, run orka3 regcred --help.

Check https://github.com/macstadium/orka-images for the latest OCI-compatible images offered by MacStadium.

Orka 3.0.0 now runs on Kubernetes 1.27

Orka's virtualization and orchestration layer now runs on Kubernetes 1.27. If you're working with the Kubernetes layer directly, review the deprecated and removed Kubernetes features and resolve any pending issues before requesting an upgrade of your environment.

To update your custom pods, review the official Kubernetes guides on how to upgrade between versions.

The new Orka 3.0.0 API is more straightforward and more powerful

Orka 3.0.0 now provides a more unrestrained and powerful API to manage your cluster. All endpoints are organized in a more streamlined method and follow enterprise industry standards.

In addition, Orka 3.0.0 now provides a Swagger UI, which lets you use the Orka3 API straight from your cluster. Navigate to http://<ORKA_API_URL>/api/v1/swagger, provide an authentication token, and start utilizing the new Orka3.0.0 API.

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

The new Orka 3.0.0 CLI took inspiration from kubectl and follows its well-known syntax. If you're familiar with kubectl, you will find the new and improved Orka3 CLI easier to use. If you're new to Kubernetes, the new Orka3 CLI will help you stride into the world of native Kubernetes understanding.

The Orka3 CLI was rewritten with automation in mind. You will find that it no longer provides interactive mode and relies on detailed command-line user input instead. All commands have been rewritten to become more intuitive for easy extensibility. Many arguments are now positional, so you don't have to write lengthy flags and flag arguments.

Autocompletion and many command aliases are now available to ensure that the Orka3 CLI is as easy to use as possible.

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

Starting with Orka 3.0, Orka relies on Single Sign-On (SSO), service accounts, and the Kubernetes concept of role-based access control (RBAC) for user management. Orka users log in to their clusters with their MacStadium Customer Portal credentials. All user management happens in the MacStadium Customer Portal, including assigning user roles. Based on the role bindings configured for the respective user in the cluster, they can access one or more namespaces. For improved security, user authentication tokens (generated during login) have a lifecycle of one hour.

Orka 3.0.0 introduces namespaces, native resource isolation, and dedication

Among the native Kubernetes capabilities of Orka 3.0.0 are namespaces. By default, all Orka users have access to the orka-default namespace. However, to apply resource dedication and isolation in your cluster, you can create more namespaces with the orka- prefix. Next, you need to move one or more nodes to the new namespace and configure the role binding for the namespace.

orka3 ns create orka-dedicated
orka3 node namespace <NODE> orka-dedicated
orka3 rb add-subject --namespace orka-dedicated --user [email protected],[email protected] --serviceaccount orka-default:sa-jenkins,orka-test:sa-githubactions

Nodes moved to a namespace become dedicated to this namespace, and only users and service accounts added to the respective role binding have access to this node and its computational resources. Formerly, you were able to create node dedication by creating user groups and applying the groups to the respective node.

Orka 3.0.0 handles sandboxing via namespaces

Orka 3.0 introduces a new way to handle sandboxing - with namespaces. First, you need to create a dedicated namespace with enabled custom pods. Next, you need to move one or more nodes to that namespace. You also need to provide access to the namespace to all users and service accounts that require access.

orka3 ns create orka-sandbox --enable-custom-pods
orka node <NODE> orka-sandbox
orka3 rb add-subject --namespace orka-dedicated --user [email protected],[email protected] --serviceaccount orka-default:sa-jenkins,orka-test:sa-githubactions

After that, you can deploy custom pods. For any custom pods you want to run, add the following toleration to the pod. Provide the name for the sandbox namespace under value.

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

Orka 3.0.0 no longer requires VM configurations

You can now deploy a VM without creating or specifying a VM configuration. Deploying a VM as now simple as running:

orka3 vm deploy --image <IMAGE_NAME>

You can specify an image stored locally in your cluster or the complete image path to an OCI-compatible registry.

Orka 3.0.0 lets you download ISOs on your local machine

You can now download any ISO stored in your cluster to your local machine for editing and testing.

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

Images and ISOs now have an extra field - description. You can use it to provide important details about the image, such as macOS version, origin (local, remote, copied or pulled), owner, or even specific OS settings. It's up to you. Use the orka3 image set-description or orka3 iso set-description command, or the POST /api/v1/namespaces/{namespace}/images/{image}/description or /api/v1/namespaces/{namespace}/isos/{iso}/description endpoints.

Removed and deprecated features

Orka 2.x API

Orka 2.x API and earlier versions are now deprecated, and backward compatibility will be removed in a future release. You must migrate your custom Orka functionality to use the new Orka3 API or the new Orka3 CLI instead. See 2.4.x to 3.0.0: API Mapping and 2.4.x to 3.0.0: CLI Mapping.

If you need help moving away from the Orka 2.x API, contact the support team through the MacStadium portal.

Orka 2.x CLI

Orka 2.x CLI and earlier versions are now deprecated, and backward compatibility will be removed in a future release. You must migrate your custom Orka functionality to use the new Orka3 API or the new Orka3 CLI instead. See 2.4.x to 3.0.0: API Mapping and 2.4.x to 3.0.0: CLI Mapping.

If you need help moving away from the Orka 2.x CLI, contact the support team through the MacStadium portal.

User logs

Logging 1.0 and Logging 2.0are now removed. The Orka team is gathering information about this feature and might consider implementing an updated version or an alternative solution.

Shared VM storage for Apple silicon-based Monterey VMs

Shared VM storage is now removed for Apple silicon-based VMs running macOS Monterey. Intel-based Monterey VMs are not affected.

To continue using shared VM storage, upgrade your Apple silicon-based Monterey VMs to macOS Ventura OR switch to Intel-based Monterey VMs.

Saved state

The following features are now removed:

• 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)

The following features are now removed:

• 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

The earlier implementation of node dedication is now removed. To configure user access to a particular node, use namespaces instead. For more information, see here.

Sandboxing

The earlier implementation of sandboxing is now removed. You need to use a namespace with enabled custom pods to run custom pods in your cluster. For more information, see here.

Yes/no argument values

Passing yes or no as arguments to boolean flags is now removed.

Use true or false instead.

Re-configuring I/O Boost

The following features are now removed:

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

I/O Boost is now always enabled. You will not be able to work with VMs running macOS versions earlier than Mojave 10.14.5.

Improvements

Orka 3.0.0. introduces the following 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: MacStadiun has published a new base Sonoma image with System Integrity Protection (SIP) disabled https://github.com/macstadium/orka-images/tree/main?tab=readme-ov-file#sip-disabled.
• 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: Choose 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 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

📘

Scheduled maintenance window required

Orka 3.0.0 is a virtualization and orchestration layer upgrade. For more information, see Orka Upgrades.

This release requires a maintenance window of up to 3 hours depending on the size of the cluster.

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.