IT Administrator Onboarding Guide

• Understanding your role and responsibilities in the support and maintenance of your organization’s Orka for VDI architecture
• Navigating core management interfaces (Ansible, Citrix Cloud, Orka Engine)
• Executing common operational tasks (provisioning desktops, managing images, troubleshooting)
• Establishing operational best practices for your Orka for VDI environment

​

Your role in managing Orka for VDI

• Hosts MacOS VMs on Apple Silicon hardware
• Manages VM lifecycle (create, start, stop, delete)
• Handles image storage and distribution

• Brokers user connections to desktops
• Manages Machine Catalogs and Delivery Groups
• Controls access policies and user assignments

• Automates VM deployment and lifecycle operations
• Maintains configuration consistency
• Coordinates image management across hosts

​

Key concepts and terminology

• Orka host: Physical Mac running Orka Engine (e.g. Mac mini M4, Mac Studio)
• VM group: A logical collection of VMs managed together (e.g. citrix-vda-finance, citrix-vda-engineering)
• Golden image: Template VM with MacOS, Citrix VDA, and applications pre-installed
• Max VMs per host: Typically two, due to Apple licensing restrictions
• Bridged networking: VMs recieve IPs directly from your network (no NAT needed)

• Machine catalog: Collection of VMs with similar configuration (these map to VM groups in Orka)
• Delivery group: Links machine catalog to users and defines access policies
• VDA (Virtual delivery agent): Software on MacOS VM that registers with Citrix Cloud
• Enrollment token: Time-limited credential for VDA registration
• Rendezvous protocol: Enables HDX connections to non-domain-joined VMs

• Inventory: List of Orka hosts (dev/inventory)
• Playbook: YAML file (deploy.yml, vm.yml)
• Group vars: Configuration variables shared across hosts (dev/group_vars/all/main.yml)
• Tags: Selective playbook execution (e.g., --tags plan for dry runs)

​

Architecture overview:

​

​

Ansbile access and credentials setup

​

Ansible control node:

​

Credentials stored in Ansible:

• SSH keys for Orka hosts: ~/.ssh/ansible_orka_key
• Ansible Vault password: .vault_pass (or manually entered)
• Ansible Vault contents: Orka API tokens, Citrix enrollment tokens, registry credentials

• Deploying VMs: ansible-playbook -i dev/inventory deploy.yml
• Managing VM state: ansible-playbook -i dev/inventory vm.yml
• Creating images: ansible-playbook -i dev/inventory create_image.yml

​

Citrix Cloud Console access and credentials setup

​

Key sections:

• Web studio: Machine catalogs, delivery groups, enrollment tokens
• Monitor: Session metrics, connection quality, active users
• Policies: HDX settings, access control, feature restrictions

​

Credentials needed:

• Citrix Cloud administrator account
• Customer ID (visible in Cloud Console, used in VDA configuration)

​

Common tasks performed in Citrix Cloud Console:

• Generating enrollment tokens
• Creating or modifying Delivery Groups
• Assigning users to desktops
• Monitoring session health

​

Orka Hosts

• Debugging Orka Engine issues
• Checking disk space: df -h /var/orka
• Reviewing Orka logs: sudo tail -100 /var/log/orka-engine.log
• Manually inspecting VMs: orka-engine vm list

• SSH key: ~/.ssh/ansible_orka_key (this is the same key Ansible uses)
• User: admin (or whichever user was configured during deployment)

​

OCI registry

​

MacStadium’s public GHCR registry:

• URL: ghcr.io/macstadium/orka-images
• No authentication required
• Base images: sonoma:latest, sequoia:latest, tahoe:latest

​

Private OCI registry:

• URL: Defined in dev/group_vars/all/main.yml (e.g., registry.example.com)
• Credentials: Stored in Ansible Vault (vault_registry_username, vault_registry_password)
• Contains: Your golden images with Citrix VDA pre-installed

​

Common tasks performed when managing OCI images:

• Pulling images: ansible-playbook -i dev/inventory pull_image.yml
• Creating/pushing images: ansible-playbook -i dev/inventory create_image.yml

​

Citrix Cloud Console Navigation

1. Hamburger menu: Navigate between services

 * Select "DaaS" or "Virtual Apps and Desktops" to access Web Studio

2. Web Studio:

 * Machine Catalogs: View registered VMs, enrollment tokens

 * Delivery Groups: User assignments, published desktops

 * Policies: HDX settings, security policies

3. Monitor tab:

 * Real-time session data

 * Connection quality metrics

 * Historical trends

4. Support menu:

 * Documentation links

 * Support case management

• Machine Catalogs → Select your catalog → Verify VMs show “Registered”
• Monitor → Check session launch success rate >95%
• Monitor → Verify there have been no “Unregistered” machines in past 24 hours

​

Connecting to the Ansible Management Node

​

Testing Ansible connectivity

​

If Ansible connectivity fails:

• Verify the SSH key exists: ls -la ~/.ssh/ansible_orka_key
• Test direct SSH connectivity: ssh -i ~/.ssh/ansible_orka_key admin@10.0.100.10
• Check that your Ansible inventory file has the correct IPs listed

Key Ansible variables:

• ansible_user: SSH user (typically admin)
• vm_image: Default golden image path
• max_vms_per_host: VM capacity limit (typically 2)
• .vault_pass: Sensitive credentials (passwords, etc.) are encrypted with Ansible Vault.

* View Vault contents with: `ansible-vault view dev/group_vars/all/vault.yml`

* Note: Keep your `.vault_pass` secure, never commit it to Git. If this is ever lost, you'll need to recreate your Ansible vault file with new credentials.

• Ansible vault contains the following:

* `vault_citrix_enrollment_token`

* `vault_citrix_customer_id`

* `vault_registry_username` / `vault_registry_password`

Reviewing Mac Host inventory

• List all Orka hosts: ansible hosts -i dev/inventory --list-hosts
• Check Orka Engine version on all hosts: ansible hosts -i dev/inventory -m shell -a "orka-engine --version"
• Check capacity per host:

• Check available disk space: ansible hosts -i dev/inventory -m shell -a "df -h /var/orka"

• <70% used: Healthy
• 70-85% used: Plan for cleanup or expansion

• 85% used: Action required (delete old images, expand storage)

• Host IP
• Hardware model (Mac mini M4, Mac Studio M2 Ultra, etc.)
• Current VM count
• Available capacity
• Network interface (10Gb vs 1Gb)
• Notes (e.g., “Reserved for engineering team”)

​

Core workflows

​

Provisioning a new desktop

• The user account exists in your identity provider (Azure AD, Okta, etc.)
• The user is assigned to the appropriate Delivery Group in Citrix Cloud
• There is available capacity on your Orka hosts (at least 1 VM slot free)
• The appropriate golden image is cached on the host(s)

1. Select the appropriate golden image. Determine this based on the user’s department/role/access needs:

2. Run Ansible playbook: VM Deploy

3. Verify VDA registration in Citrix

4. Assign to user/delivery group

​

Managing images

• Create: Build a golden image with macOS + VDA + applications
• Test: Deploy a test VM and validate its functionality
• Publish: Push your image to an OCI registry with an applicable version tag
• Cache: Pull an image to all Orka hosts
• Deploy: Use an image for new VM provisioning
• Update: Apply patches and create a new image version
• Retire: Remove old image versions after migration to a new version is complete

• Configuration scripts are prepared in the /scripts directory
• A base MacOS image is available
• Registry credentials are in Ansible Vault

• Deploy a temporary VM from a base image
• Run configuration scripts
• Commit VM to an image
• Push image to a container registry with a version tag applied
• Delete temporary VM

• Scripts run as admin user with sudo privileges
• Test scripts individually before image creation
• Include error handling (set -e, exit codes)
• Clean up temporary files

• The playbook deploys a temporary VM named image-builder-[timestamp]
• VM boots (2-3 minutes)
• Scripts are copied to the VM via SSH
• Scripts execute sequentially
• VM shuts down cleanly
• The image is committed (in this example, sonoma-finance:v2.0)
• Image is pushed to registry.example.com/citrix-vda/sonoma-finance:v2.0
• Temporary VM is deleted

​

Updating Existing Images

1. Pull the current production image
2. Create a new image version with patches applied
3. Test the image thoroughly
4. Update the vm_image default to new version
5. Recreate VMs from the new image (for persistent desktops)

• Update the vm_image default image
• New sessions will automatically use the updated image
• Existing VMs are recreated upon the next user logout

• Schedule a maintenance window
• Delete old VMs
• Deploy a VM from the newly created image
• Restore user data from backups (if applicable)

​

Caching Images Across Hosts

• Faster VM deployment (no download wait)
• Reduces network bandwidth during deployments
• Ensures consistency across hosts

Cache images on all hosts:

Verify cached image:

Cache multiple images:

ansible-playbook -i dev/inventory pull_image.yml \ -e "remote_image_name=registry.example.com/citrix-vda/sonoma-finance:latest"

Remove old image versions to free space:

​

Version control and rollback

​

Version numbering scheme:

• v1.0.0 - Initial release
• v1.1.0 - Added new application
• v1.1.1 - Security patch
• v2.0.0 - Major update (macOS version upgrade)

​

User assignment and policies

​

Working with Citrix Delivery Groups

​

Create a new Delivery Group

1. Navigate to Citrix Cloud Console → Delivery Groups → Create New Delivery Group
2. Select machines by choosing the Machine Catalog containing the new VMs created in the previous step(s)
3. Add users by clicking “Add”, searching for the specified team, and selecting the correct AD/Azure AD group. Alternatively, you can add users individually.
4. To configure desktops, give them a display name (e.g. “MacOS Marketing Desktop”) and add a description for the VM.
5. Choose ‘Add Desktop’ as the Delivery Type

​

Modify existing Delivery Groups

1. Delivery Groups → Select group → Edit
2. Users tab → Add → Search for the selected user → Assign

1. Delivery Groups → Select group → Edit
2. Users tab → Select user → Remove

​

Assignment types:

Static (dedicated):

• Each user is assigned permanently to a specific VM
• The VM retains the user’s settings, files (if they are stored locally)
• Best used for: Developers, power users

Pooled (random):

• User gets the next available VM
• The VM resets to golden image after logout
• Best used for: Individual task workers and call centers

Change assignment type:

1. Create new a Delivery Group with the desired assignment type
2. Migrate your users to the new group
3. Delete the old Delivery Group

​

Access Control and Entitlements

​

User entitlements:

Grant access:

• Assign the user to a Delivery Group (as shown above)
• The user sees the assigned desktop in Citrix Workspace immediately

Revoke access:

• Remove the user from a Delivery Group
• The desktop disappears from the user’s Workspace within 5 minutes

Conditional access:

1. Citrix Cloud Console → Web Studio → Policies
2. Create a new policy, or edit an existing policy
3. Configure conditions:

 * Device type: macOS, iOS, web only

 * Network location: Internal network only, or allow external network

 * Device compliance: Require managed device (if using MDM)

​

Multi-factor authentication (MFA):

• Require MFA for Citrix Workspace access
• Users will be prompted for a second factor during login

​

Session Policies and Preferences

Session timeout:

1. Navigate to Citrix Cloud Console → Web Studio → Policies
2. Edit the policy for the necessary Delivery Group
3. Configure session settings:

 * Session idle timeout: Disconnect after X hours idle (default: 24 hours)

 * Disconnected session timeout: Log off user(s) after X hours disconnected (default: never)

• Pooled desktops: 8 hours idle, 30 minutes disconnected (aggressive cleanup)
• Dedicated desktops: 24 hours idle, never disconnect (preserve work)

Reconnection:

• Policy → Session → Connection → Enable “Session reconnection”
• When users close Workspace without logging out, their session is preserved
• When users reopen their Workspace, they can reconnect to same session

​

Feature policies (HDX settings):

Clipboard:

• Bidirectional: Copy/paste both ways (client ↔ VM)
• Client to VM only: Users can paste into the VM, but not copy out
• Disabled: No clipboard access

1. Policies → HDX Settings → Clipboard redirection
2. Select: Allowed / Prohibited / Client to VM only

File transfer:

• Allow: Users can drag files between client and VM
• Prohibit: No file transfers are allowed

1. Policies → HDX Settings → Client drive redirection
2. Select: Allowed / Prohibited

USB redirection:

• Allow specific devices: Keyboards, mice, smart cards
• Prohibit all: Block USB entirely

1. Policies → HDX Settings → USB device redirection
2. Select device classes allowed

Printing:

• Client printer mapping: The user’s local printers appear in the VM
• Disable: No printing

1. Policies → Printing → Client printer redirection
2. Select: Allowed / Prohibited

Example policy set (Finance team - secure):

• Clipboard: Client to VM only (prevent data exfiltration)
• File transfer: Prohibited
• USB: Prohibited
• Printing: Allowed
• Session timeout: 8 hours idle

Example policy set (Engineering team - open):

• Clipboard: Bidirectional
• File transfer: Allowed
• USB: Allowed (specific devices)
• Printing: Allowed
• Session timeout: 24 hours idle

Apply policies to a specific Delivery Group:

1. Create a policy with the desired settings configured
2. In Citrix Cloud Console, navigate to Policies → Filter → Set filter to Delivery Group name
3. The chosen policy applies to all users in that group

​

Lifecycle operations

Start a VM: ansible-playbook -i dev/inventory vm.yml -e "vm_name=webapp-abc123" -e "desired_state=running"

Stop a VM: ansible-playbook -i dev/inventory vm.yml -e "vm_name=webapp-abc123" -e "desired_state=stopped"

Delete a single VM: ansible-playbook -i dev/inventory vm.yml -e "vm_name=webapp-abc123" -e "desired_state=absent"

1. Navigate to Citrix Cloud Console → Delivery Groups → Select group
2. Edit → Users tab → Remove user

​

VM cleanup task checklist:

1. Remove User from the Citrix Delivery Group
2. Delete the VM from Orka
3. Archive User data (if necessary)
4. Update capacity tracking spreadsheet/software
5. Confirm that the VM has been removed from the Machine Catalog in Citrix

​

Monitoring and Troubleshooting

​

Key metrics to watch:

Check daily:

1. VM registration status. Check this by navigating to Citrix Cloud Console → Monitor → Machine Catalogs. You will want to look for:

 1. Unregistered Machines: Should be 0

 2. Power state “Off”: Investigate why VMs are powered off

 3. Faults: Any VM faults which require attention

2. Session launch success rate. Check this by navigating to Citrix Cloud Console → Monitor → User Activity.

 1. Target: >95% success rate.

 2. If Users Activity is <95%: Review failed connection attempts, identify any patterns to help determine the cause (specific users, times issues occure, VMs impacted)

3. Host capacity. This can be checked by running: ansible-playbook -i dev/inventory list.ymland verifying:

 1. Host capacity: Check and confirm there are no hosts at 2/2 VM capacity.

 2. Confirm disk space is >85%

 3. If yes, plan for disk expansion or cleanup.

Check weekly:

1. Performance trends. You can review these by navigating to Citrix Cloud Console → Monitor → Trends. Review the following:

 1. Average session launch time (target: <30 seconds)

 2. Session quality (should be "Good" or "Excellent")

 3. Peak concurrent users (plan capacity for 20% growth)

2. Host health can be verified by confirming available disk space using: ansible hosts -i dev/inventory -m shell -a "df -h /var/orka"

 1. Check for any errors in the Orka logs: `ansible hosts -i dev/inventory -m shell \ -a "sudo grep -i error /var/log/orka-engine.log | tail -20"`

3. Image currency

 1. Are VMs running the latest golden image version?

 2. Are there any security patches pending?

 3. If yes, schedule any updates that are needed and communicate any downtime to Users.

Check monthly:

1. Capacity planning

 1. Confirm your current VM count vs. your total VM capacity

 2. Calculate anticipated user growth trends

 3. Use these calculations to help determine your projected need for additional hosts

2. User feedback

 1. Are there any session quality complaints? If so, what are they, and are there any trends to surface? Track these in an internal spreadsheet or other tool for additional sentiment analysis.

 2. Application performance issues

 3. Feature requests or service improvements

3. Security review

 1. Verify if enrollment tokens been rotated in the last 90 days

 2. Confirm SSH keys are up-to-date

 3. Review audit logs

4. Alert thresholds

 1. Set up relevant monitoring alerts via email/Slack/Teams/etc.

 2. Confirm which alerts require immediate response (Critical)

    1. VDA registration drops below 80% of expected targets

    2. All VMs in a Delivery Group are unavailable

    3. Host disk space >90%

 3. Confirm which alerts require a response within 4 hours:

    1. >10% of sessions launched fail over 15 minutes

    2. Host CPU sustained usage >80% for 30 minutes

    3. Available disk space >75%

 4. If session launch time exceeds baseline by 50%, or a new “Unregistered” VM appears, review this information daily.

​

Common issues and resolutions

VM deployed, but is not registered in Citrix:

• The VM appears in the list.yml output
• The Citrix Machine Catalog shows no new VM
• Desktop is not available in Workspace

1. Check the VDA service is running: ansible mac_vms -i dev/inventory -m shell \ -a "sudo launchctl list | grep citrix" --limit 10.0.100.10

2. Check enrollment token:

 * Citrix Cloud → Machine Catalogs → Enrollment Token

 * Verify that the token is not expired

 * If the token is expired: Generate new a enrollment token, update Ansible Vault, and redeploy the VM

3. Check the Citrix VDA logs:

4. Test network connectivity:

Issue: Session launch timeout

• User clicks on the desktop in their Citrix Workspace
• A connection progress bar appears
• The session eventually times out with a “Cannot connect” error

1. Verify the the VM is powered on:

2. Confirm the Citrix Machine Catalog shows that the VM is both “Registered” and “Available”
3. Test Rendezvous connectivity:

4. Verify that the firewall allows HDX ports (1494, 2598)
5. Try a different client device to isolate if the problem is a client-side vs. server-side issue

Issue: Disk space full on Orka host

• VM deployment fails with “insufficient space” error
• Host disk usage >90%

1. Check disk usage:

2. List images on the Orka host:

3. Remove old image versions:

4. If inventory is still low: Move VMs to other hosts, expand storage, or add new host(s)

​

Log Locations

​

Orka Engine logs:

• Location: /var/log/orka-engine.log
• View: sudo tail -100 /var/log/orka-engine.log
• Contains: VM lifecycle events, image operations, errors

​

Citrix VDA logs:

• Location: /Library/Application Support/Citrix/VDA/Logs/
• Key files:

* `vda.log` \- Main VDA service log

* `registration.log` \- Registration events

* `broker.log` \- Communication with Citrix Cloud

• View: sudo tail -100 /Library/Application\ Support/Citrix/VDA/Logs/vda.log

​

System logs:

• Location: /var/log/system.log
• View: sudo tail -100 /var/log/system.log
• Contains: macOS system events, service crashes

​

Ansible logs:

• Location: Playbook output (stdout)
• Verbose mode: Add -vvv to playbook command
• Example: ansible-playbook -i dev/inventory deploy.yml -vvv

​

Centralized logging (if configured):

• Check your logging infrastructure (Splunk, ELK, CloudWatch)
• Search by hostname, VM name, or error keywords

​

When to Escalate to MacStadium Support

• The Orka Engine service crashes repeatedly
• If you are unable to deploy VMs after following the documented troubleshooting steps
• You suspect hardware failure (host unresponsive)
• Image operations fail consistently
• You need guidance on capacity planning or architecture changes

• The problem description and its symptoms/potential root causes. If you have noticed any trends or patterns when the issue occurs, provide this information as well.
• The steps you have already taken to troubleshoot the issue
• Relevant log excerpts (Orka Engine, VDA)
• Output of any diagnostic commands you have run
• Timeline of the issue (when it started, issue frequency)

• Support Portal: MacStadium
• Include: Account ID, affected host IPs, error messages
• Attach: Log files, screenshots if helpful

• Severity 1 (production down): 1 hour
• Severity 2 (degraded service): 4 hours
• Severity 3 (question/guidance): 24 hours

​

Security and Compliance

​

Network Isolation Best Practices

VLAN segmentation:

• Management VLAN: Orka API, Ansible control node (restricted access)
• VM VLAN: Citrix VDA VMs (isolated from management)
• User VLAN: End-user access (if applicable)

​

Firewall rules:

• Inbound: SSH (port 22) from the Ansible control node only
• Inbound: Orka API (port 80/443) from the Ansible control node only
• Outbound: Container registry (port 443)
• Outbound: Internet access for macOS updates (port 80/443)

​

VMs should allow:

• Inbound: HDX (ports 1494, 2598) from the Citrix Gateway Service
• Outbound: Citrix Cloud (port 443 to *.xendesktop.net, *.nssvc.net)
• Outbound: Internet access for application updates

​

Block unnecessary traffic:

• VM-to-VM traffic (unless required by applications)
• VM-to-management-VLAN traffic
• Direct VM-to-Internet (route connections through a company proxy if required by policy)

​

SSH key management

Key rotation schedule:

Generate a new SSH key:

Deploy the new SSH key to your host(s):

Remove old SSH key(s) from a host:

​

SSH key storage

• Store private keys securely
• Never commit private keys to Git
• Limit access to keys (only authorized admins)

​

If a key is compromised

• Generate a new key immediately
• Deploy the new SSH key to all hosts
• Remove the compromised key from all hosts
• Review access logs for unauthorized use
• Document the incident for additional review

​

Audit logging

Citrix:

• Configuration Logging: Tracks changes to Machine Catalogs, Delivery Groups, policies
• Access: Citrix Cloud Console → Configuration → Logging
• Retention period: 90 days (configurable)

Orka:

• Orka Engine logs all VM operations
• Location: /var/log/orka-engine.log
• Retention period: Configure log rotation (default: 30 days)

Ansible:

• Playbook execution logs
• Capture stdout: ansible-playbook ... | tee -a /var/log/ansible-playbook.log
• Include timestamp(s), operator name, and the command(s) executed

​

What to log

• VM provisioning and deprovisioning
• User access grants and revocations
• Policy changes
• Image updates
• Configuration changes

​

Log review

• Weekly: Review logs for any anomalies
• Monthly: Summarize log activity for management
• Quarterly: Audit logs for compliance

​

Data Sovereignty Considerations

VM data:

• Stored on the Orka host local disk (/var/orka)
• A physical location: Your data center (on-premises) or MacStadium data center (hosted)

Images:

• Stored in an OCI registry
• A physical location: Your data center (on-premises) or MacStadium data center (hosted)

User data:

• Within the VM (ephemeral for pooled access, persistent for dedicated access)
• Backup location: Your backup infrastructure

Citrix metadata:

• Stored in Citrix Cloud (US or EU region, depending on account)
• Contains: User assignments, policies, and session logs (no VM content)

​

Compliance considerations

GDPR (European users):

• Ensure Citrix Cloud region is EU
• Document data flows
• Implement data retention policies (delete VMs when a user leaves the organization)

HIPAA (U.S.-based healthcare policy):

• Encrypt data at rest (FileVault on VMs)
• Encrypt data in transit (HDX uses TLS)
• Implement audit logging
• Sign BAA with Citrix

Data residency requirements:

• Deploy Orka hosts in the required geographic region
• Use a container registry located in the same region
• Verify Citrix Cloud region compliance

​

Best practices

​

Image Hygiene and Update Cadence

Monthly:

• Apply macOS security updates to golden images
• Update applications (Office, browsers, etc.)
• Test the updated image thoroughly
• Deploy the image to production

Quarterly:

• Review installed applications (remove any unused applications)
• Update the Citrix VDA to the latest version
• Audit image sizes (optimize if these are >50GB)
• Document any changes made in your CHANGELOG.MD file and push these updates to Git.

Annually:

• Upgrade macOS major version (e.g., Sonoma → Sequoia)
• Review all configuration scripts
• Rebuild images from scratch (vs. doing incremental updates)

Image testing checklist:

1. VM deploys successfully
2. The VDA registers with Citrix
3. All applications launch as expected
4. No errors appear in the VDA logs
5. Test that user(s) can access the desktop
6. Confirm session performance is acceptable

​

Capacity planning

Current capacity formula:

Estimate concurrent users:

Calculate your VM needs:

Determine your host requirement(s):

​

Change management procedures

• Order hosts 60 days before capacity constraint
• Allow 14 days for delivery (if hosted with MacStadium)
• Allow one week for deployment and testing

• VM utilization >75%: Start planning for host expansion
• VM utilization >90%: Expedite new hosts

​

Backup and Disaster Recovery

• Store these in an OCI registry (off-site)
• Maintain at least three recent versions
• Test the golden image VM restoration process quarterly

​

User data (persistent desktops only):

• Do daily backups via Time Machine or an enterprise backup tool
• 30-day retention of user data
• Test data restoration process and procedures monthly

​

Configuration:

• Ansible playbooks and inventory: Store these in a Git repository
• Citrix configuration: Export this monthly via PowerShell
• Documentation: Store this in a company wiki such as Confluence, in Git, or on a shared drive

​

Disaster recovery scenarios:

Scenario 1: Single host failure

• Impact: 2 VMs unavailable
• RTO: 4 hours
• Procedure:

1. Provision a replacement Mac

2. Install Orka Engine on the machine

3. Add the machine to your existing Ansible inventory

4. Pull golden images

5. Deploy VMs to new host from the golden image

Scenario 2: Complete site failure

• Impact: All VMs are unavailable
• RTO: 8-12 hours
• Procedure:

1. Provision Macs at an alternate site (or host these directly with MacStadium)

2. Restore your last known good Ansible configuration from Git

3. Pull images from your OCI registry

4. Deploy new VMs

5. Verify VDA registration in Citrix

Disaster recovery (DR( testing:

• Annually: Conduct a full DR exercise
• Quarterly: Conduct a partial failover test
• Document lessons learned

​

Change Management Procedures

1. Document the change:

• What: Description of the suggested change
• Why: Business justification for making the change
• Impact: Affected systems, users, and any anticipated downtime
• Rollback plan: Steps necessary to revert the change if any issues occur

2. Test in a non-production environment:

• Deploy to a test VM group
• Validate functionality
• Measure performance impact

3. Schedule a change maintenance window:

• Communicate the change to users 1 week in advance
• Choose a low-usage time (evenings, weekends)
• Change duration: 2× expected time (buffer for issues)

4. Execute the change:

• Follow the documented change procedure
• Monitor for any issues
• Validate success criteria has been met
• Communicate change completion

5. Post-change review process:

• Document the actual vs. planned change(s)
• Capture any lessons learned during the change process
• Update change procedure(s) if needed

​

Example change: Update golden image from v1.2 to v2.0

Change request:

• Change: Update finance golden image to v2.0 (adds Microsoft Teams)
• Impact: 50 finance VMs, 200 users
• Downtime: 2 hours (pooled desktops, off-hours)
• Rollback: Revert vm_image to v1.2, redeploy VMs

Test plan:

• Deploy 2 test VMs from v2.0 image
• Validate Microsoft Teams launches correctly
• Test user session quality is acceptable

Change execution plan:

1. Update vm_image in group vars to v2.0
2. Delete any existing VMs: delete.yml (30 min)
3. Deploy the new VMs: deploy.yml (60 min)
4. Verify VDA registration in Citrix (15 min)
5. Test user sessions (15 min)

Change rollback plan (if adverse issues occur):

1. Update the vm_image back to v1.2
2. Delete v2.0 VMs
3. Redeploy VMs from v1.2

Change communication:

• 1 week before scheduled change: “Scheduled maintenance Sunday 2 AM-4 AM, desktops will be unavailable”
• Day of change: “Maintenance is currently in progress, desktops will be available by 4 AM”
• After change is complete: “Maintenance is now complete, Microsoft Teams is now available on finance desktops.”

​

Resources and support

​

Documentation:

MacStadium

• Orka Documentation and Support: MacStadium
• Bare Metal Mac Options: Cloud-hosted Bare Metal Macs | MacStadium

Citrix

• VDA for macOS Documentation: Citrix Virtual Delivery Agent for macOS
• System Requirements: System Requirements | Citrix Virtual Delivery Agent for macOS
• Citrix Cloud Console: https://citrix.cloud.com
• Citrix Support: Loading…

Ansible:

• Ansible Documentation: Ansible Community | Ansible documentation
• Ansible Vault Guide: https://docs.ansible.com/ansible/latest/user_guide/vault.html

​

Support Contact Information

MacStadium Support:

• Portal: MacStadium
• Email: support@macstadium.com
• Phone: Available in support portal
• Hours: 24/7 for Severity 1, business hours for others
• SLA: 1 hour (Sev 1), 4 hours (Sev 2), 24 hours (Sev 3)

• You Account ID
• Affected host IPs or VM names
• Problem description and timeline
• The troubleshooting steps you have already taken
• Log excerpts (Orka Engine, VDA)

Citrix Support:

• Portal: Loading…
• Access via Citrix Cloud Console → Support
• Include: You Customer ID, Machine Catalog name, applicable error messages

​

Citrix community forums:

• Citrix Discussions: https://discussions.citrix.com
• Citrix Community: Deploying Strong Network in Azure Kubernetes