Ansible quick reference

Quick-reference Ansible commands for Orka-based Citrix VDI: connectivity tests, Orka Engine checks, VM lifecycle, VDA management, and image operations.

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: [e-mail]

• 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