> ## Documentation Index > Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt > Use this file to discover all available pages before exploring further. # Orka 3.0 Release Notes > Orka 3.0 introduced SSO, native Kubernetes, OCI registry support, the new orka3 CLI, and macOS Sonoma images. Patch notes for v3.0.1-3.0.3 also included. ## 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 ``` (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 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](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:///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 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 ``` 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 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 ``` 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 is now as simple as running: ``` orka3 vm deploy --image ``` 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:///api/v1/namespaces/orka-default/isos//download' \ -H 'accept: application/json' \ -H 'Authorization: Bearer ' \ -o '' ``` ### 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](/orka/orka-cluster-migration-from-24-3x/24x-to-300-cli-mapping) and [2.4.x to 3.0.0: CLI Mapping](/orka/orka-cluster-migration-from-24-3x/24x-to-300-cli-mapping). If you need help moving away from the Orka 2.x API, contact the support team through the [MacStadium portal](https://portal.macstadium.com/). ### 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](/orka/orka-cluster-migration-from-24-3x/24x-to-300-cli-mapping) and [2.4.x to 3.0.0: CLI Mapping](/orka/orka-cluster-migration-from-24-3x/24x-to-300-cli-mapping). If you need help moving away from the Orka 2.x CLI, contact the support team through the [MacStadium portal](https://portal.macstadium.com/). ### User logs Logging 1.0 and Logging 2.0 are 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](/orka/orka-resources/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](/orka/orka-cluster-migration-from-24-3x/24x-to-300-after-the-migration). ### 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](/orka/orka-cluster-migration-from-24-3x/24x-to-300-after-the-migration). ### 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:** MacStadium has published a new base Sonoma image with System Integrity Protection (SIP) disabled [here](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](https://support.apple.com/en-gb/guide/mac-help/mchlc03f57a1/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 ` 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](/orka/orka3-cli-reference/image-management) 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/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. ![Xcode "Verifying Xcode" dialog causing git operations to hang on an Orka VM](https://files.readme.io/4534063-7a9f7a8-Screenshot_2022-02-07_at_16_12_18.png) * 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 Orka 3.0.0 is a virtualization and orchestration layer upgrade. For more information, see [Orka Upgrades](/orka/orka-upgrades-and-release-notes/orka-upgrades#virtualization-and-orchestration-layer-upgrades-kubernetes-docker-or-linux). 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](https://portal.macstadium.com/). 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](/orka/orka-cluster-migration-from-24-3x/24x-to-300-after-the-migration) 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](/orka/orka-cluster-migration-from-24-3x/24x-to-300-cli-mapping) and [2.4.x to 3.0.0: API Mapping](/orka/orka-cluster-migration-from-24-3x/24x-to-300-cli-mapping) to decide how to migrate it.