Ansible quick reference - MacStadium Docs

Setup Commands

Test Connectivity

ansible hosts -i dev/inventory -m ping

Check Orka Engine Version

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

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=YOUR_KEY" -e "engine_url=https://download.url/orka-engine"

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"

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"

Delete Single VM

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 inventory deploy.yml -e "vm_name=dev-desktop" -e "vm_image=ghcr.io/macstadium/orka-images/sonoma:latest" -e "cpu=4" -e "memory=8192"

Deploy with Network Interface

ansible-playbook -i 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 inventory deploy.yml -e "vm_name=build-01" -e "vm_image=ghcr.io/macstadium/orka-images/sonoma:latest" --limit mac-node-1

Image Creation with Auth

ansible-playbook -i inventory create_image.yml -e "vm_image=base:latest" -e "remote_image_name=registry.company.com/app:v2.0" -e "registry_username=deploy" -e "registry_password=secret" -e "insecure_push=false"

Insecure Registry

ansible-playbook -i 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

VMs are identified individually by name. Use clear, descriptive names:

dev-desktop-01, dev-desktop-02
prod-build-runner, prod-build-runner-2
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

Dry Run (Check Mode)

ansible-playbook -i dev/inventory <playbook.yml> --check

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

Run Specific Tags

# Run only tasks tagged with 'configure'
ansible-playbook -i dev/inventory create_image.yml --tags configure

# Run only tasks tagged with 'push'
ansible-playbook -i dev/inventory create_image.yml --tags push

Skip Tags

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 /scripts directory
Test image builds in dev before production
Keep base images cached on all hosts
Implement regular image rebuild schedule

Security and Operations

Store credentials securely (Ansible Vault)
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 Version

​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 Single VM

​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 (Check Mode)

​Verbose Output

​Run Specific Tags

​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