Machine Image Management¶
AWS (AMIs)¶
AMI IDs stored in SSM Parameter Store, built via Packer workflows.
SSM Parameters¶
| Parameter | Purpose |
|---|---|
/shifter/ami/kali |
Kali attacker instance |
/shifter/ami/ubuntu |
Ubuntu victim instance |
/shifter/ami/windows |
Windows victim instance |
/shifter/ami/dc |
Domain Controller instance |
The build workflow publishes each type to /shifter/ami/<type>; the provisioner resolves both the legacy known types and any custom key from that path.
Provisioner fetches AMI IDs at runtime via shifter/engine/provisioner/provisioner_ami.py:get_ami_id().
AMI Types¶
Packer-Built AMIs¶
The kali, ubuntu, and windows AMIs are built from base images using Packer (the build job in packer.yml).
| AMI | Base Image | Build Scripts |
|---|---|---|
| kali | Official Kali AMI | shifter/packer/scripts/kali/ |
| ubuntu | Ubuntu 22.04 | shifter/packer/scripts/ubuntu/ |
| windows | Windows Server 2022 | shifter/packer/scripts/windows/ |
Build configuration: shifter/packer/*.pkr.hcl (one file per type).
External image recipes¶
Pack-specific images and their build pipelines belong to pack authors. Register immutable image artifacts through the supported preparation contract; core image workflows build only platform base images.
Prebaked DC AMI¶
Domain Controller uses a manually created AMI with AD DS already promoted.
| Property | Value |
|---|---|
| Domain | internal.shifter |
| NetBIOS | INTSHIFTER |
| Hostname | Fixed from AMI (typically DC01) |
| AMI IDs | shifter/packer/dc-amis.json |
Critical: The prebaked DC's Administrator password must match the
environment's domain password in AWS Secrets Manager (shifter-{env}-portal-dc-domain).
That secret is Terraform-managed—terraform apply for the portal stack
generates the value (random_password.dc_domain_password in the
portal Terraform root) and seeds it—so the AMI build reads the value
from Secrets Manager rather than choosing one. Victims use the same password
for domain join. The value must never be committed to terraform.tfvars,
workflow YAML, or any other tracked file.
DC AMI is prebaked because runtime promotion adds 15-20 minutes to provisioning. Tradeoffs: - Fixed domain name across all ranges - Fixed hostname (no per-range DC naming) - Password rotation must be coordinated between the AMI and the runtime secret
Workflows¶
Build (Dev)¶
Workflow: .github/workflows/packer.yml
| AMI Type | Action |
|---|---|
| kali, ubuntu, windows | Packer build, fresh-boot SSM/DNS validation gate, then update dev SSM |
| dc | Read the id from dc-amis.json (trusted dev provenance, validated), update dev SSM |
The kali, ubuntu, and windows builds bake a deterministic AmazonProvidedDNS
upstream into the guest (issue #1633) so DNS is race-free from first boot. Before
the build overwrites /shifter/ami/<type>, a validation gate boots the exact
candidate AMI in a range-equivalent subnet and requires it to register with SSM
and resolve the regional SSM endpoint on a fresh boot and after a reboot. A
failed candidate leaves the previous known-good id in place. The gate reads its
subnet, security group, and instance profile from trusted repository Actions
variables (PACKER_VERIFY_*_<ENV>), not dispatch inputs; they are described in
the AWS AMI seeding runbook.
The base build job assumes a dedicated least-privilege image-pipeline IAM role
(github_actions_image in platform/terraform/global/iam, issue #1656), not the
broad deploy role. Its OIDC trust is pinned to the dev/main protected-branch
subjects, and its iam:PassRole is scoped to exactly the
shifter-<env>-range-range-instance role passed to EC2, so the verification
instance can receive only the range role. The role ARN is wired to the
AWS_IMAGE_ROLE_ARN_<ENV> secret (see the runbook cutover); the
check_tf_iam_role_naming guardrail (ADR-004-R22) pins the exact-subject and
exact-range-role invariants. bake-scenario keeps its own separate role.
Promote (Prod)¶
Workflow: .github/workflows/packer-promote.yml
| AMI Type | Action |
|---|---|
| kali, ubuntu, windows | Copy AMI to prod account, update prod SSM |
| dc | Read the id from dc-amis.json (trusted dev provenance, validated), update prod SSM |
packer-promote.yml handles only kali, ubuntu, windows, and dc.
Both DC publishers read dc-amis.json from a dedicated checkout of the protected
dev ref (never the dispatched/build ref or a runner leftover) and resolve it
through one shared validator, shifter/packer/scripts/bake/resolve-dc-ami.sh,
which fails closed unless the id exists, matches the AMI shape, and names an
image EC2 reports as available and owned by the target account. The prod
promote job also runs only from a protected ref (dev/main). See issue #1656.
Updating AMIs¶
- Modify scripts in
shifter/packer/scripts/ - Run "Packer AMI Build" workflow for the type
- Test in dev
- For promotable types (kali, ubuntu, windows), run "Packer AMI Promote to Prod"
Domain Controller¶
- Edit
shifter/packer/dc-amis.jsonwith new AMI ID - Run "Packer AMI Build (Dev)" workflow with
dctype - Test in dev
- Run "Packer AMI Promote to Prod" workflow with
dctype
To create a new DC AMI:
- Launch Windows Server 2022 base AMI
- Install AD DS feature
- Promote to DC with domain
internal.shifter, NetBIOSINTSHIFTER - Set the domain Administrator password to the value already seeded in
shifter-{env}-portal-dc-domain(Terraform-managed; read it from Secrets Manager, do not invent one), seedev/secrets.md - Set the DC's DNS forwarders to the link-local AmazonProvidedDNS so external
names such as the regional SSM endpoint resolve deterministically (issue
#1633):
Set-DnsServerForwarder -IPAddress 169.254.169.253 -PassThru. This is the DC-role equivalent of theFallbackDNSbaked into the Linux guests. Do not reset the DC's adapter to DHCP DNS: a promoted DC points its client at itself and forwards outbound queries, so a DHCP reset would break domain resolution. - Sysprep and create AMI
- Update
dc-amis.json
Important: The Administrator password set during promotion must match the runtime secret referenced by the portal/engine Terraform stack for domain join to work. Keep only non-secret identifiers in Terraform configuration; do not store the password value in environment tfvars.
Related Files (AWS)¶
| File | Purpose |
|---|---|
shifter/packer/dc-amis.json |
DC AMI IDs (version controlled) |
shifter/engine/provisioner/provisioner_ami.py |
get_ami_id() function |
shifter/engine/provisioner/catalog/instances.py |
Instance type definitions |
shifter/engine/provisioner/plans/dc_setup.py |
DC verification (no promotion step) |
GCP¶
GCP keeps four distinct image concepts separate (do not conflate them with AWS AMIs):
GCE guest images (Packer)¶
Compute Engine guest images are built with Packer, parallel to the AWS AMI flow
(issue #505, PLAT-001.10). They are not AMIs and their refs are never
stored in AWS SSM /shifter/ami/*.
- Templates:
shifter/packer/gcp/*.pkr.hcl(googlecomputebuilders), a separate Packer configuration from the AWSamazon-ebstemplates one directory up—packerinvoked in either directory never sees the other. - Version pointer = the release manifest. Each build creates image
shifter-<type>-<timestamp>in the developer build project. Each release names the newest verified publication of each role, and the deploy imports those images into the range project (the GCP analog of the AWS SSM parameter). - Build:
.github/workflows/packer-gcp.yml(workflow_dispatch,ubuntu-latest+ purpose-scoped Workload Identity Federation into the developer build project). It calls.github/workflows/packer-gcp-validate.ymlfor the exact candidate. Only after validation passes, it publishes the image to the release registry with signed build provenance (#2668). No promotion step exists. - Image types:
ubuntu,kali,dc-prebaked(published asdc). Kali has no public GCP image and the official genericcloud disk is not GCE-bootable, so its builder converts Google'sdebian-12base into Kali Rolling in its first provisioning script; seeshifter/packer/gcp/README.md. - Agent trigger: the
build_gce_imageMCP ops tool (infra_mutation), parallel tobuild_ami.
Guest specialization that is AWS-specific in the shared provisioning scripts (the SSM agent; Claude Code's Bedrock binding) is a guest-runtime / range concern tracked separately from this image-build pipeline.
Other GCP image concepts (unchanged)¶
- GDC VM Runtime - OS images stored in GCS, imported as
VirtualMachineDiskCRDs. Image URLs configured inGDCVMRuntimeConfig(GDC_*_IMAGE_URL). - Scenario Pods - Standard container images from Artifact Registry.
- VM-Series NGFW - OVA image stored in GCS, bootstrapped via GCS bucket.
- Control-plane containers - Built once for each release by
release-gcp.ymland pushed to the release registry;gcp-deploycopies them into the deployment Artifact Registry. A CI deploy through_gcp-dev.ymlbuilds them directly into the deployment Artifact Registry.
See GDC Provisioning for details.