Ansible quick reference - MacStadium Docs

Run these commands from the root of your orka-engine-orchestration clone. They use -i dev/inventory, the inventory next to dev/group_vars, so Ansible loads the variables you set there.

Setup Commands

Test Connectivity

ansible hosts -i dev/inventory -m ping

Check Orka Engine Status

ansible hosts -i dev/inventory -m shell -a "/usr/local/bin/orka-engine info"

Verify Python Version

ansible hosts -i dev/inventory -m shell -a "python3 --version"

One-Liner Examples

Install/Upgrade Orka Engine

ansible-playbook -i dev/inventory install_engine.yml -e "orka_license_key=<ORKA_LICENSE_KEY>" -e "engine_url=<ENGINE_URL>"

Plan Deployment (Dry Run)

ansible-playbook -i dev/inventory deploy.yml -e "vm_name=my-vm" --tags plan

Deploy VM

ansible-playbook -i dev/inventory deploy.yml -e "vm_name=my-vm" -e "vm_image=ghcr.io/macstadium/orka-images/sonoma:latest" -e "network_interface=en0"

Set network_interface to the host’s network interface, for example en0, for bridged networking. Without it, the VM uses NAT, and Citrix Cloud and end users can’t reach it.

Deleting VMs matches names by prefix. delete.yml, and vm.yml with desired_state=absent, delete every VM whose name starts with the vm_name you pass, not only the VM with that exact name. For example, vm_name=citrix-vda-finance deletes every VM in that group. Before you delete, run list.yml and make sure no VM you want to keep has a name that starts with the value you’re passing.

Plan Deletion (Dry Run)

ansible-playbook -i dev/inventory delete.yml -e "vm_name=my-vm" --tags plan

Delete VM

ansible-playbook -i dev/inventory delete.yml -e "vm_name=my-vm"

Stop VM

ansible-playbook -i dev/inventory vm.yml -e "vm_name=my-vm" -e "desired_state=stopped"

Start VM

ansible-playbook -i dev/inventory vm.yml -e "vm_name=my-vm" -e "desired_state=running" -e "network_interface=en0"

Pass network_interface every time you start a VM, including when vm.yml starts a whole prefix group. Orka Engine doesn’t save the network interface with the VM, so a VM started without it comes up on NAT, where Citrix Cloud and end users can’t reach it.

Delete VMs by name prefix

ansible-playbook -i dev/inventory vm.yml -e "vm_name=my-vm" -e "desired_state=absent"

List All VMs

ansible-playbook -i dev/inventory list.yml

List VMs by Name

ansible-playbook -i dev/inventory list.yml -e "vm_name=my-vm"

Pull Image to All Hosts

ansible-playbook -i dev/inventory pull_image.yml -e "remote_image_name=ghcr.io/macstadium/orka-images/sonoma:latest"

Create and Push Custom Image

ansible-playbook -i dev/inventory create_image.yml -e "vm_image=ghcr.io/macstadium/orka-images/sonoma:latest" -e "remote_image_name=registry.example.com/custom:v1.0"

Create Image with OS Upgrade

ansible-playbook -i dev/inventory create_image.yml -e "vm_image=base:latest" -e "remote_image_name=registry.example.com/custom:v1.0" -e "upgrade_os=true"

Android Virtual Devices

Install Android SDK on Hosts

ansible-playbook -i dev/inventory install_android_sdk.yml

To force reinstallation on hosts where the SDK is already present:

ansible-playbook -i dev/inventory install_android_sdk.yml -e "install_android_sdk_force=true"

Install SDK Platforms and System Images

ansible-playbook -i dev/inventory sdkmanager_install.yml

With a specific platform and image types:

ansible-playbook -i dev/inventory sdkmanager_install.yml -e "platform=android-34" -e "image_types=default,google_apis,google_apis_playstore"

Create an AVD (Plan First)

ansible-playbook -i dev/inventory deploy_avd.yml -e "vm_name=my-vm" --tags plan

Create an AVD

ansible-playbook -i dev/inventory deploy_avd.yml -e "vm_name=my-vm"

With custom platform, image type, and resources:

ansible-playbook -i dev/inventory deploy_avd.yml -e "vm_name=my-vm" -e "platform=android-34" -e "image_type=google_apis" -e "cpu=4" -e "memory=2048"

Manage AVD State

# Start AVD
ansible-playbook -i dev/inventory avd.yml -e "vm_name=my-vm" -e "desired_state=running"

# Stop AVD
ansible-playbook -i dev/inventory avd.yml -e "vm_name=my-vm" -e "desired_state=stopped"

# Delete AVD (specify index if multiple exist)
ansible-playbook -i dev/inventory avd.yml -e "vm_name=my-vm" -e "desired_state=absent" -e "avd_index=0"

List AVDs

# All AVDs across all hosts
ansible-playbook -i dev/inventory list_avds.yml

# Filter by VM
ansible-playbook -i dev/inventory list_avds.yml -e "vm_name=my-vm"

Delete AVD by Index

ansible-playbook -i dev/inventory delete_avd.yml -e "vm_name=my-vm" -e "avd_index=0"

Uninstall SDK Platform

ansible-playbook -i dev/inventory sdkmanager_uninstall.yml

# Target a specific platform
ansible-playbook -i dev/inventory sdkmanager_uninstall.yml -e "platform=android-34"

Common Variable Combinations

Deploy with Custom CPU and Memory

ansible-playbook -i dev/inventory deploy.yml -e "vm_name=dev-desktop" -e "vm_image=ghcr.io/macstadium/orka-images/sonoma:latest" -e "cpu=4" -e "memory=8192" -e "network_interface=en0"

Deploy with Network Interface

ansible-playbook -i dev/inventory deploy.yml -e "vm_name=prod-desktop" -e "vm_image=ghcr.io/macstadium/orka-images/sonoma:latest" -e "network_interface=en0"

Deploy to Specific Host

ansible-playbook -i dev/inventory deploy.yml -e "vm_name=build-01" -e "vm_image=ghcr.io/macstadium/orka-images/sonoma:latest" -e "network_interface=en0" --limit mac-node-1,localhost

deploy.yml builds its plan on the Ansible control node, so include localhost in --limit.

Image Creation with Auth

ansible-playbook -i dev/inventory create_image.yml -e "vm_image=base:latest" -e "remote_image_name=registry.company.com/app:v2.0" -e "registry_username=<REGISTRY_USERNAME>" -e "registry_password=<REGISTRY_PASSWORD>" -e "insecure_push=false"

Insecure Registry

ansible-playbook -i dev/inventory pull_image.yml -e "remote_image_name=insecure-registry:5000/image:latest" -e "insecure_pull=true"

Image Naming Patterns

MacStadium Public Images

Tahoe: ghcr.io/macstadium/orka-images/tahoe:latest
Sequoia: ghcr.io/macstadium/orka-images/sequoia:latest
Sonoma: ghcr.io/macstadium/orka-images/sonoma:latest

Private Registry Format

Full path: registry.example.com/organization/repository:tag
With port: registry.example.com:5000/orka/image:v1.0

VM Naming Convention

list.yml, vm.yml, and delete.yml match VM names by prefix, so give related VMs a shared name prefix, and don’t give a VM a name that is the start of another VM’s name. Use clear, descriptive names:

dev-desktop-01, dev-desktop-02
prod-build-runner-01, prod-build-runner-02
ci-macOS-sonoma

AVDs are named automatically based on the VM: {vm_name}-avd-0, {vm_name}-avd-1, etc.

Ansible Shortcuts

Run on Single Host

ansible-playbook -i dev/inventory <PLAYBOOK>.yml --limit mac-node-1

Playbooks that build a plan or list results on the Ansible control node, such as deploy.yml, delete.yml, and list.yml, also need localhost in the limit: --limit mac-node-1,localhost.

Dry run

The orchestration modules that query Orka Engine don’t support Ansible check mode, so --check fails. To preview changes, run deploy.yml, delete.yml, deploy_avd.yml, delete_avd.yml, or avd.yml with --tags plan:

ansible-playbook -i dev/inventory deploy.yml -e "vm_name=my-vm" --tags plan

Verbose Output

# Verbose output
ansible-playbook -i dev/inventory <PLAYBOOK>.yml -v

# More verbose output
ansible-playbook -i dev/inventory <PLAYBOOK>.yml -vv

# Debug level output
ansible-playbook -i dev/inventory <PLAYBOOK>.yml -vvv

Skip Tags

The plays in create_image.yml that deploy the image-host build VM and add it to the inventory aren’t tagged, so --tags configure or --tags push on their own match no hosts and do nothing. To keep the build VM running after the image is pushed, skip the delete step instead:

ansible-playbook -i dev/inventory create_image.yml --skip-tags delete

Step Through Tasks

ansible-playbook -i dev/inventory <PLAYBOOK>.yml --step

Best Practices Checklist

Planning and Safety

Always use --tags plan before production deployments
Test playbooks on single host first with --limit
Review deployment plan output before executing
Verify capacity before large deployments

Naming and Organization

Use clear, descriptive VM names (for example, prod-desktop-01, build-runner-sonoma)
Version your images with tags (:v1.0, :v2.0, not :latest in prod)
Document VM purposes in inventory comments

Capacity Management

Set appropriate max_vms_per_host limits
Monitor disk space on hosts regularly
Keep Orka Engine updated across all hosts
Track VM distribution across hosts

Image Management

Place custom configuration scripts in the scripts/ directory at the root of your orka-engine-orchestration clone
Test image builds in dev before production
Keep base images cached on all hosts
Implement regular image rebuild schedule

Security and Operations

Store credentials as secrets in the management UI, or pass them at run time with -e. Don’t commit them to Git
Maintain inventory file accuracy
Use SSH keys (not passwords) for host access
Rotate credentials regularly
Review deployment logs for errors

State and Tracking

Let Ansible manage VMs (use playbooks, not manual creation)
Use list.yml to verify state before changes
Keep group vars consistent across environments

Support Resources

Documentation: MacStadium
Support Portal: support@macstadium.com
CLI Reference: orka-engine --help
VM Commands: orka-engine vm --help
Image Commands: orka-engine image --help
Project README: Check your repository’s README.md for architecture details

​Setup Commands

​Test Connectivity

​Check Orka Engine Status

​Verify Python Version

​One-Liner Examples

​Install/Upgrade Orka Engine

​Plan Deployment (Dry Run)

​Deploy VM

​Plan Deletion (Dry Run)

​Delete VM

​Stop VM

​Start VM

​Delete VMs by name prefix

​List All VMs

​List VMs by Name

​Pull Image to All Hosts

​Create and Push Custom Image

​Create Image with OS Upgrade

​Android Virtual Devices

​Install Android SDK on Hosts

​Install SDK Platforms and System Images

​Create an AVD (Plan First)

​Create an AVD

​Manage AVD State

​List AVDs

​Delete AVD by Index

​Uninstall SDK Platform

​Common Variable Combinations

​Deploy with Custom CPU and Memory

​Deploy with Network Interface

​Deploy to Specific Host

​Image Creation with Auth

​Insecure Registry

​Image Naming Patterns

​MacStadium Public Images

​Private Registry Format

​VM Naming Convention

​Ansible Shortcuts

​Run on Single Host

​Dry run

​Verbose Output

​Skip Tags

​Step Through Tasks

​Best Practices Checklist

​Planning and Safety

​Naming and Organization

​Capacity Management

​Image Management

​Security and Operations

​State and Tracking

​Support Resources

Setup Commands

Test Connectivity

Check Orka Engine Status

Verify Python Version

One-Liner Examples

Install/Upgrade Orka Engine

Plan Deployment (Dry Run)

Deploy VM

Plan Deletion (Dry Run)

Delete VM

Stop VM

Start VM

Delete VMs by name prefix

List All VMs

List VMs by Name

Pull Image to All Hosts

Create and Push Custom Image

Create Image with OS Upgrade

Android Virtual Devices

Install Android SDK on Hosts

Install SDK Platforms and System Images

Create an AVD (Plan First)

Create an AVD

Manage AVD State

List AVDs

Delete AVD by Index

Uninstall SDK Platform

Common Variable Combinations

Deploy with Custom CPU and Memory

Deploy with Network Interface

Deploy to Specific Host

Image Creation with Auth

Insecure Registry

Image Naming Patterns

MacStadium Public Images

Private Registry Format

VM Naming Convention

Ansible Shortcuts

Run on Single Host

Dry run

Verbose Output

Skip Tags

Step Through Tasks

Best Practices Checklist

Planning and Safety

Naming and Organization

Capacity Management

Image Management

Security and Operations

State and Tracking

Support Resources