Ephemeral Castle: Vault Ansible Scripts Detail

Level 3 (Detail) — The 4 shell scripts executed by the vault-runtime Ansible role.

vault-phase-a-bootstrap.sh

Purpose: First initialization of the Vault instance.

Location: ansible/roles/vault-runtime/files/vault-phase-a-bootstrap.sh

Behavior:

  1. Creates a staging workdir on the host
  2. Initializes Vault via vault operator init -format=json (2-of-3 Shamir)
  3. Extracts unseal keys and root token
  4. Unseals Vault using 2 unseal shares
  5. Logs in with root token
  6. Creates admin policy
  7. Creates admin token with the admin policy
  8. Writes lifecycle receipt JSON with lineage ID
  9. All artifacts written to the staging workdir for Ansible to collect

Arguments:

ArgDescription
$1Staging workdir path
$2Structured log file path

Environment: CONTAINER_NAME, VAULT_ADDR, VAULT_CACERT, VAULT_TLS_SERVER_NAME, POLICY_NAME, TOKEN_ROLE, HOST_IDENTITY, SERVICE_IDENTITY, SCHEMA_VERSION, ORIGIN_TYPE, SECRET_SHARES, SECRET_THRESHOLD

vault-local-unseal.sh

Purpose: Automated Vault unseal using 2 of 3 Shamir shares.

Location: ansible/roles/vault-runtime/files/vault-local-unseal.sh

Behavior:

  1. Reads unseal share 1 and 2 from {{ vault_bootstrap_dir }}/
  2. Calls vault operator unseal for each share via podman exec
  3. Verifies Vault status after unseal

Called by: vault-local-unseal.service on system start, and explicitly after Ansible convergence.

vault-snapshot-backup.sh

Purpose: Scheduled S3 snapshot backup.

Location: ansible/roles/vault-runtime/files/vault-snapshot-backup.sh

Behavior:

  1. Takes a Raft snapshot: vault operator raft snapshot save
  2. Uploads to S3 with lineage-aware naming
  3. Rotates between slot-a and slot-b
  4. Updates latest.json pointer

Called by: vault-snapshot-backup.timer (scheduled, no explicit schedule in defaults).

vault-remote-restore.sh

Purpose: Restore Vault from S3 snapshot.

Location: ansible/roles/vault-runtime/files/vault-remote-restore.sh

Behavior:

  1. Reads S3 lineage pointer
  2. Downloads the latest snapshot
  3. Starts a temporary Vault instance
  4. Executes vault operator raft snapshot restore
  5. Restarts Vault with the restored data

Called by: vault-remote-restore.service during restore flow.

Supporting Scripts

render-tailscale-inventory.sh

Location: scripts/render-tailscale-inventory.sh

Purpose: Generates inventory.tailscale.ini with Tailscale IPs for Ansible transport switch.

Behavior:

  1. Resolves the tailnet IP for the target hostname (lushycorp-vault) via Tailscale API or tailscale ip
  2. Writes ansible/inventory.tailscale.ini with the resolved IP
  3. Used in create.sh Phase 4 (Transport Switch)

Arguments: --hostname (required), --output (required)

validate-device-tags.sh

Location: scripts/validate-device-tags.sh

Purpose: Confirms that a Tailscale device has the expected tags.

Behavior:

  1. Queries Tailscale API for device by hostname
  2. Checks that device has all required tags
  3. Outputs validation JSON to configs/tailscale-tags.json

Arguments: --hostname (required), --required-tags (required), --output (required)

See Also