VDI golden image management

​

Golden image lifecycle

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. deploy.yml only deploys the VM: unless the golden image includes the Citrix VDA, run install_citrix_vda.yml, and then run register_citrix_vda.yml for every new VM.
6. Update: Apply patches or new applications, run create_image.yml again with a new version tag, test, then repeat from step 4.

​

Creating a Golden Image with Citrix VDA

​

Golden Image Creation Workflow

​

Create a VM Image

ansible-playbook -i dev/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"

1. Place your configuration scripts (VDA install, etc.) in the scripts/ directory at the root of your orka-engine-orchestration clone
2. The playbook runs every *.sh file directly inside scripts/. It doesn’t sort the scripts, so don’t rely on the order they run in: if one step depends on another, put both in the same script.
3. Example scripts:

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

​

Update a VM to a New Image

# Step 1: Delete the existing VM
ansible-playbook -i dev/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 dev/inventory deploy.yml -e "vm_name=citrix-vda-01" -e "vm_image=registry.example.com/citrix-vda/sonoma-golden:v2.0" -e "network_interface=en0"

​

Cache Management

​

Cache a VM Image

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

​

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.