Skip to main content
Image management is critical for maintaining a scalable MacStadium VDI environment. This page covers creating a golden image with Citrix VDA pre-installed, automating image builds, distributing images across hosts, and version control practices for long-term maintenance.

​
Golden image lifecycle

Every VM in your fleet is deployed from a golden image, a versioned snapshot of macOS with Citrix VDA and your organization’s applications pre-installed. The lifecycle repeats with each update cycle: Golden image lifecycle diagram
  1. Base image: Start from a MacStadium public base image (ghcr.io/macstadium/orka-images/sequoia:latest or similar).
  2. Build: Run create_image.yml: it deploys a temporary VM, executes your scripts in the /scripts directory, commits the result, pushes the image to your OCI registry, and cleans up.
  3. Version: Tag the image with a version (v1.0, v1.1, etc.) before pushing to your registry. Tag as :latest once validated.
  4. Cache: Run pull_image.yml to pre-pull the image to all hosts. This avoids download delays at deployment time.
  5. Deploy: Run deploy.yml to provision VMs from the cached image. VMs are ready for Citrix VDA registration immediately.
  6. Update: Apply patches or new applications, run create_image.yml again with a new version tag, test, then repeat from step 4.
Run all playbooks from the management UI for day-to-day image operations. See Getting Started: MSDC-Hosted or Getting Started: Self-Hosted for setup instructions.

​
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_name=citrix-vda-01" -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? (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.