> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 /inventory -m ping
```

### Check Orka Engine Version

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

### Verify Python Version

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

***

## One-Liner Examples

### Install/Upgrade Orka Engine

```
ansible-playbook -i /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 /inventory deploy.yml \
  -e "vm_name=my-vm" \
  --tags plan
```

### Deploy VM

```
ansible-playbook -i /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 /inventory delete.yml \
  -e "vm_name=my-vm" \
  --tags plan
```

### Delete VM

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

### Stop VM

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

### Start VM

```
ansible-playbook -i /inventory vm.yml \
  -e "vm_name=my-vm" \
  -e "desired_state=running"
```

### Delete Single VM

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

### List All VMs

```
ansible-playbook -i /inventory list.yml
```

### List VMs by Name

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

### Pull Image to All Hosts

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

### Create and Push Custom Image

```
ansible-playbook -i /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 /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 /inventory install_android_sdk.yml
```

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

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

### Install SDK Platforms and System Images

```
ansible-playbook -i /inventory sdkmanager_install.yml
```

With a specific platform and image types:

```
ansible-playbook -i /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 /inventory deploy_avd.yml \
  -e "vm_name=my-vm" \
  --tags plan
```

### Create an AVD

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

With custom platform, image type, and resources:

```
ansible-playbook -i /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 /inventory avd.yml \
  -e "vm_name=my-vm" \
  -e "desired_state=running"

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

# Delete AVD (specify index if multiple exist)
ansible-playbook -i /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 /inventory list_avds.yml

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

### Delete AVD by Index

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

### Uninstall SDK Platform

```
ansible-playbook -i /inventory sdkmanager_uninstall.yml

# Target a specific platform
ansible-playbook -i /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

* **Sonoma**: `ghcr.io/macstadium/orka-images/sonoma:latest`
* **Ventura**: `ghcr.io/macstadium/orka-images/ventura:latest`
* **Monterey**: `ghcr.io/macstadium/orka-images/monterey: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 /inventory <playbook.yml> --limit mac-node-1
```

### Dry Run (Check Mode)

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

### Verbose Output

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

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

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

### Run Specific Tags

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

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

### Skip Tags

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

### Step Through Tasks

```
ansible-playbook -i /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 (e.g., `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](https://docs.macstadium.com)

* **Support Portal** : [support@macstadium.com](mailto: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