Skip to main content

​
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_group=webapp" \
  -e "desired_vms=10" \
  --tags plan

​
Deploy VM Group

ansible-playbook -i /inventory deploy.yml \
  -e "vm_group=webapp" \
  -e "desired_vms=10"

​
Plan Deletion (Dry Run)

ansible-playbook -i /inventory delete.yml \
  -e "vm_group=webapp" \
  -e "delete_count=5" \
  --tags plan

​
Delete VM Group

ansible-playbook -i /inventory delete.yml \
  -e "vm_group=webapp" \
  -e "delete_count=5"

​
Stop VM

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

​
Start VM

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

​
Delete Single VM

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

​
List All VMs

ansible-playbook -i /inventory list.yml

​
List VMs from Group

ansible-playbook -i /inventory list.yml -e "vm_group=webapp"

​
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"

​
Common Variable Combinations

​
Small Development Group

ansible-playbook -i inventory deploy.yml \
  -e "vm_group=dev" \
  -e "desired_vms=5" \
  -e "max_vms_per_host=2"

​
Medium Production Group

ansible-playbook -i inventory deploy.yml \
  -e "vm_group=prod-webapp" \
  -e "desired_vms=20" \
  -e "max_vms_per_host=5"

​
Large-Scale Deployment

ansible-playbook -i inventory deploy.yml \
  -e "vm_group=build-farm" \
  -e "desired_vms=100" \
  -e "max_vms_per_host=10"

​
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

​
Private Registry Format

​
VM Naming Convention

VMs are automatically named with group prefix:
  • Group webapp → VMs: webapp-abc123, webapp-def456, etc.
  • Group dev → VMs: dev-xyz789, dev-uvw456, 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 & 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 & Organization

  • Use meaningful VM group names (e.g., webapp-prod, build-farm-dev)
  • Version your images with tags (:v1.0, :v2.0, not :latest in prod)
  • Document group 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 & 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 & Tracking

  • Let Ansible manage VM counts (incremental deployment)
  • Don’t manually create VMs in managed groups
  • Use list.yml to verify state before changes
  • Keep group vars consistent across environments

​
Support Resources

    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