Skip to main content
On April 20th, 2026, we're moving to a new docs site docs.macstadium.com, head there for the most current documentation.
  1. MacStadium
  2. Remote Desktop (VDI)
  3. Orka for VDI Deployment

Image Management

Image management is critical for maintaining a scalable Orka for VDI environment. This section covers creating a golden image with the Citrix VDA pre-installed, automating image builds, distributing images across hosts, and implementing version control practices for long-term maintenance. Your Orka for VDI deployment may use a non-Citrix solution.

Creating a golden image with Citrix VDA

Golden images serve as templates for rapid VM deployment. A well-crafted golden image contains the base OS, Citrix VDA, and any additional software your users need, all pre-configured and ready to deploy. VMs that are deployed from a golden image are ready for immediate use, with no additional setup required.

Golden image creation workflow

Create a VM 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/citrix-vda/sonoma-golden:v1.0"

Before running:

1. Place your configuration scripts (VDA install, etc.) in the /scripts directory

2. Scripts will be executed in alphabetical order

3. Example scripts:

scripts=(
  01_install_dotnet.sh
  02_install_citrix_vda.sh
  03_configure_system.sh
)

Update a VM to a New Image

This implementation doesn’t have a dedicated playbook. To refresh VMs with a new image:

# Step 1: Delete the existing VM
ansible-playbook -i inventory vm.yml -e "vm_name=citrix-vda-abc123" -e "desired_state=absent"

# Step 2: Deploy a replacement VM from the new image version 
ansible-playbook -i inventory deploy.yml -e "vm_group=citrix-vda" -e "desired_vms=1" -e "vm_image=registry.example.com/citrix-vda/sonoma-golden:v2.0"

Cache management

Cache a VM Image 

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

Note: pull_image.yml automatically caches the image on all hosts in the inventory.

Version control best practices

  1. Monitor image cache status

  2. Remove outdated images when new versions are released

  3. Establish proper version control for images, using semantic versioning for image tags and naming conventions

  4. Maintain multiple image tags for flexibility

  5. Maintain a CHANGELOG.MD or detailed README.MD file documenting changes for each released version of an image

  6. Commit changes before building VM images, tagging releases in Git to match the image version

  7. If problems arise with a new image, roll back to a previous version

  8. Define your image retention policy by addressing the following questions:

    1. How long will you keep old image versions?

    2. Which images will you always want to retain for rollback purposes?

    3. When will you delete older image versions to free space if needed?

    4. Will you store major image versions indefinitely? (This is strongly recommended for auditing/compliance)

    5. When will you delete images tagged as dev/staging?

  9. Test before promoting images to production

  10. Communicate image updates

    1. Notify all impacted stakeholders about updates to VM images

    2. Announce new versions as needed in team channels

    3. Document breaking changes

    4. Schedule production deployments to take place during maintenance windows

    5. Before updating an image, provide stakeholders with a rollback plan

Was this article helpful?