Skip to content

Test VM

Create, use, and clean up self-service Ansible test VMs — throwaway EC2 machines that playbooks run against, provisioned per developer via the aws-test-vm Coder template.

Invoke by asking Claude (e.g. "spin up a RHEL 9 test box for the firewalld role") or with /test-vm. Covers RHEL 9, Ubuntu 24.04, and Windows Server 2022/2025.

When to use

Reach for it whenever you need a clean machine to run a role or playbook against — validating a change, reproducing a customer issue, or checking a role behaves on a fresh host rather than one already shaped by earlier runs. For repeatable role testing (rather than an ad-hoc box) use Molecule instead; these VMs are for interactive, one-off work.

What it does

One Coder workspace = one EC2 VM (agent-optional target, not a dev workspace). The skill picks parameters to match what you're testing, creates the workspace, and hands back the inventory hostname and IP. Key choices:

  • OS: rhel9 (matches the managed fleet), ubuntu24, windows2022, windows2025.
  • Size: defaults to the smallest that fits — t3.medium for Linux, t3.large for Windows — bigger only for a stated reason (e.g. IRIS OLTP needs ~9 GB shared memory).
  • Data disks: production-shaped map for roles that manage their own storage.
  • Windows domain join: on by default, so the VM is Kerberos-capable like the fleet; it skips gracefully when the nightly-rebuilt dev directory is down.

The VM's Name tag becomes its dynamic-inventory hostname (<name>.sapphire.dev) automatically — no inventory edits.

Running playbooks against it

  • Linux — fleet SSH key, AMI default user (ec2-user on RHEL, ubuntu on Ubuntu): ansible-playbook --limit <name>.sapphire.dev -u ec2-user playbooks/<name>.yml.
  • Windows — workgroup or domain-joined; WinRM via psrp. The shared test-VM admin password is sensitive — Claude will ask you for it rather than fetch or store it.
  • No public IP by design. Roles that download from the internet need the squid proxy extra-vars (-e @extra_vars/proxy.yml) — a role that only works with direct egress is a bug this setup catches. (To learn a role's exact egress, see Internet Requirements.)
  • No UI terminal / coder ssh to test VMs (a DERP-vs-proxy limitation) — shell in by SSH from a dev workspace (Linux) or WinRM/RDP (Windows).

Lifecycle & cleanup

  • Autostop after 8h; coder start resumes with all playbook-applied state intact (the instance stops, disks persist).
  • Stop when done for the day; delete when the experiment is over — stale boxes give confusing results. Reset-to-clean = delete + recreate (~2 min).
  • Instance type and disks resize across a stop/start (disks grow-only); changing the OS replaces the VM.

Reference

User-facing details and the full lifecycle: Self-Service Test VMs. Template internals (tagging, domain join, networking): coder/aws/test-vm/CLAUDE.md.