> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# VDI golden image management

> Create and manage golden images for MacStadium VDI: build images with Citrix VDA pre-installed, automate builds with Ansible, and distribute across hosts.

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:

<img src="https://mintcdn.com/macstadiuminc/0YsMQFLUbXS5qwex/images/image-lifecycle.svg?fit=max&auto=format&n=0YsMQFLUbXS5qwex&q=85&s=5a614a3ad20727def715f89af34ec878" alt="Golden image lifecycle diagram" width="1400" height="525" data-path="images/image-lifecycle.svg" />

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.

<Tip>
  Run all playbooks from the management UI for day-to-day image operations. See [Getting Started: MSDC-Hosted](/remote-desktop-vdi/getting-started/msdc-hosted) or [Getting Started: Self-Hosted](/remote-desktop-vdi/getting-started/self-hosted) for setup instructions.
</Tip>

## 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](https://semver.org/) 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.