Ephemeral Castle: Vault Systemd Detail
Level 3 (Detail) — Systemd units and timers for the Vault runtime.
Concept
The Vault runtime on Hetzner uses systemd units for lifecycle management. The original design used Quadlet (Podman-in-systemd), but the .container generator proved unreliable on Podman 4.3.1 (TD-016), forcing a fallback to explicit Type=simple systemd units.
Unit Inventory
lushycorp-vault.service
| Field | Value |
|---|---|
| File | lushycorp-vault.service.j2 |
| Type | simple |
| Purpose | Main Vault container runtime |
| Dependencies | network-online.target |
| Restart | always |
Runs: podman run ... vault server -config=/etc/vault/vault.hcl
vault-local-unseal.service
| Field | Value |
|---|---|
| File | vault-local-unseal.service.j2 |
| Type | oneshot |
| Purpose | Unseal Vault on boot |
| Dependencies | Requires lushycorp-vault.service, 5s wait |
| Restart | no |
Runs: {{ vault_bootstrap_dir }}/vault-local-unseal.sh
vault-snapshot-backup.service
| Field | Value |
|---|---|
| File | vault-snapshot-backup.service.j2 |
| Type | oneshot |
| Purpose | Take and upload Raft snapshot to S3 |
| Depends on | lushycorp-vault.service must be active |
vault-snapshot-backup.timer
| Field | Value |
|---|---|
| File | vault-snapshot-backup.timer.j2 |
| Purpose | Schedule for snapshot backup service |
| Schedule | (configured via defaults) |
vault-remote-restore.service
| Field | Value |
|---|---|
| File | vault-remote-restore.service.j2 |
| Type | oneshot |
| Purpose | Restore Vault from S3 snapshot |
| Used in | C2 restore flow |
Quadlet Issue (TD-016)
The original design used a lushycorp-vault.container.j2 Quadlet file (.container → Podman-generates systemd unit). On Podman 4.3.1 (the current Hetzner golden image), the Quadlet generator produced incorrect units that failed to start the container reliably.
The fallback was an explicit Type=simple systemd unit that calls podman run directly. This bypasses Quadlet but introduces minor technical debt regarding standard Podman service management.
Key Directories
| Path | Purpose |
|---|---|
{{ vault_runtime_root }}/vault.hcl | Vault configuration |
{{ vault_tls_dir }}/ | TLS certs (ca.crt, server.crt, server.key) |
{{ vault_data_dir }}/ | Raft data directory |
{{ vault_bootstrap_dir }}/ | Unseal shares, lifecycle receipt |
See Also
- Detail: Ansible Scripts Detail
- Detail: Ansible Vault Detail
- Debt: TD-016 (Quadlet)
- Hub: Ephemeral Castle