DOCSEARCHbyAlgolia
Submit Docs

MacStadium Documentation

website·Indexed 37 days ago

https://docs.macstadium.com

Technical guides for MacStadium IaaS, featuring bare metal Mac configurations, benchmarks, and CI/CD tool setup for Xcode, Homebrew, Ansible, and Packer. Includes detailed networking documentation for site-to-site IPsec VPN configuration with AWS and Azure, as well as management of Cisco ASA/ASAv firewalls via ASDM and CLI.

Tokens
183.4K
Snippets
660
Records
1.3K
Agent score
65%

What's inside MacStadium

  1. Overview of Orka nodes and architecture

    Orka nodes are the physical Mac hardware in a cluster that provide compute resources (CPU, memory, and storage) for running VMs. Nodes are categorized by architecture:

    • Intel nodes (amd64): Mac Pro, Mac mini (Intel), iMac Pro
    • Apple silicon nodes (arm64): Mac mini (M1/M2/M3), Mac Studio

    Nodes belong to namespaces and only provide resources to VMs within that same namespace. If no --namespace flag is provided in CLI commands, the orka-default namespace is used.

  2. Overview of SAML Single Sign-On for MacStadium

    MacStadium supports SAML Single Sign-On (SSO) to allow organizations to manage user authentication and access through a centralized Identity Provider (IdP). This integration enables centralized user management, a streamlined login experience, and the enforcement of IdP security policies like Multi-Factor Authentication (MFA).

    Note: SAML SSO is a paid offering. To enable it, contact your account team via the MacStadium portal.

  3. Overview of Orka VM Tools for ARM VMs

    Orka VM Tools are background services required for coordination between the Orka host and the guest operating system on ARM-based virtual machines running macOS 13 or later. They are mandatory for the following features:

    • Disk resizing: Resizing the VM's disk without redeploying.
    • Shared attached disks: Attaching a single shared disk to multiple VMs simultaneously.

    Critical: The version of Orka VM Tools must match the version of the Orka cluster (e.g., if the cluster is 3.x, VM Tools must be 3.x) to avoid failures in disk resizing and shared storage.

  4. Overview of MacStadium VDI business outcomes

    MacStadium VDI provides virtual macOS desktops hosted on genuine Apple hardware (Mac mini and Studio) in SOC 2 and ISO 27001 compliant data centers. It is designed to solve three primary business challenges:

    1. Global Distribution: Eliminates the need to ship physical Macs to international contractors or remote employees, reducing onboarding time from weeks to hours.
    2. Security & Data Sovereignty: Prevents data loss from stolen devices by keeping all intellectual property and source code within the data center. It allows organizations to meet strict data sovereignty requirements by ensuring data resides and is accessed only within specific jurisdictions (e.g., the US).
    3. Operational Efficiency: Removes the administrative burden of manually provisioning, configuring, and shipping hardware, while reducing Hardware CapEx by eliminating the need to purchase high-end laptops for remote users.

  5. Overview of Orka Upgrade Service

    The Orka Upgrade Service provides a durable, observable way to upgrade an Orka cluster to a selected release using the orka3 CLI. It coordinates the control plane and Apple silicon nodes, recording progress in Kubernetes to prevent failures on a single node from silently spreading across the fleet.

    Key Constraints:

    • It is for planned, manually initiated upgrades of Orka's node-local software (Orka Engine and Virtual Kubelet).
    • It does NOT upgrade the macOS guest operating system.
    • It is not a scheduler, auto-update service, or a tool for installing unpublished builds.
    • Only one upgrade run can execute at a time.

  6. Overview of Bazel RBE Architecture with Orka

    Bazel Remote Build Execution (RBE) separates the build process into a control plane (scheduling, cache management, routing) and a worker pool (execution). For iOS and macOS builds, Orka VMs serve as the macOS worker pool. The RBE server and cache typically run on a Linux VM co-located in the MacStadium environment, while macOS workers are deployed from versioned OCI images.
    [Developer / CI] 
       |
       | gRPC (remote-apis protocol)
       v
[RBE server (Linux VM)]
  bazel-buildfarm or BuildBuddy
  Redis backplane (buildfarm only)
       |
       | dispatch to workers
       v
[Orka macOS VMs (worker pool)]
  Xcode, Homebrew, Java, Bazelisk
  bazel-buildfarm worker or BuildBuddy executor
       |
       v
[Remote cache (Linux VM or S3)]
  bazel-remote, buildfarm CAS, or BuildBuddy cache

  7. Overview of Android emulators on Orka

    Orka allows Android emulators to run as first-class resources on Apple silicon (M-series) nodes. Because Apple silicon does not support nested virtualization, the emulator runs directly on the host Mac as a separate process and is connected to a macOS VM via an ADB relay bridge. This enables running iOS and Android tests within the same CI job. The emulator lifecycle is tied to the VM; deleting the VM automatically cleans up the associated emulator.

  8. Overview of Azure to MacStadium Site-to-Site VPN options

    To establish a persistent connection between Azure and a MacStadium private cloud, an IPsec Site-to-Site VPN is used. There are two primary availability modes:

    • Active/Standby (Active/Active Disabled): The Azure VPN gateway consists of two instances. If the active instance fails or undergoes maintenance, the standby instance automatically takes over.
    • Active/Active Enabled: Each Azure gateway instance has a unique public IP address, and both establish IPsec tunnels to the MacStadium firewall. This mode requires enabling the TCP state bypass feature on the Cisco ASA firewall (via access-list, class-map, policy-map, and service-policy) to allow asynchronous routing between separate VPN tunnels for Virtual Tunnel Interfaces (VTI).

    Both modes support static or dynamic routing via BGP.

  9. Overview of MacStadium VDI (macOS DaaS)

    MacStadium VDI is a macOS Desktop-as-a-Service (DaaS) solution that allows organizations to provision and manage macOS virtual desktops running on genuine Apple silicon hardware. Each virtual desktop runs as a macOS VM on a bare metal Mac host. The system is orchestrated via the Orka Engine and automated using Ansible. While it supports various VDI tools, MacStadium provides primary support for Citrix DaaS.

  10. Overview of Private Cloud VM and Cloud Snapshots

    Snapshots provide point-in-time copies of a VM or Private Cloud storage to revert environments to a previous state. There are two types:

    • Cloud Snapshot: A snapshot of an entire Private Cloud instance, including every VM and volume.
    • VM Snapshot: A snapshot of an individual Virtual Machine.

    Note: Snapshots restore existing entities to a previous state; they do not clone a VM into a new instance.

  11. Overview of upgrading self-managed Orka Anywhere clusters

    Upgrading a self-managed Orka Anywhere cluster (AWS-hosted or on-premises) is a self-service process using the same Ansible-based workflow used during initial installation. Every upgrade consists of two parts: the Services upgrade (updating Orka Kubernetes services) and the Node tooling upgrade (updating the Virtual Kubelet and Orka Engine on ARM Mac nodes in place).

  12. Overview of HashiCorp Packer for VM Image Creation

    Packer is an open-source, command-line-driven tool used to create machine images of virtual machines. It allows for the creation of a live image that can be cloned rapidly, reducing deployment time from minutes or hours to seconds. Packer uses JSON to define VM templates and is designed to be integrated into build pipelines. It is not a replacement for configuration management tools; instead, it interfaces with provisioning solutions like Chef, Puppet, and Ansible to provision the base VM image.