Update license key docs to reflect self-service provisioning flow

orka/orka-engine/orka-engine-30.mdx

@@ -10,7 +10,7 @@
 
   * A host (or node) is a physical computer with a host macOS and an installation of Orka Engine.
   * An image is the bits on disk representing a VM that can be used for saving state and sharing.
   * MacStadium base VM Orka images are macOS OCI compliant VM images stored in our public GitHub registry [ghcr.io/macstadium/orka-images/](http://ghcr.io/macstadium/orka-images/) with user credentials user/pwd:
 
 
 
@@ -48,27 +48,21 @@
 
 ## Obtaining an Orka License Key
 
-Orka Engine requires a valid license key to operate. To request a license key:
+Your license key is included in your order confirmation from MacStadium. If you don't have it, log in to your customer portal at [macstadium.users.licensespring.com](https://macstadium.users.licensespring.com) or contact [support@macstadium.com](mailto:support@macstadium.com).
 
-1. Contact your MacStadium account representative
+Activate your license:
 
-2. Provide your organization name, deployment details, and use case
-
-3. Your account representative will submit your information to our licensing team for provisioning
-
-4. Receive license key via email (Est. 24 hour turnaround time)
-
-5. Activate: `orka-engine license set --key YOUR_KEY`
+`orka-engine license set --key YOUR_KEY`
 
 You can also download Orka Engine directly at: [https://distribution.macstadium.com/orka-engine/official/3.6.0/orka-engine.pkg](https://distribution.macstadium.com/orka-engine/official/3.6.0/orka-engine.pkg)
 
 ## Installation
 
-To install Orka Engine on an Apple silicon ARM (M1-M3) computer running macOS 13 (Ventura) and above, it is necessary to acquire and run the installer package.
+To install Orka Engine on an Apple silicon host (M1 or later) running macOS 13 (Ventura) and above, it is necessary to acquire and run the installer package.
 
 The Orka Engine installer is self-guided and takes less than a minute to install successfully. Simply double click or right click open the **orka-engine.pkg** file from the source download directory and follow the prompts.
 
 ![macOS installer window for orka-engine showing the Introduction step](/images/attachments/39594591423515.png)
 
 ![Orka Engine app icon showing an orca whale with a terminal prompt symbol](/images/attachments/39594527742107.png)
 
@@ -83,7 +77,7 @@
   * Save that VM as an image using `orka-engine vm save`
   * Listing images available on disk with `orka-engine image list`
   * Stop a VM with **ctrl-c** in terminal window bound to running VM or by closing the Dock item
   * Run a base template VM image hosted from MacStadium using `orka-engine vm run`
     * `orka-engine vm run latest-sonoma --image ghcr.io/macstadium/orka-images/sonoma:latest`
   * Pulling remote images locally using `orka-engine image pull`
   * Starting a VM in the stopped state with `orka-engine vm start`
@@ -95,7 +89,7 @@
 
 After Orka Engine is installed, open a terminal window. The command `orka-engine` is installed at `/usr/local/bin/orka-engine` \- this should be in the $PATH for most users by default.
 
 ## Using orka-engine --help
 
 The `orka-engine --help` command lists the three subcommands, `vm`to manage VMs, `image` to manage images, and `host` to see information about the host.
 
@@ -113,7 +107,7 @@
 ```
 orka-engine vm run latest-ipsw --ipsw latest --disk-size 90
 ```
 `orka-engine vm run` is a blocking function. Open another terminal window to interface with orka-engine for other functions while the VM is running. Stop a VM with **ctrl-c** or via the UI window **Menu - > Quit**.
 
 ## Common Options when Running a VM
 
@@ -160,7 +154,7 @@
 
 Orka engine can list the name and resource consumption of VMs that are currently running or stopped on a local host.
 
 ![Terminal output of orka-engine vm list showing a VM named latest-ipsw with 2 CPUs, 4096M memory, in running state](/images/attachments/39594527745947.png)
 
 ## Saving a VM as an Image
 
@@ -168,7 +162,7 @@
 
 For example,`orka-engine vm save latest-ipsw sonoma146-vanilla` saves the VM called `latest-ipsw` as an image with the name **sonoma146-vanilla**
 
 ![Terminal confirmation: The image 'sonoma146-vanilla' for VM 'latest-ipsw' has been successfully saved](/images/attachments/39594591426971.png)
 
 ## Listing Images Available on Disk
 
@@ -178,9 +172,9 @@
 
 Stop a headless VM or VM with a display console enter **ctrl-c**(from the terminal window VM was started with) or if deployed with a display console, by choosing the apple icon in the VM and selecting Shut Down… .
 
 ## Running a VM Based on a MacStadium Hosted Image
 
 MacStadium hosts a number of Sequoia, Sonoma, and Ventura images on [GitHub - macstadium/orka-images: Public images for Apple silicon-based Orka virtual machines](https://github.com/macstadium/orka-images/) In `orka-engine vm ,` specify an `--image` option to be the URL of an image coming from an OCI registry, 
 
 ```bash
 orka-engine vm run sonoma-latest --image ghcr.io/macstadium/orka-images/sonoma:latest
@@ -197,7 +191,7 @@
 
 
 
 ## Reviewing Current List of VMs (in VMs orka-engine)
 
 It is now possible to start a second terminal and run `orka-engine vm list`, and the following output appears, (which indicates that the previously running `latest-ipsw` VM has been stopped), and the recent `sonoma-latest` is now running. 
 
@@ -231,7 +225,7 @@
 
 ## Pulling Remote Images Locally
 
 In previous examples, `orka-engine vm run` was used to both _pull_ (or download) a remote image to the local device and to _run_ the vm. There are cases where users may just want to download an image, and `orka-engine image pull` supports this. 
 
 `orka-engine image pull ghcr.io/macstadium/orka-images/ventura:no-sip`
 
@@ -241,9 +235,9 @@
 
 ## Pushing local Images to Registry
 
 If the previously run sonoma-latest image has been modified and saved with the necessary CI tools, then it can image can be shared with team members by storing it on the team OCI repo and naming it **sequoiaCI** ; on the repo, use the `orka-engine image push` command. 
 
 The default local Orka Engine VM image files system path is `/Users/<host_username>/.local/share/orka/data/` where the host_username is **admin** in this example and the container registry is [ghcr.io](http://ghcr.io/) and the repo credentials are username=**dev1** and password=**repo**. 
 
 `orka-engine image push --username dev1 --password repo /Users/admin/.local/share/orka/data/sonoma-latest ghcr.io/images/sequoiaCI:latest `
 

orka/orka-on-aws-and-on-prem/orka-on-aws-getting-started.mdx

@@ -13,7 +13,7 @@
 The diagram below illustrates the architecture of an Orka Cluster on AWS, detailing how it integrates with Amazon EC2 Mac instances, Amazon EKS (Elastic Kubernetes Service), and Amazon ECR (Elastic Container Registry) within a customer’s AWS account.
 
 ![Orka Cluster on AWS architecture diagram showing EC2 Mac, EKS, and ECR integration](/images/attachments/44003706780059.png)
 The EC2 Mac hosts are set up with Orka AMIs, which provide a stable runtime for virtual machines. Each VM is deployed on the host using an OCI image, which can be fetched from Amazon ECR or an external OCI Registry. The use of OCI images enables rapid deployment (within a few minutes) of different macOS versions, pre-configured with various tools and optionally with SIP (System Integrity Protection) disabled. This addresses challenges that typically exist on Mac EC2 without Orka VMs. An EKS cluster will integrate with CI tools, CLI, or API, and orchestrate workloads, including spin-up and tear-down of VMs, and scheduled caching of images as needed.
 
 Key elements in the architecture include:
 
@@ -32,15 +32,15 @@
   * Storage
     * We recommend using ECR or alternative OCI repositories for image storage.
   * Mac EC2
     * We will provide an AMI based on an official AWS macOS base image that includes our tooling (Virtual Kubelet, Orka Engine) and a bootstrap script that accepts the EKS parameters to connect as an Orka worker node.
     * We have a new AMI available that supports the external NVMe disk available with M4 instances. Per the [official Amazon docs](https://aws.amazon.com/ec2/instance-types/mac/): "Amazon EC2 M4 Mac instances come with a new 2TB instance store volume per EC2 Mac Dedicated Host, providing low latency storage for improved caching and build/test performance."
 
 The new AMI is compatible with Orka 3.5 and later, and all EC2 Apple silicon Mac instance types (M1, M2, M4).
 
 By default:
 
 - The NVMe disk is used for Orka storage of VM and image data on M4 instances only
 - Autologin is enabled for the `ec2-user`, and is required when running a Sequoia guest OS or newer
 
 <Note>
   The `ENABLE_NVME_DISK` and `ENABLE_AUTOLOGIN` variables are **not** required. These are set to `true` by default, and either variable may be disabled if needed:
@@ -53,7 +53,7 @@
 /usr/local/bin/bootstrap-orka <eks-cluster-name> <vpc-region> <orka-license-key>
 ```
   * Networking
     * Apple silicon nodes don’t have a direct tie-in to the traditional k8s networking stack. With Orka, we provide a private network, expose certain ports, and require NATing for access. We do provide modes for network isolation and internet isolation. We provide documentation below for how to expose Orka services outside of the cluster. As of Orka 3.5.0, we also support [bridge networking mode](/orka/orka-on-aws-and-on-prem/using-bridge-networking-with-orka-350), enabling the ability to get an IP on a subnet in your VPC.
   * User Management and Authorization
     * Users need to register at portal.macstadium.com, as all user management is handled through the portal service. Customers can also use their own OIDC identity provider. See [OIDC Provider Setup](#oidc-provider-setup) below.
   * Logging, Monitoring, and Alerting
@@ -73,7 +73,7 @@
     * Orka Operator: TCP 8080 (metrics), TCP 8081 (health check), TCP 443 (webhook), Linux worker nodes should be accessible from within the cluster on any port. Does not require Internet access.
     * Orka OIDC Provider: TCP 443. Requires connectivity to the authentication provider.
   * EC2 Mac Nodes
     * Virtual Kubelet / Orka Engine AMI: Ingress ports can be internal to the cluster network. The customer should allow ingress to all ports within the network. The following ports should be open to all networks that need access to the VMs: TCP 5900-6200 (Screenshare), TCP 5999-6299 (VNC), and TCP 8822-9122 (SSH). In general, we recommend allowing outbound requests uniformly for forward compatibility.
 
 > **NOTE**: SSH/Screen Share/VNC ports are globally tracked and allocated. The ranges given above are applicable to each Apple silicon node.
 
@@ -81,10 +81,10 @@
 ## Install Overview
 
   1. **Talk to your MacStadium Account Team about your Orka on AWS install.**
      1. Provide MacStadium with your AWS account ID and region to be used. This is needed so that the Orka AMI can be shared with your account.
   2. Follow the installation steps below for the EKS Cluster and the CodeBuild role.
      1. **Take note of the EKS Node IAM role and the CodeBuild role ARN, and share the 2 ARNs with your MacStadium Account Team**
   3. MacStadium provides customers with an OIDC Client ID to use during CodeBuild execution and with AMI details so they can install Orka software onto EC2 Mac.
   4. Follow the steps below to update your build spec with the OIDC Client ID, set up IAM roles so that CodeBuild can manage the EKS cluster, and execute CodeBuild to install Orka Services into the EKS cluster.
   5. Follow the steps below to set up the OIDC Provider
   6. Follow the steps below to expose the Orka API service via Load Balancer
@@ -99,28 +99,28 @@
      2. To set up the cluster, follow the AWS guidelines for [EKS Auto Mode](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-automode.html) or the [EKS QuickStart](https://docs.aws.amazon.com/eks/latest/userguide/quickstart.html).
   2. **Recommendations** :
      1. Select the same region for the cluster as the one used for deploying the EC2 Mac nodes to avoid costly cross-region traffic.
      2. Deploy the cluster in private subnets only, as none of the Orka services need to be accessed from the Internet directly.
      3. Deploy at least two Linux worker nodes for resiliency and high availability.
   3. **Note down the ARN of the**[**EKS Node IAM role**](https://docs.aws.amazon.com/eks/latest/userguide/create-node-role.html)**.** MacStadium needs this ARN to configure EKS cluster admin access for the node.
   4. **Optional:**
      1. Set Cluster endpoint access to “Private” to restrict access to your cluster API from the Internet.
         1. This setting depends on your access needs. All Orka clients (CLI, integrations, etc.) must have connectivity to the cluster.
      2. Use EKS API for Cluster authentication mode.
         1. This is the [newest authentication mode for EKS](https://aws.amazon.com/blogs/containers/a-deep-dive-into-simplified-amazon-eks-access-management-controls/), replacing the old aws-auth config map.
   5. Orka Cluster installs itself into EKS using Ansible scripts.
      1. **MacStadium support will provide an OIDC Client ID**
      2. Additional considerations
         1. The Ansible runner must have connectivity to the cluster API.
         2. The Ansible runner must have Cluster Admin privileges to set up the cluster.
         3. MacStadium recommends using CodeBuild to run Ansible and configure the EKS cluster. CodeBuild provides direct visibility to the cluster, alleviating networking concerns.
 
 
 
 ### Setup a CodeBuild project to run Orka Installation into the EKS Cluster
 
 MacStadium recommends using CodeBuild to run Ansible and configure the EKS cluster. CodeBuild provides direct visibility to the cluster, alleviating networking concerns. To set up a CodeBuild project as an Ansible runner:
 
   1. **Allow AWS to create the CodeBuild role for you. Note down the name and ARN of the role — you will need to share the ARN with MacStadium and modify the role later.**
   2. Select the following options:
      1. Project type - Default project
      2. Source - no source
@@ -131,10 +131,10 @@
         4. Environment type - Linux Container
         5. Image registry - Other registry
            1. Under External registry URL, enter `ghcr.io/macstadium/orka-ansible-aws:<version_tag>` where `<version_tag>` is the Orka version.
   3. (Optional) Set VPC, Subnets and security group to be used by CodeBuild. This is only needed if the EKS access is set to private. To do that:
      1. Click Additional Configuration
      2. Select the VPC where your cluster is deployed
      3. Select the subnets which EKS uses
      4. Select a security group that has access to the EKS API
   5. In the BuildSpec, add the following commands:
 
@@ -145,8 +145,8 @@
 Where:
 `{cluster_name}` - the name of your EKS cluster
 `{region}` - the region where the cluster is deployed
 `{k8s_api_address}` - the K8s API address of your cluster
 `{kube_oidc_client_id}` - the OIDC client ID provided by MacStadium
 
   6. Save the configuration.
   7. Next, Configure CodeBuild to manage the EKS cluster:
@@ -174,14 +174,14 @@
 
 To use the Orka API/CLI, you need to set up the OIDC provider.
 
 The issuer URL and client ID will be provided by MacStadium.
 
 To set up the provider:
 
   * Go to the Cluster Access tab.
   * Click `Associate Identity Provider`.
   * Add the `Issuer URL` provided by MacStadium.
   * Add the `Client ID` provided by MacStadium.
   * Add `cognito:groups` for the `Groups claim`.
   * Add `oidc:` for the `Groups prefix`.
 
@@ -195,7 +195,7 @@
 
 ### Cluster Admin Access
 
 By default, Orka's validator webhooks restrict certain operations (including deleting another user's VM) to cluster admins only. On AWS and on-prem deployments, cluster admin status must be explicitly configured. This differs from MacStadium-hosted clusters, where kubeadm automatically establishes the `kubeadm:cluster-admins` group.
 
 The default admin group for AWS and on-prem is `orka:cluster-admins`. To use a different group, set the `cluster_admin_group` Ansible variable before running the installation playbook.
 
@@ -235,7 +235,7 @@
 
 ## Provisioning Steps
 
   1. We will provide an AMI based on an official AWS macOS base image that includes our tooling (Virtual Kubelet, Orka Engine)
   2. The AMI will additionally include a bootstrap script that should be run via user data. See the section below for more detailed information
   3. The IAM role must be linked to an instance profile and attached to the instance
   4. The security group allowing access to the EKS control plane must be attached to the instance
@@ -247,25 +247,21 @@
 
 ## Obtaining an Orka License Key
 
-Orka Engine requires a valid license key to operate. To request a license key:
+Your license key is included in your order confirmation from MacStadium. If you don't have it, log in to your customer portal at [macstadium.users.licensespring.com](https://macstadium.users.licensespring.com) or contact [support@macstadium.com](mailto:support@macstadium.com).
 
-1. Contact your MacStadium account representative
+Activate your license:
 
-2. Provide your organization name, deployment details, and use case
-
-3. Your account representative will submit your information to our licensing team for provisioning
-
-4. Receive license key via email (Est. 24 hour turnaround time)
-
-5. Activate: `orka-engine license set --key YOUR_KEY`
+```
+orka-engine license set --key YOUR_KEY
+```
 
 You can also download Orka Engine directly from MacStadium. Contact your account representative for the current installer link.
 
 ### Bootstrap Script
 
 The AMI includes a bootstrap script that can be run via [user data](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html) and accepts the following parameters to connect as an Orka worker node:
 
   * EKS cluster name, EKS cluster VPC region, Orka License Key (provided by MacStadium)
   * The customer should pass the following as user data when launching an instance:
 
 
@@ -292,7 +288,7 @@
 
 IAM-based or certificate-based kubeconfig authentication is not sufficient for `vm push` on its own. An `Unauthorized` error from `vm push` in this context indicates a missing Orka API token, not an ECR authentication issue.
 
 You can get credentials for use with a private ECR registry with the aws CLI as follows:
 
 
 ```
@@ -340,13 +336,13 @@
 
 
 
 ## Mac Node Deprovisioning Steps
 
 To deprovision a Mac Node you need to:
 
   1. Delete the Mac instance
   2. (Optional) Release the Mac dedicated host if you no longer need it
   3. Delete the Kubernetes node by running `kubectl delete node <node_name>` where `<node_name>` is the name of the node you want to deprovision
 
 
 
@@ -354,7 +350,7 @@
 
 ### OpenTelemetry Standards
 
 Logging and monitoring conform to OpenTelemetry best practices, meaning that metrics can be scraped from the appropriate resources via Prometheus and visualized with Grafana using Prometheus as a data source.
 
 Logs can be exposed on EC2 Mac workers via CloudWatch or by installing a `promtail` service, allowing them to be aggregated through Loki.
 
@@ -364,8 +360,8 @@
 
 What | Resource | Accessing | Purpose
 ---|---|---|---
 Virtual Kubelet Logs | Mac EC2 Node | Via promtail: `/usr/local/virtual-kubelet/vk.log` | Interactions between EKS and worker node for managing virtualization.
 Orka VM Logs | Mac EC2 Node | Via promtail: `/Users/administrator/.local/state/virtual-kubelet/vm-logs/*` | Logs pertaining to the lifecycle of a specific VM
 Pod Logs | EKS | Kubernetes Client, Kubernetes Dashboard, Helm Chart further exposing logs to a secondary service | All Kubernetes-level behavior
 
 #### Key Metrics
@@ -385,4 +381,4 @@
 macOS 15 Sequoia guest OSes (VMs) will not work out of the box on AWS EC2 Mac. This is due to the newly required Apple ID guest functionality in Sequoia guest OS images which requires the host user that starts the VM to have a login keychain, even if they do not intend to use the Apple ID guest functionality. This is discussed in the [Apple Virtualization documentation](https://developer.apple.com/documentation/virtualization/using-icloud-with-macos-virtual-machines). Unfortunately, Marketplace security requirements do not allow the setup of any credentials on the host OS. As a result we have two options for macOS 15 support:
 
   1. After setting up your EC2 Mac, you will need to set up a login keychain on the host OS before running the Sequoia OS Orka VM image.
   2. MacStadium will supply a Sequoia OCI image that is upgraded from a Sonoma image rather than created from a Sequoia IPSW on Sequoia host. This will run without the Apple ID functionality in guest.

orka/orka-on-aws-and-on-prem/orka-on-prem-getting-started.mdx

@@ -4,7 +4,7 @@
 zendesk_id: 39570839057819
 ---
 
 With Orka On-Prem, you can now effortlessly integrate macOS development and macOS CI/CD into your On-Prem Mac Compute and Kubernetes-based workflows and environments. Don't have Kubernetes experience on-prem? Don't worry, MacStadium can configure a Hybrid Cluster using any Managed k8s Service like AWS Elastic Kubernetes Service, Google Kubernetes Engine, Azure Kubernetes Service, or using MacStadium hosted Kubernetes.
 
 # How does Orka On-Prem work?
 
@@ -12,14 +12,14 @@
 
 ![Orka On-Prem architecture diagram showing Kubernetes, Mac nodes, and OCI registry](/images/attachments/44003753966363.png)
 
 The Kubernetes 1.35 Cluster provides a runtime for the Orka Cluster Services. The Mac hosts are set up with Orka Engine (VM Runtime), which provides a stable runtime for virtual machines. VMs are deployed to the host using an OCI image, which can be fetched from any OCI registry, such as Artifactory, GitHub Container Repo (GHCR), or Amazon ECR. The use of OCI images enables sub-minute deployment of different macOS versions, pre-configured with various tools and optionally with SIP (System Integrity Protection) disabled. This addresses challenges that typically exist on Mac without Orka VMs. CI tools will integrate via the Orka API installed into Kubernetes, or the CLI or API it exposes to orchestrate workloads, including spin-up and tear-down of VMs, and scheduled caching of images as needed.
 
 Key elements in the architecture include:
 
   * A private network configuration for Orka.
   * A dedicated Kubernetes 1.35 cluster, which runs Orka Cluster Services for orchestration and automation.
   * Mac Nodes to be used for compute, usually on-prem.
   * An OCI Registry such as Artifactory, GitHub Container Registry, Docker Registry, AWS ECR, or others..
   * A load balancer for Orka Users to interact with the Orka Services on Kubernetes via CLI, API, or CI tools.
 
 
@@ -30,7 +30,7 @@
 
 You might experience issues if your Orka VMs need to access services that are in a network that overlaps with their virtual network.
 
 For the Apple silicon nodes, the following ports should be open to all networks that need access to the VMs: TCP 5900-6200 (Screenshare), TCP 5999-6299 (VNC), and TCP 8822-9122 (SSH). In general, we recommend allowing outbound requests uniformly for forward compatibility.
 
 > **NOTE**: SSH/Screen Share/VNC ports are globally tracked and allocated. The ranges given above are applicable to each Apple silicon node.
 
@@ -46,15 +46,15 @@
 
 We recommend following the [official guidelines](https://kubernetes.io/docs/setup/) for setting up a Kubernetes cluster. The official recommended tool for setting up Kubernetes clusters is [kubeadm](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/).
 
 If you are familiar with Ansible, you could also use [Kubespray](https://kubespray.io/) to set up your cluster.
 
 If you do not have experience with Kubernetes, MacStadium can host and manage the Kubernetes cluster for you in our Data Centers, or you can use an AWS EKS service to run your Orka Cluster Services.
 
 The following assumes you are installing and managing your own Kubernetes cluster.
 
 ### Setting up OIDC for Authentication
 
 Orka uses OIDC for user authentication. Make sure to configure the MacStadium OIDC provider in your Kubernetes cluster.
 
 This can be done by setting the following values for your Kubernetes API Server:
 
@@ -67,11 +67,11 @@
   --oidc-username-prefix=-
   '--oidc-groups-prefix=oidc:'
 ```
 If you are using kubeadm to set up your cluster, you can pass these values as extra args to the apiServer property in the ClusterConfiguration resource:
 
 
 ```
 apiVersion: kubeadm.k8s.io/v1beta3
 kind: ClusterConfiguration
 ...
 apiServer:
@@ -84,27 +84,21 @@
     oidc-groups-prefix: "oidc:"
 ...
 ```
 Alternatively, you could also add these manually as ApiServer arguments by editing the ApiServer config file (usually /etc/kubernetes/manifests/kube-apiserver.yaml)
 
 ### Obtaining an Orka License Key
 
-Orka Engine requires a valid license key to operate. To request a license key:
+Your license key is included in your order confirmation from MacStadium. If you don't have it, log in to your customer portal at [macstadium.users.licensespring.com](https://macstadium.users.licensespring.com) or contact [support@macstadium.com](mailto:support@macstadium.com).
 
-1. Contact your MacStadium account representative
-
-2. Provide your organization name, deployment details, and use case
-
-3. Your account representative will submit your information to our licensing team for provisioning
-
-4. Receive license key via email (Est. 24 hour turnaround time)
+Add your license key to `cluster.yml` under `orka_engine_license_key` before running the installer (see below).
 
 ### Installing the Orka Cluster Services
 
 MacStadium provides the Orka Cluster Services installer as a public container image on GitHub Container Registry (GHCR). You will need an environment with outbound internet access to pull the Ansible image, connectivity to the Kubernetes API, and cluster admin access.
 
 1. Ensure the Ansible runner is set up correctly:
   1. The Ansible runner must have connectivity to the cluster API.
   2. The Ansible runner must have Cluster Admin privileges to set up the cluster (i.e. a kube config with admin privileges)
 
 2. On the host create a file called `cluster.yml`. This file will contain Ansible variables needed for the Orka setup. Add the following content:
 
@@ -153,7 +147,7 @@
 
 ### Cluster Admin Access
 
 By default, Orka's validator webhooks restrict certain operations (including deleting another user's VM) to cluster admins only. On AWS and on-prem deployments, cluster admin status must be explicitly configured. This differs from MacStadium-hosted clusters, where kubeadm automatically establishes the `kubeadm:cluster-admins` group.
 
 The default admin group for AWS and on-prem is `orka:cluster-admins`. To use a different group, set the `cluster_admin_group` Ansible variable before running the installation playbook.
 
@@ -178,7 +172,7 @@
 
 ### Setup
 
 MacStadium provides another Ansible playbook that allows you to configure your Mac nodes with the software needed to run these nodes as Kubernetes worker nodes.
 
 To set up the Mac Nodes:
 
@@ -214,14 +208,14 @@
 ```
 ansible-playbook configure-arm.yml -i hosts --ask-become-pass
 ```
 You will be asked for the ansible_user password. This is needed so that Ansible can set up autologin for the hosts. This is needed so you can run Sequoia VMs.
 
 ## Setting Up Backups
 
 Orka backups are exports of the Orka specific resources within the cluster:
 
   1. Orka Nodes
   2. Virtualmachine configs
   3. Service Accounts
   4. RoleBindings
 
@@ -234,18 +228,18 @@
      2. You define where the backups are stored
   2. Use the functionality provided by MacStadium
      1. MacStadium provides an Ansible playbook that:
      2. Sets up a cronjob that runs every 30 min by default
      3. The cronjob exports the resources mentioned above by default
      4. The job stores the backups in an S3 bucket that you have specified
 
 
 
 ### Using The MacStadium Provided Backup
 
 To use the MacStadium provided functionality you need to:
 
   1. Create an AWS S3 bucket and generate AWS access id and secret access key that provide permissions to write to the bucket
   2. Run the Ansible image provided by MacStadium and mount a backup.yml file with the following content
 
 ```
      aws_access_key_id_backup: # The creds that allow access to the S3 bucket
@@ -266,11 +260,11 @@
 ```
 ### Implementing Your Own Backup
 
 The recommended way to backup Orka resources is via a CronJob, similar to what MacStadium provides out of the box.
 
 The resources you need to backup are:
 
   1. All namespaces with the label orka.macstadium.com/namespace
 
 ```
      kubectl get namespaces -l orka.macstadium.com/namespace=true -o yaml \
@@ -278,20 +272,20 @@
 ```
 Note - we are removing some metadata as otherwise restore would fail.
 
   2. OrkaNodes, VirtualMachineConfigs, ServiceAccounts, Rolebindings from these namespaces
 Note - you need to remove some metadata from these resources. To do that, run the following:
 
 ```
      kubectl get "$resource" -n "$namespace" -o yaml \
         yq eval 'del(.items[].metadata.resourceVersion, .items[].metadata.uid, .items[].metadata.creationTimestamp, .items[].metadata.selfLink, .items[].metadata.managedFields, .items[].metadata.ownerReferences, .items[].metadata.generation, .items[].status)'
 ```
 These resources can be stored in an yml file, which you can archive and store somewhere.
 
 # Logging, Monitoring, and Alerting
 
 ## OpenTelemetry Standards
 
 Logging and monitoring conform to OpenTelemetry best practices, meaning that metrics can be scraped from the appropriate resources via Prometheus and visualized with Grafana using Prometheus as a data source.
 
 Logs can be exposed on Mac workers installing a `promtail` service, allowing them to be aggregated through Loki.
 
@@ -299,16 +293,16 @@
 
 | What | Resource | Accessing | Purpose |
 | --- | --- | --- | --- |
 | Virtual Kubelet Logs | Mac Node | Via promtail: `/usr/local/virtual-kubelet/vk.log` | Interactions between k8s and worker node for managing virtualization. |
 | Orka VM Logs | Mac Node | Via promtail: `/Users/administrator/.local/state/virtual-kubelet/vm-logs/*` | Logs pertaining to the lifecycle of a specific VM |
 | Pod Logs | k8s | Kubernetes Client, Kubernetes Dashboard, Helm Chart further exposing logs to a secondary service | All Kubernetes-level behavior |
 
 #### Orka v3.4+ Log Sources
 
 | What | Resource | Accessing | Purpose |
 | --- | --- | --- | --- |
 | Virtual Kubelet Logs | Mac Node | Via promtail: `/var/log/virtual-kubelet/vk.log` | Interactions between k8s and worker node for managing virtualization. |
 | Orka VM Logs | Mac Node | Via promtail: `/opt/orka/logs/vm/` | Logs pertaining to the lifecycle of a specific VM |
 | Orka Engine Logs | Engine Node | `/opt/orka/logs/com.macstadium.orka-engine.server.managed.log` | Logs pertaining to Orka Engine |
 | Pod Logs | k8s | Kubernetes Client, Kubernetes Dashboard, Helm Chart further exposing logs to a secondary service | All Kubernetes-level behavior |
 

remote-desktop-vdi/macstadium-vdi-deployment/deployment-guide.mdx

@@ -1,5 +1,5 @@
 ---
 title: "VDI deployment guide for MacStadium"
 description: "Deploy the Orka-Engine-Orchestration control plane for managing virtual desktops. Runs in a dedicated VM and connects to physical Mac hosts running Orka Engine."
 zendesk_id: 44259626250267
 ---
@@ -32,7 +32,7 @@
   - 10GB Ethernet
   - macOS 14 (Sonoma), 15 (Sequoia), or 26 (Tahoe)
 
-An Orka Engine license key and installer URL (contact your MacStadium account representative)
+An Orka Engine license key (included in your order confirmation from MacStadium — if you don't have it, log in to your customer portal at [macstadium.users.licensespring.com](https://macstadium.users.licensespring.com) or contact [support@macstadium.com](mailto:support@macstadium.com))
 An administrator account on each machine
 Network connectivity between the controller and all Mac hosts
 
@@ -47,7 +47,7 @@
 To configure manually:
 
 1. Open System Settings then Network, then select your interface (Ethernet or Wi-Fi).
 2. Set IP Address, Subnet Mask, Router, and DNS Servers from your management VLAN.
 3. Apply settings and verify connectivity.
 
 To use a DHCP reservation:
@@ -60,7 +60,7 @@
 
 | Field             | Example           |
 | ----------------- | ----------------- |
 | Hostname          | mac-node-1        |
 | IP address        | 10.0.100.10       |
 | MAC address       | a1:b2:c3:d4:e5:f6 |
 | Hardware model    | Mac mini M4       |
@@ -68,14 +68,14 @@
 
 ### Firewall Requirements (Citrix DaaS)
 
 If deploying MacStadium VDI with Citrix DaaS, ensure the following traffic is permitted:
 
 Outbound from VMs (TCP 443):
 
 - `[customer_ID].xendesktop.net` - Citrix DaaS controller
 - `*.*.nssvc.net` - Citrix Gateway Service
 - `*.citrixworkspacesapi.net` - Gateway connectivity checks
 - On-premises delivery controller FQDNs (for CVAD deployments)
 - If Citrix Rendezvous is enabled, also allow outbound TCP/UDP 443 to _._.nssvc.net.
 
 Inbound to VMs:
@@ -86,10 +86,10 @@
 
 Run the steps in this section on the designated Ansible controller machine.
 
 ### 1.1  Set the Hostname
 
 **Run on: Controller**
 Set a consistent hostname before configuring anything else. This ensures that your VDI tools are able to label the host devices accordingly. Replace example-controller with your chosen name.
 
 ```
 sudo scutil --set ComputerName "example-controller"
@@ -113,7 +113,7 @@
 
 **Run on: Controller**
 
 Modern versions of macOS protect against installing python packages system-wide. Install Ansible through pipx in a virtual environment so it is isolated from system Python packages.
 
 ```
 brew install pipx
@@ -121,17 +121,17 @@
 pipx install ansible==11.4.0
 ```
 
 **Note:** Optionally install sshpass if you prefer password-based authentication instead of key exchange: brew tap esolitos/ipa && brew install esolitos/ipa/sshpass
 
 ## 2.  Host Setup
 
 Run the steps in this section on each physical Mac host. Repeat for every host in your fleet.
 
 ### 2.1  Set the Hostname
 
 **Run on: Host(s)**
 
 Replace example-host0 with the appropriate hostname for each machine. Use a short name (no dots) for HostName.
 
 ```
 sudo scutil --set ComputerName "example-host0"
@@ -178,7 +178,7 @@
 
 **Run on: Controller**
 
 Run ssh-copy-id once per host, substituting the correct IP address each time.
 
 ```
 ssh-copy-id administrator@10.254.235.xx
@@ -255,12 +255,12 @@
 
 Variable reference:
 
 | max_vms_per_host  | Maximum VMs allowed per host                                  |
 | ----------------- | ------------------------------------------------------------- |
 | engine_binary     | Path to the Orka Engine binary                                |
 | ansible_user      | SSH username on each host                                     |
 | vm_image          | Default base image for VM deployments                         |
 | network_interface | (Optional) Network interface for bridged networking, e.g. en0 |
 
 ## 5.  Install Orka Engine
 
@@ -274,7 +274,7 @@
 ansible-playbook install_engine.yml -i inventory -e "orka_license_key=YOUR-LICENSE-KEY" -e "engine_url=https://distribution.macstadium.com/orka-engine/official/3.5.2/orka-engine.pkg"
 ```
 
-**Note:** Obtain your license key and installer URL from your MacStadium account representative.
+**Note:** Your license key is included in your order confirmation from MacStadium. If you don't have it, log in to your customer portal at [macstadium.users.licensespring.com](https://macstadium.users.licensespring.com) or contact [support@macstadium.com](mailto:support@macstadium.com). The installer URL is already included in the command above.
 
 ### 5.1  Verify the Installation
 
@@ -289,7 +289,7 @@
 
 **Run on: Controller**
 
 Add the install_engine_force flag to reinstall or upgrade to a newer version:
 
 ```
 ansible-playbook install_engine.yml -i inventory -e "orka_license_key=YOUR-LICENSE-KEY" -e "engine_url=https://distribution.macstadium.com/orka-engine/official/3.5.2/orka-engine.pkg" -e "install_engine_force=true"
@@ -297,7 +297,7 @@
 
 ## 6.  Deploy and Manage VMs
 
 All playbook commands are run from the controller inside ~/orka-automation/orka-engine-orchestration.
 
 ### 6.1  Deploy VMs
 
@@ -317,7 +317,7 @@
 
 _Run this command once for each additional VM, using a unique `vm_name` each time._
 
 **Note:** When network_interface is not specified, VMs deploy in NAT mode. Bridged mode is recommended for VDI because VMs are directly reachable by Citrix Cloud and end users without port forwarding.
 
 To preview what will be deployed without making any changes, add `--tags plan`:
 
@@ -337,7 +337,7 @@
 
 **Run on: Controller**
 
 Start, stop, or delete a specific VM by name. Valid values for desired_state are running, stopped, and absent.
 
 ```
 ansible-playbook vm.yml -i inventory -e "vm_name=my-vm-name" -e "desired_state=running"
@@ -367,7 +367,7 @@
 
 ## 7.  Semaphore Web UI
 
 Semaphore provides a browser-based interface for running orchestration playbooks. It is the primary way IT administrators interact with MacStadium VDI. The CLI is available for troubleshooting and advanced or custom workflows. All task templates, inventory, and repository configuration are set up automatically on first launch.
 
 ### 7.1  Install Prerequisites
 
@@ -471,7 +471,7 @@
 | Android: Install SDK Components | `sdkmanager_install.yml` | `platform`, `image_types` (optional) |
 | Android: Uninstall SDK Components | `sdkmanager_uninstall.yml` | `platform` |
 | Android: Deploy AVD | `deploy_avd.yml` | `vm_name`, `platform` (optional), `image_type` (optional) |
 | Android: List AVDs | `list_avds.yml` | `vm_name` (optional) |
 | Android: Delete AVD | `delete_avd.yml` | `vm_name`, `avd_index` |
 | Android: Manage AVD | `avd.yml` | `vm_name`, `desired_state` (`running`, `stopped`, `absent`), `avd_index` (optional), `cpu` (optional), `memory` (optional) |
 | Citrix: Install Citrix VDA | `install_citrix_vda.yml` | `vm_name` |
@@ -493,9 +493,9 @@
 
 ## 8.  Image Management
 
 ### 8.1  Using MacStadium Public Images
 
 MacStadium maintains public base images through GitHub Container Registry. No authentication is required. Reference them by OCI path: `ghcr.io/macstadium/orka-images/[os-version]:latest`
 
 Available images include Tahoe, Sequoia, Ventura, and Sonoma. Use the image name matching your target macOS version.
 
@@ -523,7 +523,7 @@
 
 ### 8.4  Private Registry Naming
 
 If using a self-hosted registry (Harbor, Docker Registry, JFrog Artifactory), use a consistent naming convention:
 
 `registry.example.com/orka/citrix-vda/sequoia-finance:v1.0`
 `registry.example.com/orka/citrix-vda/sequoia-engineering:v2.1`
@@ -544,11 +544,11 @@
 
 **Note:** The following remote host CLI commands are for advanced troubleshooting and diagnostics. It is recommended to use the Ansible playbooks or Semaphore UI when available.
 
 | MacStadium Support             | [support@macstadium.com](mailto:support@macstadium.com)                                        |
 | ------------------------------ | ---------------------------------------------------------------------------------------------- |
 | orka-engine-orchestration repo | [orka-engine-orchestration on GitHub](https://github.com/macstadium/orka-engine-orchestration) |
 | Orka Engine CLI help           | orka-engine --help                                                                             |
 | VM commands                    | orka-engine vm --help                                                                          |
 | Image commands                 | orka-engine image --help                                                                       |
 | Ansible docs                   | [Ansible documentation](https://docs.ansible.com)                                              |
 | Citrix VDA for macOS           | [Citrix documentation](https://docs.citrix.com)                                                |