HashiCorp Vault + Laravel: Architecture Layers, Methodologies, and Production Parameters

95 min read

Published December 15, 2025 · Revised 30 August 2026 (Vault 1.17 lab; Vault 1.19+ token-file reference, Traefik v3.2, Laravel 10+)

Single-node Vault behind Traefik, AppRole, KV v2, and a Laravel app that loads secrets before the database connection resolves — plus every layer, methodology, and parameter you need to choose the right pattern and not copy the wrong one.

If you have ever committed a .env file by accident, rotated an API key at 2 a.m., or wondered why production secrets live next to your APP_DEBUG flag — this guide is for you.

The lab path is unchanged: stand up a single-node HashiCorp Vault behind Traefik, expose it over HTTPS, and wire Laravel so secrets stop living in plain text on disk. Around that path, this revision documents the architecture layers, the methodologies (auth, seal, storage, secret delivery) with working implementations, and what each parameter does, what the default is, and how you should set it.

Part 1 — Architecture layers (host to Laravel bootstrap)

Vault is not “a password file with an HTTP API.” It is a stack. A misconfigured cluster_addr, a policy on the CLI path instead of the API path, or a secret loaded in boot() instead of register() are all layer mistakes. If you skip this part, the copy-paste lab still works — until the first restart, the first 403, or the first MySQL connection that used an empty password.

The stack, top to bottom

Namespaces (X-Vault-Namespace) are a Vault Enterprise / HCP feature. Open-source Vault has a single namespace: root. Do not set a namespace header on OSS — login will fail with a namespace error, not a useful “wrong path” message.

What happens on one Laravel request

1. PHP-FPM (or Octane worker) starts or reuses a process. Service providers run register() then boot().
2. If you implemented the pattern in Part 12, register() calls Vault POST /v1/auth/approle/login with Role ID + Secret ID and receives a client token (unless a token is already in process memory).
3. Laravel sends GET /v1/secret/data/laravel/app with header X-Vault-Token.
4. Vault checks seal → token validity → policy on that exact API path → KV engine → returns JSON data.data.
5. Config::set('database.connections.mysql.password', …) runs before any provider opens MySQL.
6. Later in the same request, Eloquent uses the in-memory config. Changing Vault after the first connection in that process does not rewrite an already-open PDO handle.

Part 2 — Methodologies: pick, then implement

A “methodology” here is a complete pattern, not a brand name. Combining the wrong two (for example Kubernetes auth on Docker Compose, or file storage with three Vault containers) looks like a Vault bug. It is a topology bug.

Storage backends

Storage is the disk (or cluster) that holds encrypted Vault data. Vault never writes plaintext secrets to the backend. Losing storage loses ciphertext; losing the Shamir shares or original auto-seal key/dependency loses the ability to decrypt it.

Minimal Raft stanza (not used in the lab; shown so you know the upgrade shape):

storage "raft" {
  path    = "/vault/data"
  node_id = "vault-1"
}

listener "tcp" {
  address         = "0.0.0.0:8200"
  cluster_address = "0.0.0.0:8201"
  tls_disable     = 1
}

api_addr     = "https://vault.example.com"
cluster_addr = "http://vault-1:8201"

On Raft you snapshot with vault operator raft snapshot save. On file storage you snapshot the volume (Part 13) — there is no Raft snapshot API.

Seal / unseal

At process start Vault begins sealed: storage is readable as ciphertext, but secret APIs refuse work. Shamir waits for operators to reconstruct the unseal key; an auto seal immediately asks its external seal service to unwrap the root key and normally becomes ready without human input.

Scripted Shamir unseal (keys in a file on disk) is not auto-unseal. It is Shamir with a worse custody story: anyone who can read that file unseals Vault. If you automate, prefer KMS or at least a hardware/offline split (three people, three keys).

Authentication for machines and humans

Auth is how a client gets a token. The token then hits policies. Laravel should never authenticate as root.

Secret delivery into Laravel

Auth answers “who is this process?” Injection answers “how do PHP processes learn DB_PASSWORD?”

Part 3 — Prerequisites and the VAULT_ADDR matrix

Vault holds secrets. Traefik terminates TLS for browsers and host clients. Laravel authenticates with AppRole and reads secrets at runtime — never with the root token.

Two paths to the same Vault listener:

1. Browser / Laravel on the host
   https://vault.example.com → Traefik (TLS) → http://vault:8200 inside Docker
2. Laravel in the same Compose network
   http://vault:8200 directly — no Traefik, no TLS on the bridge

Prerequisites:

• Docker and Docker Compose
• A domain (e.g. vault.example.com) with DNS pointing to your server
• Ports 80 and 443 open on the host for Traefik (lab defaults — not a production port map)
• Laravel 10+ (local or on the same server)

Dedicated Vault host vs Laravel production host

In production, Vault and Laravel often run on different machines. Vault holds ciphertext and the unseal dependency; Laravel holds the application. Treat them as separate failure domains with explicit network policy — not “same Compose stack on one VM.”

Firewall rules (public Vault): allow 443 (Traefik) only from Laravel’s outbound IP(s) and operator VPN — not 0.0.0.0/0. Vault’s Docker listener on 8200 must not be published to the internet; Traefik is the only edge. For Agent on the Laravel host, the Agent container needs the same egress path PHP would use.

TLS: On a private network you may terminate TLS on Traefik with an internal CA, or use plain HTTP only if the path is provably isolated (many teams still use TLS on private links). Laravel sets VAULT_VERIFY_TLS=true and mounts the internal CA when using HTTPS.

Create the project folder:

mkdir vault-stack && cd vault-stack
mkdir -p vault/config vault/policies

Part 4 — Vault configuration (config.hcl) and every server parameter

Create a single file at vault/config/config.hcl (one file only — do not drop extra *.hcl / *.json next to it):

ui            = true
disable_mlock = true

storage "file" {
  path = "/vault/file"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = 1
}

# Public URL — Traefik terminates TLS; used for UI redirects and external clients
api_addr     = "https://vault.example.com"

# Internal cluster port — MUST match listener scheme (HTTP, not HTTPS)
# Single-node: loopback on the cluster port (8201 by convention)
cluster_addr = "http://127.0.0.1:8201"

log_level = "info"

Why cluster_addr must not be the public HTTPS URL

When tls_disable = 1, Vault listens on plain HTTP. Setting cluster_addr = "https://vault.example.com" tells Vault nodes to talk to each other over HTTPS on a port that only speaks HTTP — cluster RPC fails silently or logs TLS handshake errors.

IPC_LOCK and disable_mlock in Docker

Vault normally calls mlock() to prevent secrets from being swapped to disk. Docker containers often lack the capability to lock memory. The fix is twofold:

• cap_add: [IPC_LOCK] in Compose — grants the capability when the kernel allows it
• disable_mlock = true in config.hcl — prevents startup failure when mlock still cannot succeed inside the container

Production trade-off: Without mlock, sensitive memory can be swapped. Mitigate with encrypted volumes, tight host access, and short-lived AppRole tokens — not a root token in Laravel.

Listener, TTL, logging — what each knob does

The file above is the lab minimum. Below is every parameter that actually matters on this stack: what it does, default if omitted, what goes wrong, how to set it.

Optional production stanza you can add later (not required for Laravel):

# default_lease_ttl = "768h"
# max_lease_ttl     = "768h"
# log_format        = "json"

# telemetry {
#   prometheus_retention_time = "30s"
#   disable_hostname          = true
# }

Prometheus telemetry is off unless you enable a telemetry block (and scrape the metrics endpoint with an appropriate listener/policy). Skip it until Vault is unsealed and Laravel reads secrets.

Part 5 — Docker Compose with Traefik labels and healthcheck

Create the shared edge network once (Traefik and Vault both attach to it):

docker network create edge

Optional dynamic Traefik file (HTTP → HTTPS redirect middleware referenced as https-redirect@file):

http:
  middlewares:
    https-redirect:
      redirectScheme:
        scheme: https
        permanent: true

Full docker-compose.yml (template — replace emails, tokens, hosts, and allowlists with your own; do not commit real secrets):

services:
  traefik:
    image: traefik:v3.2
    container_name: traefik
    hostname: traefik
    restart: always
    environment:
      # DNS challenge credentials — use placeholders or a secrets manager, never real tokens in git
      - CLOUDFLARE_EMAIL=you@example.com
      - CF_DNS_API_TOKEN=replace-with-your-dns-api-token
    command:
      - --log.level=ERROR
      - --log.format=json
      - --api.dashboard=true
      - --api=true
      - --api.insecure=true
      - --ping=true
      - --accesslog=true
      - --accesslog.fields.names.StartUTC=drop
      - --accesslog.bufferingsize=250
      - --providers.file.directory=/dynamic
      - --providers.file.watch=true
      - --providers.docker.endpoint=unix:///var/run/docker.sock
      - --providers.docker.exposedbydefault=false
      - --providers.docker.network=edge
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443
      - --certificatesresolvers.le.acme.dnschallenge=true
      - --certificatesresolvers.le.acme.dnschallenge.provider=cloudflare
      - --certificatesresolvers.le.acme.email=admin@example.com
      - --certificatesresolvers.le.acme.storage=/acme/acme.json
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik/dynamic:/dynamic:ro
      - traefik_acme:/acme
      - ./traefik/usersfile:/usersfile:ro
    healthcheck:
      test: ["CMD", "traefik", "healthcheck", "--ping"]
      interval: 5s
      timeout: 5s
      retries: 3
      start_period: 5s
    labels:
      - traefik.enable=true
      - traefik.docker.network=edge
      - traefik.http.middlewares.web-auth.basicauth.usersfile=/usersfile
      - traefik.http.middlewares.ip-whitelist.ipwhitelist.sourcerange=203.0.113.0/24,198.51.100.10
      - traefik.http.routers.traefik.entrypoints=web
      - traefik.http.routers.traefik.middlewares=https-redirect@file
      - traefik.http.routers.traefik.service=api@internal
      - traefik.http.routers.traefik-secure.entrypoints=websecure
      - traefik.http.routers.traefik-secure.rule=Host(`traefik.example.com`)
      - traefik.http.routers.traefik-secure.tls=true
      - traefik.http.routers.traefik-secure.tls.options=default
      - traefik.http.routers.traefik-secure.middlewares=web-auth@docker,ip-whitelist@docker
      - traefik.http.routers.traefik-secure.tls.certresolver=le
      - traefik.http.routers.traefik-secure.service=api@internal
    networks:
      - edge

  vault:
    image: hashicorp/vault:1.17
    container_name: vault
    restart: unless-stopped
    cap_add:
      - IPC_LOCK
    volumes:
      # Mount a directory that contains ONE config file only
      - ./vault/config:/vault/config:ro
      - vault_data:/vault/file
    # Point at the single file — do NOT pass the directory (avoids dual-config / port bind)
    entrypoint: ["vault", "server", "-config=/vault/config/config.hcl"]
    environment:
      # In-container CLI + healthcheck — NOT the public HTTPS URL
      VAULT_ADDR: "http://127.0.0.1:8200"
      VAULT_API_ADDR: "https://vault.example.com"
    healthcheck:
      # 0 = unsealed, 2 = sealed/uninitialized (API up). Traefik skips unhealthy backends.
      test: ["CMD-SHELL", "vault status >/dev/null 2>&1; ec=$$?; [ $$ec -eq 0 ] || [ $$ec -eq 2 ]"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 15s
    networks:
      - edge
    labels:
      - traefik.enable=true
      - traefik.docker.network=edge
      # HTTP → redirect middleware from file provider
      - traefik.http.routers.vault.entrypoints=web
      - traefik.http.routers.vault.rule=Host(`vault.example.com`)
      - traefik.http.routers.vault.middlewares=https-redirect@file
      - traefik.http.routers.vault.service=vault-secure
      # HTTPS
      - traefik.http.routers.vault-secure.entrypoints=websecure
      - traefik.http.routers.vault-secure.rule=Host(`vault.example.com`)
      - traefik.http.routers.vault-secure.tls=true
      - traefik.http.routers.vault-secure.tls.options=default
      - traefik.http.routers.vault-secure.middlewares=ip-whitelist@docker
      - traefik.http.routers.vault-secure.tls.certresolver=le
      - traefik.http.routers.vault-secure.service=vault-secure
      - traefik.http.services.vault-secure.loadbalancer.server.port=8200

networks:
  edge:
    name: edge
    external: true

volumes:
  vault_data:
  traefik_acme:
    name: traefik_acme

Start the stack:

docker compose up -d
docker compose ps

NAME      IMAGE                  STATUS
traefik   traefik:v3.2           Up (healthy)
vault     hashicorp/vault:1.17   Up (healthy)

Open https://vault.example.com — the UI loads but shows Sealed until you unseal (Part 6).

Compose fields explained

Traefik labels explained

Part 5A — End-to-end bootstrap: cold Vault to Laravel-ready

Parts 4–8 explain each step in depth. This part is the single runbook an operator runs once on a new Vault node (and repeats after disaster recovery on empty storage — never run operator init twice on existing data).

config.hcl + storage volume
  → docker compose up (Vault sealed but healthy if API is up)
  → operator init (once)
  → operator unseal × threshold
  → login (root, bootstrap only)
  → secrets enable kv-v2 @ secret
  → policy write laravel
  → auth enable approle
  → write auth/approle/role/laravel
  → read role-id + write secret-id
  → kv put secret/laravel/...
  → approle login + kv get (smoke test)
  → revoke root / lock away
  → configure Laravel or Agent

Gate 0 — Configuration and storage

1. Create vault/config/config.hcl (Part 4): storage "file" { path = "/vault/file" }, listener, api_addr, cluster_addr. Only this one file in the config directory.
2. Start stack: docker compose up -d. Expect Vault healthy while sealed if the API listens (Part 5 healthcheck accepts exit 0 and 2).
3. Verify: docker compose logs vault shows config loaded, no crash loop.

Gate 1 — Initialize and unseal

docker exec -it vault vault operator init -key-shares=5 -key-threshold=3
# Store shares offline. Then:
docker exec -it vault vault operator unseal   # repeat with 3 distinct shares
docker exec vault vault status                # Sealed: false
docker exec -it vault vault login             # root token, bootstrap only

Exit criterion: Initialized true, Sealed false, authenticated CLI session. If already initialized, skip init and only unseal after restarts.

Gate 2 — KV engine, policy, AppRole, secrets

docker exec vault vault secrets enable -path=secret kv-v2

docker cp vault/policies/laravel-policy.hcl vault:/tmp/laravel-policy.hcl
docker exec vault vault policy write laravel /tmp/laravel-policy.hcl

docker exec vault vault auth enable approle
docker exec vault vault write auth/approle/role/laravel \
  token_policies="laravel" token_ttl=1h token_max_ttl=4h secret_id_ttl=0

docker exec vault vault read -field=role_id auth/approle/role/laravel/role-id
docker exec vault vault write -f -field=secret_id auth/approle/role/laravel/secret-id

docker exec vault vault kv put secret/laravel/production/database \
  DB_HOST=10.0.1.5 DB_PORT=3306 DB_DATABASE=app DB_USERNAME=app \
  DB_PASSWORD='CHANGE_ME'

docker exec vault vault kv put secret/laravel/production/redis \
  REDIS_CACHE_HOST=10.0.1.10 REDIS_CACHE_PASSWORD='CHANGE_ME' \
  REDIS_SESSION_HOST=10.0.1.11 REDIS_SESSION_PASSWORD='CHANGE_ME' \
  REDIS_HORIZON_HOST=10.0.1.10 REDIS_HORIZON_PASSWORD='CHANGE_ME'

Gate 3 — Smoke test as Laravel will

export VAULT_ADDR=https://vault.example.com   # or http://vault:8200 in lab
read -r -s -p "Role ID: " ROLE_ID; echo
read -r -s -p "Secret ID: " SECRET_ID; echo
vault write auth/approle/login role_id="$ROLE_ID" secret_id="$SECRET_ID"
# paste client_token:
export VAULT_TOKEN=<client_token>
vault kv get secret/laravel/production/database
vault kv get secret/laravel/production/redis

Exit criterion: HTTP 200 on both KV reads; 403 here means policy path typo (secret/data/... vs CLI path). Then revoke root token or remove from active use (Part 8).

Part 6 — Initialize, unseal, and self-hosted auto-unseal

A Vault process begins sealed. With the default Shamir seal, operators submit a threshold of unseal-key shares after every process restart. With an auto seal, Vault asks an external seal service to unwrap its root key and operators retain recovery-key shares for quorum-authorized recovery operations. Recovery shares do not manually unseal a Vault whose Transit dependency is unavailable.

operator init parameters (shares, threshold)

Initialization is a first-start operation against empty storage. Running init again returns “Vault is already initialized.” Back up before changing an existing seal; initialization is not a migration mechanism.

Path A — initialize the Shamir lab

docker exec -it vault vault operator init -key-shares=5 -key-threshold=3

Unseal Key 1: <redacted>
Unseal Key 2: <redacted>
Unseal Key 3: <redacted>
Unseal Key 4: <redacted>
Unseal Key 5: <redacted>

Initial Root Token: <redacted>

Vault initialized with 5 key shares and a key threshold of 3.

docker exec -it vault vault operator unseal
docker exec -it vault vault operator unseal
docker exec -it vault vault operator unseal

Key             Value
---             -----
Seal Type       shamir
Initialized     true
Sealed          false
Total Shares    5
Threshold       3
Version         1.17.x
Storage Type    file
HA Enabled      false

docker exec vault vault status
docker exec -it vault vault login

Success! You are now authenticated. The token information displayed below
is already stored in the token helper.

Key                  Value
---                  -----
token                <redacted>
token_accessor       <redacted>
token_duration       ∞
token_renewable      false
token_policies       ["root"]

Shamir restarts

Only the Shamir path requires T share submissions after every Vault process or host restart. A script that stores those shares beside Vault is not auto-unseal; it collapses custody onto that host. The remaining subsections implement real self-hosted auto-unseal.

Path B — self-hosted auto-unseal with a dedicated Unseal Vault

The Unseal Vault is a separate trust domain: separate VM(s), storage, listener, DNS, backup, root token, audit log, and failure budget. Bootstrap it with Shamir and keep it running before the target starts. Do not point a Vault at its own Transit engine: while sealed it cannot serve the decrypt request needed to unseal itself.

1. Build and initialize https://unseal-vault.internal:8200 with Shamir; unseal it manually and log in for bootstrap.
2. Enable Transit, create a non-exportable key, write a least-privilege policy, and issue an orphan periodic service token.
3. Place only that token and the Unseal Vault CA on every target node with restrictive ownership and mounts.
4. Add the Transit seal stanza before initializing a fresh target, or follow the migration sequence for existing storage.

export VAULT_ADDR=https://unseal-vault.internal:8200
export VAULT_CACERT=/etc/vault-unseal/tls/ca.pem
vault secrets enable transit
vault write -f transit/keys/autounseal

cat > /tmp/autounseal-policy.hcl <<'EOF'
path "transit/encrypt/autounseal" {
  capabilities = ["update"]
}
path "transit/decrypt/autounseal" {
  capabilities = ["update"]
}
EOF
vault policy write autounseal /tmp/autounseal-policy.hcl
vault token create -orphan -period=24h -policy=autounseal

Success! Enabled the transit secrets engine at: transit/
Success! Data written to: transit/keys/autounseal
Success! Uploaded policy: autounseal

Key                  Value
---                  -----
token                <redacted>
token_accessor       <redacted>
token_duration       24h
token_renewable      true
token_policies       ["autounseal" "default"]

seal "transit" {
  address         = "https://unseal-vault.internal:8200"
  key_name        = "autounseal"
  mount_path      = "transit/"
  token            = "file:///vault/seal/token"
  tls_ca_cert     = "/vault/seal/unseal-vault-ca.pem"
  tls_server_name = "unseal-vault.internal"
  disable_renewal = "false"
}

sudo install -d -o vault -g vault -m 0700 /etc/vault.d/seal
sudo sh -c 'umask 077; tr -d "\r\n" < /secure-transfer/autounseal.token > /etc/vault.d/seal/token'
sudo chown vault:vault /etc/vault.d/seal/token
sudo install -o root -g vault -m 0640 /secure-transfer/unseal-vault-ca.pem /etc/vault.d/seal/unseal-vault-ca.pem
# Docker mounts:
# /etc/vault.d/seal/token:/vault/seal/token:ro
# /etc/vault.d/seal/unseal-vault-ca.pem:/vault/seal/unseal-vault-ca.pem:ro

Keep certificate verification enabled. The CA must validate the Unseal Vault’s presented chain and tls_server_name must match a certificate SAN. Never use tls_skip_verify=true in production.

Fresh target initialization with recovery shares

docker exec -it vault vault operator init \
  -recovery-shares=5 \
  -recovery-threshold=3

Recovery Key 1: <redacted>
Recovery Key 2: <redacted>
Recovery Key 3: <redacted>
Recovery Key 4: <redacted>
Recovery Key 5: <redacted>

Initial Root Token: <redacted>

Success! Vault is initialized

docker compose restart vault
docker exec vault vault status

Key                     Value
---                     -----
Seal Type               transit
Recovery Seal Type      shamir
Initialized             true
Sealed                  false
Total Recovery Shares   5
Threshold               3
Version                 1.19.x
Storage Type            file
HA Enabled              false

Operational dependency and backup checks

• Availability: the Unseal Vault must be reachable whenever a target starts and whenever Transit-dependent seal operations occur. Existing unsealed target processes may continue through a brief outage, but a restart cannot recover without Transit.
• No circular dependencies: do not host the Unseal Vault only on infrastructure that needs the target Vault to boot (target-sourced TLS keys, database credentials, DNS credentials, storage unlock, or scheduler secrets). Give it an independent startup path.
• Backups: back up Unseal Vault storage and target storage independently. Preserve the Unseal Vault’s Shamir shares and the Transit key’s storage; a new key with the same name cannot decrypt old target wrapping material.
• Token lifecycle: monitor renewal failures and expiry. Test the narrow token with vault token lookup on the Unseal Vault by accessor; rotate by writing a new token file and restarting/reloading targets in a controlled window.
• Long target outage: a periodic token is renewable, not immortal. If every target is down longer than its period, the token expires because nothing renews it. Before the next cold start, an Unseal Vault operator must issue and securely install a replacement token; test this recovery path.
• Health: alert on Unseal Vault sealed/unavailable, Transit request errors, target sealed=true, TLS expiry, audit write failures, and backup age. Test cold starts, not just a running target.

Migrate an existing Shamir target to Transit

1. Build, initialize, unseal, back up, and health-check the independent Unseal Vault. Create Transit key, policy, periodic token, CA file, and test TLS reachability from the target host.
2. Back up the target storage and configuration. Record vault status, verify the old Shamir threshold and version, and schedule downtime.
3. Add the Transit seal stanza and protected files while the target still runs, then stop the target cleanly.
4. Start the target with the new stanza. It remains sealed in migration mode; that is expected.
5. Submit the existing Shamir shares, using -migrate on every command, until the threshold is met.
6. Verify Seal Type transit, Recovery Seal Type shamir, Sealed false, and then perform a controlled restart to prove auto-unseal.

docker exec -it vault vault operator unseal -migrate
docker exec -it vault vault operator unseal -migrate
docker exec -it vault vault operator unseal -migrate
docker exec vault vault status
docker compose restart vault
docker exec vault vault status

Key                     Value
---                     -----
Seal Type               transit
Recovery Seal Type      shamir
Initialized             true
Sealed                  false
Total Recovery Shares   5
Threshold               3
Migration               false
Storage Type            file
HA Enabled              false

Self-hosted Raft clusters

Every Raft node must have the same Transit seal type, Unseal Vault address, mount path, key name, and trusted CA. Give each target cluster a dedicated token; each node needs access to the protected token file. Node-specific settings such as node_id, listener address, and cluster_addr remain unique.

• Fresh cluster: initialize only the first node with recovery shares. Auto-sealed peers using retry_join join and unseal automatically; never initialize peers independently.
• Shamir-to-Transit migration: stop the entire Raft cluster, update the seal stanza and files on all nodes, then bring enough nodes up together for Raft quorum. Run the threshold of operator unseal -migrate submissions against the elected leader. The leader writes migration state to Raft and replicates it; do not repeat seal migration separately on each peer. Start/restart remaining peers and verify each auto-unseals.
• Per-node verification: query each node’s local API address and confirm Seal Type transit, Sealed false, expected peer membership, and one active leader. A load-balanced status check can hide a sealed peer.

vault operator raft list-peers
vault operator raft snapshot save backups/vault-raft-$(date +%Y%m%d-%H%M%S).snap
sha256sum backups/vault-raft-*.snap

Node       Address               State       Voter
----       -------               -----       -----
vault-1    vault-1:8201          leader      true
vault-2    vault-2:8201          follower    true
vault-3    vault-3:8201          follower    true

Restore into an isolated recovery environment first. Use the same Transit seal configuration and ensure the original Unseal Vault Transit key is available before restoring. Authenticate with sufficient privileges, then run vault operator raft snapshot restore backup.snap. Use -force only when deliberately bypassing seal-consistency checks during a documented disaster-recovery procedure; it is not a routine flag. After restore, verify all peer IDs/addresses, restart peers one at a time, check each node’s seal status, and test a non-destructive secret read.

PKCS#11 / on-premises HSM (Enterprise only)

seal "pkcs11" is the direct no-cloud HSM option, but PKCS#11 auto-unseal and seal wrapping require a Vault Enterprise edition/binary with HSM entitlement. It is not available in Vault Community Edition. For OSS, the practical self-hosted recommendation is the dedicated Transit architecture above.

seal "pkcs11" {
  lib            = "/opt/hsm/lib/libpkcs11.so"
  slot           = "0"
  key_label      = "vault-root"
  hmac_key_label = "vault-hmac"
  generate_key   = "false"
  # Supply the PIN through VAULT_HSM_PIN, not this file.
}

• Use a supported PKCS#11 v2.20+ vendor library and matching OS/CPU architecture; Vault does not replace the vendor’s HSM integration guide.
• Prefer pre-provisioned, backed-up, non-exportable HSM keys (generate_key=false); some FIPS/CC modes require manual key creation.
• Deploy an HA HSM service and test library reconnection. Enterprise seal wrap can require HSM availability during runtime, not only at startup, and adds latency.
• Keep PINs outside HCL (for example VAULT_HSM_PIN from a protected service manager), restrict library/config permissions, and document HSM key backup/replication and quorum administration.
• Validate mechanism and data-size constraints with the exact HSM model. Never copy a mechanism numeric value from another vendor without compatibility testing.

Part 7 — KV v2 secrets engine, paths, and policies

Enable KV version 2 at path secret:

docker exec -it vault vault secrets enable -path=secret kv-v2

Success! Enabled the kv-v2 secrets engine at: secret/

Store a sample secret:

docker exec -it vault vault kv put secret/laravel/app \
  DB_PASSWORD="super-secret-db-password" \
  MAIL_PASSWORD="smtp-password-here"

===== Secret Path =====
secret/data/laravel/app

======= Metadata =======
Key                Value
---                -----
created_time       2026-08-30T10:00:00.000Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

Verify:

docker exec -it vault vault kv get secret/laravel/app

======= Secret Path =======
secret/data/laravel/app

======= Metadata =======
Key                Value
---                -----
created_time       2026-08-30T10:00:00.000Z
deletion_time      n/a
destroyed          false
version            1

======= Data =======
Key             Value
---             -----
DB_PASSWORD     super-secret-db-password
MAIL_PASSWORD   smtp-password-here

KV v2 parameters and HTTP vs CLI paths

Enable is one command; the engine still has tunables. KV v1 (no versions, path without /data/) is not what this lab uses. If someone ran vault secrets enable kv without -version=2 / kv-v2, Laravel’s data.data parsing will be wrong.

docker exec vault vault kv metadata put -max-versions=20 secret/laravel/app
# engine-wide default:
docker exec vault vault write secret/config max_versions=20

Policy capabilities and path prefixes

Policies match the API path, not the CLI shorthand. Capabilities are the verbs Vault evaluates after auth.

A tighter lab policy (read data only — this is what Laravel needs):

path "secret/data/laravel/*" {
  capabilities = ["read"]
}

Apply the policy (name must match AppRole token_policies in Part 8):

docker cp vault/policies/laravel-policy.hcl vault:/tmp/laravel-policy.hcl
docker exec -it vault vault policy write laravel /tmp/laravel-policy.hcl

Recommended KV layout for Laravel (multi-database, multi-Redis)

One flat secret/laravel/app key map does not scale when cache, session, and Horizon use different Redis instances (or passwords). Split by environment and concern so policies can scope reads and rotation jobs touch one surface at a time.

secret/laravel/production/database     # MariaDB/MySQL credentials
secret/laravel/production/redis      # all Redis endpoints + passwords
secret/laravel/production/mail       # SMTP, API mailers
secret/laravel/production/integrations  # payment, webhooks, third-party APIs
secret/laravel/production/app-key    # APP_KEY only — Agent-friendly path
secret/laravel/staging/...           # parallel tree, tighter policies

HTTP API paths add /data/: e.g. secret/data/laravel/production/redis. Policy glob for the app role:

path "secret/data/laravel/production/*" {
  capabilities = ["read"]
}
path "secret/data/laravel/staging/*" {
  capabilities = ["read"]
}

Example Redis secret (one KV object, multiple logical clients):

docker exec vault vault kv put secret/laravel/production/redis \
  REDIS_CACHE_HOST=redis-cache.internal \
  REDIS_CACHE_PORT=6379 \
  REDIS_CACHE_PASSWORD='cache-secret' \
  REDIS_SESSION_HOST=redis-session.internal \
  REDIS_SESSION_PORT=6379 \
  REDIS_SESSION_PASSWORD='session-secret' \
  REDIS_HORIZON_HOST=redis-cache.internal \
  REDIS_HORIZON_PORT=6379 \
  REDIS_HORIZON_PASSWORD='cache-secret'

Horizon often shares the cache Redis but uses a different database index — still one password if the instance is shared; use separate keys when the host or password differs.

Part 8 — AppRole authentication for Laravel (recommended for Compose)

Enable AppRole:

docker exec -it vault vault auth enable approle

Success! Enabled approle auth method at: approle/

Create the role — token_policies must exactly match the policy name from vault policy write laravel:

docker exec -it vault vault write auth/approle/role/laravel \
  token_policies="laravel" \
  token_ttl=1h \
  token_max_ttl=4h \
  secret_id_ttl=0

Success! Data written to: auth/approle/role/laravel

Get the Role ID (safe in .env):

docker exec vault vault read -field=role_id auth/approle/role/laravel/role-id

Generate a Secret ID (treat like a password — never commit to git):

docker exec vault vault write -f -field=secret_id auth/approle/role/laravel/secret-id

Every AppRole parameter — default, meaning, how to set

Zero means different things on different fields. Read this table before you copy secret_id_ttl=0 into production and assume it matches token_ttl=0 (it does not).

Login API (what Laravel calls):

read -r -p "Role ID: " ROLE_ID
read -r -s -p "Secret ID: " SECRET_ID; echo
vault write auth/approle/login role_id="$ROLE_ID" secret_id="$SECRET_ID"
unset ROLE_ID SECRET_ID

Key                     Value
---                     -----
token                   <redacted>
token_accessor          <redacted>
token_duration          1h
token_renewable         true
token_policies          ["default" "laravel"]

Production bootstrap: initial Secret ID delivery

Lab generates Secret ID on the Vault host. Production separates role creation (infrequent, admin) from Secret ID delivery (each deploy target, least exposure).

Admin (break-glass):
  - AppRole role laravel-prod exists; policy read-only on secret/data/laravel/production/*
  - Role ID stored in config management (not secret)

CI / release pipeline (per environment):
  1. Authenticate to Vault with human OIDC or CI JWT (Part 9) — NOT root
  2. vault write -f -wrap-ttl=600 auth/approle/role/laravel-prod/secret-id
  3. Deliver wrap token to target host via SSH vault unwrap or Ansible — one time
  4. Unwrap → write /vault/agent/secret_id mode 0600, owner root
  5. Start vault-agent; verify templates; delete plaintext Secret ID from shell history

Runtime:
  - Agent reads role_id + secret_id files, logs in, renews token
  - remove_secret_id_file_after_reading=true only if orchestrator injects fresh ID on each Agent recreate

Rotation (quarterly):
  - Generate new secret-id; deploy to agents; verify login; destroy old accessor
  - secret_id_num_uses=0 for multi-process Agent; use num_uses=1 only for single-login automation

vault write -f -wrap-ttl=10m -field=wrapping_token \
  auth/approle/role/laravel-prod/secret-id

# On target (within wrap TTL):
vault unwrap -field=secret_id <wrapping_token> | install -m 600 /vault/agent/secret_id

Response wrapping for Secret ID

A wrapped Secret ID is a single-use token that unwraps to the real Secret ID. The wrap token can live in CI; the Secret ID never sits in a chat log. Laravel then has the unwrapped Secret ID in the process environment, or you unwrap on the server once per deploy.

# Create a wrapped Secret ID (wrap_ttl = how long the wrap token is valid)
WRAP=$(docker exec vault vault write -wrap-ttl=5m -f -field=wrapping_token \
  auth/approle/role/laravel/secret-id)

# On the app host, unwrap once (VAULT_ADDR must reach Vault)
# vault unwrap -field=secret_id "$WRAP"
# Put the result in VAULT_SECRET_ID and discard the wrap token

If secret_id_num_uses=1, that unwrapped ID is good for one AppRole login. That fits “one Agent or one deploy job logs in and writes a token file,” not “fifty PHP-FPM children each login.” For FPM pull with one shared Secret ID, keep secret_id_num_uses=0 (unlimited) and rotate the Secret ID on a calendar.

Part 9 — Other auth methods (Kubernetes, JWT/OIDC, TLS, token)

Static token (anti-pattern)

Create a token with vault token create -policy=laravel -ttl=24h and put it in VAULT_TOKEN. Laravel would send it as X-Vault-Token with no login step. That token is the secret. It is easier than AppRole and worse in every incident: no Role ID/Secret ID split, easy to commit, hard to see which app it belongs to. Do not use this for production Laravel.

Kubernetes auth — implementation

Use this when Laravel runs in a cluster and the pod already has a service account token. Vault validates that JWT against the Kubernetes API (or a configured JWT issuer in newer setups).

docker exec -it vault vault auth enable kubernetes

# In-cluster Vault (typical):
# vault write auth/kubernetes/config \
#   kubernetes_host="https://kubernetes.default.svc" \
#   kubernetes_ca_cert=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt \
#   token_reviewer_jwt=@/var/run/secrets/kubernetes.io/serviceaccount/token

docker exec -it vault vault write auth/kubernetes/role/laravel \
  bound_service_account_names=laravel \
  bound_service_account_namespaces=production \
  token_policies=laravel \
  token_ttl=1h \
  token_max_ttl=4h \
  audience=vault

Laravel (or a tiny sidecar) then POSTs the projected JWT:

POST /v1/auth/kubernetes/login
{
  "role": "laravel",
  "jwt": "<contents of /var/run/secrets/kubernetes.io/serviceaccount/token>"
}

After login, KV reads are identical to AppRole: same X-Vault-Token, same secret/data/… policy. Only the login URL and body change. Do not also put AppRole Secret IDs in the same pod unless you are migrating; one identity source.

JWT / OIDC — implementation shape

OIDC is the right method for humans (Vault UI) and for CI (GitHub Actions OIDC, GitLab ID tokens). It is usually the wrong method for long-running PHP-FPM: you would need a JWT minted for every worker start.

vault auth enable jwt
vault write auth/jwt/config \
  bound_issuer="https://token.actions.githubusercontent.com" \
  oidc_discovery_url="https://token.actions.githubusercontent.com"

vault write auth/jwt/role/laravel-ci \
  role_type="jwt" \
  user_claim="sub" \
  bound_audiences="https://github.com/YOUR_ORG" \
  bound_claims_type="glob" \
  bound_claims='{"ref":"refs/heads/main","repository":"YOUR_ORG/YOUR_REPO"}' \
  token_policies="laravel" \
  token_ttl=15m

The GitHub workflow then exchanges ACTIONS_ID_TOKEN_REQUEST_TOKEN for a JWT and calls POST /v1/auth/jwt/login with role + jwt. Use this to write KV or to mint a wrapped Secret ID during deploy — not as the PHP runtime identity unless each request carries a JWT (API gateway pattern).

TLS certificate auth — implementation shape

vault auth enable cert
vault write auth/cert/certs/laravel \
  display_name=laravel \
  policies=laravel \
  certificate=@/path/to/ca.pem \
  ttl=1h

The HTTP client must present the client certificate (Http::withOptions(['cert' => ..., 'ssl_key' => ...])). Traefik-to-Vault HTTP in this lab does not pass client certs through unless you configure Traefik passthrough / mTLS to the backend. That is why AppRole is the Compose default.

Part 10 — Secret delivery methodologies (HTTP pull, Agent, dynamic DB)

Method A — HTTP pull (this guide’s lab)

PHP authenticates (AppRole) and GETs KV during register(). Implementation is Part 11–12. Use it when: Compose or a VM, a handful of static secrets, you can tolerate “Vault down means app down” at boot.

Method B — Vault Agent templates (PHP never calls Vault)

Production reference: Part 10B — Vault Agent: complete Compose reference (sidecar, templates, shared volume, Swoole/Octane entrypoint, APP_KEY). Use Part 10B instead of duplicating config here.

Method C — Dynamic database credentials

Vault’s database secrets engine creates a MySQL/MariaDB user on demand, with a lease. Laravel’s password is no longer a KV string you rotate by hand; it expires. You need a reconnect story.

docker exec -it vault vault secrets enable database

docker exec -it vault vault write database/config/mysql \
  plugin_name=mysql-database-plugin \
  connection_url="{{username}}:{{password}}@tcp(mariadb:3306)/" \
  allowed_roles="laravel" \
  username="vault-admin" \
  password="vault-admin-password"

docker exec -it vault vault write database/roles/laravel \
  db_name=mysql \
  creation_statements="CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}'; GRANT SELECT,INSERT,UPDATE,DELETE ON appdb.* TO '{{name}}'@'%';" \
  default_ttl="1h" \
  max_ttl="24h"

Read credentials: GET /v1/database/creds/laravel returns data.username, data.password, and a lease ID. PHP-FPM: one login per process per TTL is usually fine if default_ttl is longer than the request. Octane/queue workers: renew sys/leases/renew with the lease ID, or reconnect when you get SQLSTATE 1045. Static KV passwords are simpler; use dynamic creds when the compliance requirement is “no long-lived DB password.”

Part 10A — Migrating existing Laravel secrets into Vault

What to move vs what to leave in Compose / .env

See also Part 13A — runtime secrets vs non-sensitive configuration for the full split.

First import procedure

1. Inventory — Export a redacted list from production .env (names only in tickets; values never in chat).
2. Map paths — Assign each secret to a KV path (layout above). One kv put per concern.
3. Write KV — From an operator shell with admin policy, not from Laravel:

docker exec vault vault kv put secret/laravel/production/database \
  DB_PASSWORD="$(grep ^DB_PASSWORD= .env.production | cut -d= -f2-)"

docker exec vault vault kv put secret/laravel/production/redis \
  REDIS_CACHE_PASSWORD='...' \
  REDIS_SESSION_PASSWORD='...' \
  REDIS_HORIZON_PASSWORD='...'

docker exec vault vault kv put secret/laravel/production/mail \
  MAIL_PASSWORD='...'

docker exec vault vault kv put secret/laravel/production/app-key \
  APP_KEY='base64:...'

4. Extend AppRole policy if paths changed from the lab glob.
5. Dual-run — Enable Vault in staging; keep .env fallback with VAULT_ENABLED=false locally.
6. Cutover — Set VAULT_ENABLED=true, remove migrated keys from production .env only after smoke tests (DB, cache, session, queue, mail).
7. Rotate — Treat import as potentially exposed; rotate DB/Redis passwords after cutover if .env ever lived in backup logs or git.

Part 10B — Vault Agent: complete Compose reference

Agent authenticates with AppRole, renders files into a shared volume, and optionally runs a reload command. Laravel never calls Vault at runtime if all secrets are templated.

Vault on a separate host: set vault-agent VAULT_ADDR to the same URL Laravel would use (https://vault.internal or allowlisted public URL). Mount the internal CA into the Agent container; do not rely on the in-stack http://vault:8200 DNS name unless Vault runs on the same Compose network. See split-server topology.

services:
  vault:
    image: hashicorp/vault:1.17
    # ... Part 5 vault service ...
    networks: [app_net]

  vault-agent:
    image: hashicorp/vault:1.17
    container_name: vault-agent
    restart: unless-stopped
    command: agent -config=/vault/agent/agent.hcl
    environment:
      VAULT_ADDR: "http://vault:8200"   # or https://vault.internal from Laravel host
    volumes:
      - ./vault/agent:/vault/agent:ro
      - vault_secrets:/run/secrets
    depends_on:
      vault:
        condition: service_started
    networks: [app_net]

  laravel:
    build: ./laravel
    restart: unless-stopped
    env_file: .env.nonsecret          # APP_ENV, VAULT_* absent from secrets file
    volumes:
      - vault_secrets:/run/secrets:ro
    depends_on:
      vault-agent:
        condition: service_started
    entrypoint: ["/bin/sh", "/docker/entrypoint.sh"]
    networks: [app_net]

volumes:
  vault_secrets:

networks:
  app_net:

pid_file = "/tmp/agent.pid"
exit_after_auth = false

vault {
  address = "http://vault:8200"
}

auto_auth {
  method "approle" {
    mount_path = "auth/approle"
    config = {
      role_id_file_path                   = "/vault/agent/role_id"
      secret_id_file_path                 = "/vault/agent/secret_id"
      remove_secret_id_file_after_reading = false
    }
  }
}

template {
  source      = "/vault/agent/laravel.env.ctmpl"
  destination = "/run/secrets/laravel.env"
  perms       = 0600
  error_on_missing_key = true
}

template {
  source      = "/vault/agent/app-key.ctmpl"
  destination = "/run/secrets/app_key"
  perms       = 0600
}

{{ with secret "secret/data/laravel/production/database" }}
DB_PASSWORD={{ .Data.data.DB_PASSWORD }}
{{ end }}
{{ with secret "secret/data/laravel/production/redis" }}
REDIS_CACHE_PASSWORD={{ .Data.data.REDIS_CACHE_PASSWORD }}
REDIS_SESSION_PASSWORD={{ .Data.data.REDIS_SESSION_PASSWORD }}
REDIS_HORIZON_PASSWORD={{ .Data.data.REDIS_HORIZON_PASSWORD }}
{{ end }}
{{ with secret "secret/data/laravel/production/mail" }}
MAIL_PASSWORD={{ .Data.data.MAIL_PASSWORD }}
{{ end }}

{{ with secret "secret/data/laravel/production/app-key" }}{{ .Data.data.APP_KEY }}{{ end }}

#!/bin/sh
set -eu

# Wait until Agent rendered secrets (Compose start order is not enough if Vault was sealed)
i=0
while [ ! -f /run/secrets/laravel.env ] || [ ! -f /run/secrets/app_key ]; do
  i=$((i + 1))
  if [ "$i" -gt 60 ]; then
    echo "vault-agent secrets not ready after 60s" >&2
    exit 1
  fi
  sleep 1
done

export APP_KEY="$(cat /run/secrets/app_key)"
set -a
. /run/secrets/laravel.env
set +a

exec "$@"

Compose command for Octane:

command: ["php", "artisan", "octane:start", "--server=swoole", "--host=0.0.0.0", "--port=8000", "--workers=4"]

Mount entrypoint.sh executable. APP_KEY is exported before php artisan octane:start — satisfying encrypter bootstrap (Part 12). Omit --workers and Octane defaults to one worker per CPU core; set it explicitly in production (e.g. --workers=4). Each worker bootstraps Laravel once — see secret lifecycle.

Loading Agent secrets before Swoole / Octane

Swoole workers inherit the parent process environment established at container start. Secrets must be on disk and sourced in the entrypoint, not inside AppServiceProvider, for:

• APP_KEY (required before config cache / encrypter)
• Any value read from env() during config/*.php load if you mirror secrets into env vars

Flow:

1. Agent renders /run/secrets/laravel.env and /run/secrets/app_key.
2. Entrypoint exports APP_KEY, sources laravel.env, execs Octane.
3. config/database.php uses env('DB_PASSWORD') which now resolves from the sourced file.
4. Optional: AppServiceProvider::register() still maps multi-Redis hosts from env if those keys were templated.

Secret lifecycle under Octane / Swoole

Agent + template reload: Add command = "..." on the template stanza to signal Octane only after a successful re-render (e.g. touch a reload flag consumed by a side process). Simplest production pattern: redeploy or docker compose restart laravel after KV rotation.

APP_KEY path with Agent (end-to-end)

1. Store APP_KEY at secret/laravel/production/app-key (never commit).
2. Agent template writes one line to /run/secrets/app_key.
3. Entrypoint: export APP_KEY="$(cat /run/secrets/app_key)" before any PHP.
4. Laravel config/app.php keeps 'key' => env('APP_KEY') — unchanged.
5. Do not fetch APP_KEY via HTTP pull in register(); it is too late for session/crypto already initialized in edge cases.

Laravel configuration: MariaDB + three Redis clients

With secrets in env (Agent-sourced or Config::set from Vault HTTP pull), wire explicit Redis connections:

'redis' => [
    'client' => env('REDIS_CLIENT', 'phpredis'),

    'default' => [  // Horizon often uses default or horizon connection
        'host' => env('REDIS_HORIZON_HOST', env('REDIS_CACHE_HOST', '127.0.0.1')),
        'password' => env('REDIS_HORIZON_PASSWORD', env('REDIS_CACHE_PASSWORD')),
        'port' => env('REDIS_HORIZON_PORT', 6379),
        'database' => env('REDIS_HORIZON_DB', 0),
    ],

    'cache' => [
        'host' => env('REDIS_CACHE_HOST', '127.0.0.1'),
        'password' => env('REDIS_CACHE_PASSWORD'),
        'port' => env('REDIS_CACHE_PORT', 6379),
        'database' => env('REDIS_CACHE_DB', 1),
    ],

    'session' => [
        'host' => env('REDIS_SESSION_HOST', '127.0.0.1'),
        'password' => env('REDIS_SESSION_PASSWORD'),
        'port' => env('REDIS_SESSION_PORT', 6379),
        'database' => env('REDIS_SESSION_DB', 2),
    ],
],

// config/cache.php
'stores' => [
    'redis' => [
        'driver' => 'redis',
        'connection' => 'cache',
    ],
],

// config/session.php
'driver' => env('SESSION_DRIVER', 'redis'),
'connection' => 'session',

'use' => 'default',  // uses redis.default connection above

HTTP pull in register() alternative — map KV into config without env:

$db = $vault->getSecret('secret/data/laravel/production/database');
$redis = $vault->getSecret('secret/data/laravel/production/redis');
Config::set('database.connections.mysql.password', $db['DB_PASSWORD'] ?? '');
Config::set('database.redis.cache.password', $redis['REDIS_CACHE_PASSWORD'] ?? '');
Config::set('database.redis.session.password', $redis['REDIS_SESSION_PASSWORD'] ?? '');
Config::set('database.redis.default.password', $redis['REDIS_HORIZON_PASSWORD'] ?? '');

Part 11 — Laravel VaultService and HTTP client

Laravel already ships with Guzzle via Illuminate\Http\Client. No extra composer require is needed unless you prefer the raw Guzzle client directly. Official HashiCorp libraries are Go/Java/.NET/Ruby — there is no first-party Laravel SDK; HTTP is the supported contract.

Laravel env / config/vault.php parameters

Laravel in the same Compose stack (add a laravel service on edge):

VAULT_ADDR=http://vault:8200
VAULT_ROLE_ID=your-role-id-here
VAULT_SECRET_ID=your-secret-id-here
VAULT_SECRET_PATH=secret/data/laravel/app
VAULT_VERIFY_TLS=true
VAULT_TIMEOUT=10
VAULT_RETRIES=2
VAULT_ENABLED=true

Laravel on the host (PHP runs outside Docker):

VAULT_ADDR=https://vault.example.com
VAULT_ROLE_ID=your-role-id-here
VAULT_SECRET_ID=your-secret-id-here
VAULT_SECRET_PATH=secret/data/laravel/app
VAULT_VERIFY_TLS=true
VAULT_TIMEOUT=10
VAULT_RETRIES=2
VAULT_ENABLED=true

Create config/vault.php:

<?php

return [
    'enabled'     => filter_var(env('VAULT_ENABLED', false), FILTER_VALIDATE_BOOLEAN),
    'address'     => env('VAULT_ADDR', 'http://127.0.0.1:8200'),
    'role_id'     => env('VAULT_ROLE_ID'),
    'secret_id'   => env('VAULT_SECRET_ID'),
    'secret_path' => env('VAULT_SECRET_PATH', 'secret/data/laravel/app'),
    'verify_tls'  => filter_var(env('VAULT_VERIFY_TLS', true), FILTER_VALIDATE_BOOLEAN),
    'timeout'     => (int) env('VAULT_TIMEOUT', 10),
    'retries'     => (int) env('VAULT_RETRIES', 2),
    'namespace'   => env('VAULT_NAMESPACE'), // Enterprise / HCP only
];

App on host vs app in Compose

Create app/Services/VaultService.php using Laravel's HTTP client:

<?php

namespace App\Services;

use Illuminate\Http\Client\PendingRequest;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Http;
use RuntimeException;

class VaultService
{
    private ?string $token = null;

    private function baseUrl(): string
    {
        return rtrim((string) config('vault.address'), '/');
    }

    private function client(): PendingRequest
    {
        $request = Http::timeout((int) config('vault.timeout', 10))
            ->retry((int) config('vault.retries', 2), 200, throw: false)
            ->withOptions(['verify' => (bool) config('vault.verify_tls')]);

        $namespace = config('vault.namespace');
        if (is_string($namespace) && $namespace !== '') {
            $request = $request->withHeaders(['X-Vault-Namespace' => $namespace]);
        }

        return $request;
    }

    private function vaultError(string $prefix, $response): string
    {
        $errors = $response->json('errors');
        if (is_array($errors) && $errors !== []) {
            return $prefix . ': ' . implode('; ', $errors);
        }

        return $prefix . ' (HTTP ' . $response->status() . ')';
    }

    public function authenticate(): string
    {
        if ($this->token) {
            return $this->token;
        }

        $response = $this->client()->post("{$this->baseUrl()}/v1/auth/approle/login", [
            'role_id'   => config('vault.role_id'),
            'secret_id' => config('vault.secret_id'),
        ]);

        if (! $response->successful()) {
            throw new RuntimeException($this->vaultError('Vault AppRole login failed', $response));
        }

        $this->token = $response->json('auth.client_token');

        if (! $this->token) {
            throw new RuntimeException('Vault AppRole login returned no client token.');
        }

        return $this->token;
    }

    public function getSecret(?string $path = null): array
    {
        $path = $path ?? config('vault.secret_path');
        $token = $this->authenticate();

        $response = $this->client()
            ->withHeaders(['X-Vault-Token' => $token])
            ->get("{$this->baseUrl()}/v1/{$path}");

        if (! $response->successful()) {
            throw new RuntimeException($this->vaultError("Vault read failed for {$path}", $response));
        }

        $data = $response->json('data.data');

        if (! is_array($data)) {
            throw new RuntimeException("Vault KV v2 payload missing data.data for {$path} — is the mount KV v2?");
        }

        return $data;
    }

    public function get(string $key, mixed $default = null): mixed
    {
        $secrets = Cache::remember('vault.secrets', 300, fn () => $this->getSecret());

        return $secrets[$key] ?? $default;
    }
}

Register the singleton in AppServiceProvider::register():

public function register(): void
{
    $this->app->singleton(\App\Services\VaultService::class);
}

Quick test:

php artisan tinker
>>> app(\App\Services\VaultService::class)->getSecret();
// ["DB_PASSWORD" => "...", "MAIL_PASSWORD" => "..."]

Part 12A — Startup order and behavior when Vault is sealed

1. Vault storage available (volume mounted)
2. Vault process up (may be sealed)
3. Operator unseal OR auto-unseal succeeds  →  Vault API ready
4. vault-agent starts, AppRole login, templates render
5. laravel entrypoint waits for /run/secrets/* , exports env
6. php-fpm / octane / queue workers start
7. Traefik routes traffic (only after app health OK)

Do not treat Compose healthy as “secrets ready.” With the Part 5 healthcheck, sealed Vault is still healthy (API up) so Traefik can discover it for unseal. Prefer depends_on: condition: service_healthy only for “API reachable,” plus application-level checks that fail closed while sealed.

Part 12 — AppServiceProvider register() pattern (not boot())

To inject Vault secrets into the database config, set them before anything opens a MySQL connection. Laravel connections are lazy — the danger is any code that touches DB (or Eloquent) while your password in config is still empty.

<?php

namespace App\Providers;

use App\Services\VaultService;
use Illuminate\Support\Facades\Config;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(VaultService::class);

        if (config('vault.enabled')) {
            $vault = $this->app->make(VaultService::class);
            $secrets = $vault->getSecret();

            Config::set('database.connections.mysql.password', $secrets['DB_PASSWORD'] ?? '');
            Config::set('mail.mailers.smtp.password', $secrets['MAIL_PASSWORD'] ?? '');
        }
    }

    public function boot(): void
    {
        //
    }
}

Never put the root token in .env or Laravel. AppRole with a read-only policy is the correct machine identity. The root token is for break-glass admin only.

Laravel bootstrap layers and what cannot come from Vault late

Laravel boots in a fixed order. Vault HTTP pull can only safely patch config that is consumed lazily (first DB query, first mail send). Anything the framework needs while it is still constructing the application is too early for register().

Part 13 — Day-two operations: backup, unseal, rotation, audit

Vault backup and recovery runbook (file storage)

Part 13 introduced backup; this is the full drill for single-node file backend on a dedicated Vault host.

Backup (scheduled)

1. Announce maintenance or rely on HA read replica if you add Raft later.
2. docker compose stop vault — ensures consistent filesystem.
3. Archive volume: tar czf vault-$(date +%F).tar.gz from ro mount (Part 13 command).
4. Record SHA256; copy off-host; include Shamir share inventory (not in the same bag as ciphertext).
5. docker compose start vault → unseal → verify vault status.

Recovery (disaster drill on staging)

1. Provision clean VM; install Docker; restore vault/config from git.
2. Create empty volume; extract tar into /vault/file mount path.
3. Start Vault — expect Sealed: true, Initialized: true.
4. Submit Shamir threshold; verify KV paths and AppRole login.
5. Point staging Laravel Agent at restored Vault; run application smoke tests.
6. Document RTO/RPO actually observed.

Backup the Vault data volume

Secrets live in the Docker volume mounted at /vault/file. Compose prefixes volume names with the project directory unless you set name:. Discover the real name before you copy-paste:

docker volume ls | grep vault
# Example name: vault-stack_vault_data  (project folder "vault-stack")

mkdir -p backups
docker run --rm \
  -v vault-stack_vault_data:/data:ro \
  -v "$(pwd)/backups:/backup" \
  alpine tar czf /backup/vault-$(date +%Y%m%d).tar.gz -C /data .
docker compose start vault
# Shamir: submit the threshold. Transit: verify automatic unseal.

# tar normally prints nothing on success
$ echo $?
0
$ ls -lh backups/vault-20260830.tar.gz
-rw-r--r-- 1 operator operator 12M Aug 30 14:20 backups/vault-20260830.tar.gz

Test restore on an isolated staging host before an emergency. For Shamir: extract to an empty volume, start a compatible Vault version, and use the same Shamir shares. For Transit: restore/verify the Unseal Vault first, configure the target with the same Transit key and CA trust, restore target data, and confirm it auto-unseals. Raft uses the snapshot save/restore procedure in Part 6, not a live volume tar.

Enable an audit device

Without audit, you cannot answer “who read secret/data/laravel/app last night?” Vault HMAC-hashes secret values in audit logs by default; you still protect the log file (it reveals paths, tokens as HMAC, and client IPs).

docker exec vault vault audit enable file file_path=/vault/file/audit.log

Success! Enabled the file audit device at: file/

That path sits on the data volume (simple lab). Production often ships audit to a separate volume or socket so a full disk on audit cannot stall Vault — if the audit device cannot write, Vault refuses requests by design. Monitor disk. Do not log audit to the same place you consider “untrusted.”

Restart runbooks: choose by seal type

Shamir

1. Query the specific node with vault status; after process restart, Sealed: true is expected.
2. Have the configured threshold of custodians submit different shares interactively. In a Shamir Raft cluster, each restarted node must be unsealed; shares are not broadcast between peers.
3. Confirm Seal Type shamir and Sealed false before restarting dependent Laravel workers.

Transit auto-unseal

1. Confirm the Unseal Vault is already initialized, unsealed, healthy, and reachable from the target node.
2. Restart the target; do not enter recovery shares.
3. Confirm Seal Type transit and Sealed false on that specific node. If sealed, inspect target logs for token, transit/decrypt/autounseal, CA, certificate-name, DNS, and timeout errors.
4. For Raft, check every node directly plus raft list-peers; a healthy load balancer endpoint does not prove every peer unsealed.

Rotate the AppRole Secret ID

docker exec vault vault write -f auth/approle/role/laravel/secret-id

Key                   Value
---                   -----
secret_id             <redacted>
secret_id_accessor    <redacted>
secret_id_num_uses    0
secret_id_ttl         0s

Update VAULT_SECRET_ID in your deploy environment. No code changes. Consider a calendar reminder every 90 days.

Rotate application secrets in KV

docker exec -it vault vault kv put secret/laravel/app \
  DB_PASSWORD="new-rotated-password" \
  MAIL_PASSWORD="new-smtp-password"

===== Secret Path =====
secret/data/laravel/app

======= Metadata =======
Key                Value
---                -----
created_time       2026-08-30T14:30:00.000Z
deletion_time      n/a
destroyed          false
version            2

KV v2 put replaces the entire key map for that path. If you omit MAIL_PASSWORD, it disappears from the latest version (older versions still exist until max_versions drops them). After rotation: restart PHP-FPM / Octane / queue workers. cache:forget only helps the get() helper in processes that still have old Config::set values until they recycle.

php artisan cache:forget vault.secrets
# then restart php-fpm or the app container

Rotate Vault’s barrier encryption key

This operation rotates Vault’s internal data-encryption key; it does not rotate Shamir shares, recovery shares, the Transit auto-unseal key, AppRole credentials, or application secrets. Existing ciphertext is rewrapped as touched; new writes use the new key version.

docker exec vault vault write -f sys/rotate
docker exec vault vault read sys/key-status

Success! Data written to: sys/rotate

Key             Value
---             -----
term            2
install_time    2026-08-30T14:40:00.000000000Z
encryptions     0

Start small

Vault high-value secrets first: database passwords, payment API keys, encryption keys. Leave APP_NAME and APP_ENV in .env. Keep APP_KEY out of late HTTP pull (Part 12). You do not need to move your entire config on day one.

Part 13A — Runtime secrets vs non-sensitive configuration

Rule: If compromise would grant data access or forgery (money, PII, sessions), it is a runtime secret. If it only describes topology or behavior, keep it in Compose and version control.

Part 14 — Master parameter reference

Server (config.hcl + process env)

Init / AppRole / KV / Laravel (short)

Part 15 — Troubleshooting and production checklist

Work top-down: Traefik reachability → Vault sealed state → policy/AppRole → Laravel VAULT_ADDR → config timing.

End-to-end verification

1. https://vault.example.com shows the Vault UI
2. docker exec vault vault status → Sealed: false
3. docker exec vault vault kv get secret/laravel/app returns your keys
4. From the app: app(VaultService::class)->getSecret() succeeds
5. App authenticates to MySQL with the Vault-sourced password

Production checklist

1. config.hcl: api_addr = public HTTPS URL; cluster_addr = http://127.0.0.1:8201; disable_mlock = true
2. Compose: cap_add: [IPC_LOCK], healthcheck (exit 0 or 2), entrypoint with -config=/vault/config/config.hcl, VAULT_ADDR=http://127.0.0.1:8200
3. Traefik: traefik.enable=true, service port 8200, shared edge network, ACME resolver; no discovery until Vault is healthy
4. Seal branch selected: runbook explicitly says Shamir or Transit; operators never treat recovery shares as auto-unseal shares
5. Shamir branch: unseal shares held by separate custodians; chosen threshold justified by absence/compromise tolerance; each-node Raft unseal and restart drill tested
6. Transit branch: dedicated independently bootable Unseal Vault; TLS verification on; exact encrypt/decrypt update policy; periodic orphan token in a protected read-only file; cold-start drill tested
7. Transit custody: target recovery shares offline; Unseal Vault Shamir shares offline; token accessors recorded; no token literal in HCL, Compose, image, logs, or repository
8. No circular dependency: Unseal Vault DNS, TLS, storage, host boot, and credentials do not require the target Vault
9. Root token: not used in Laravel; revoked or locked down after AppRole setup
10. Policy: secret/data/laravel/* read-only; name laravel matches AppRole token_policies
11. AppRole: Role ID in .env; Secret ID injected at deploy; token_ttl set explicitly (not 0); rotation scheduled
12. Laravel VAULT_ADDR: http://vault:8200 in Compose; https://vault.example.com on host
13. Laravel flag: VAULT_ENABLED + config('vault.*') only (no raw env() in services)
14. Config timing: Config::set() in register(), not boot(); APP_KEY not from late KV pull
15. Workers: restart FPM/Octane/queue after KV rotation; Octane token TTL vs worker lifetime
16. Backup: stopped volume snapshot (file) or Raft snapshot; checksum/off-host retention; isolated restore tested with the matching Shamir or Transit dependency set
17. Raft + Transit: identical seal stanza/key/CA on every node; unique node IDs; status checked per node; snapshot and quorum restore tested
18. Audit: file (or socket) device enabled; disk monitored (failed audit blocks requests)
19. Monitoring: Shamir alerts respect the documented operator window; Transit sealed-at-start alerts immediately and includes Unseal Vault, token renewal, TLS expiry, and Transit audit health
20. No extra packages: use Illuminate\Support\Facades\Http (Guzzle already included)

Wrapping up

You now have a production-minded pattern and a map of the alternatives:

1. Layers — host, Docker, storage, seal, listener, auth, token, policy, engine, audit, Traefik, Laravel bootstrap
2. Lab methodology — file storage, Shamir unseal, AppRole, HTTP pull in register(), Traefik for HTTPS
3. Parameters — each important knob has a default, a failure mode, and a recommended setting (Parts 4, 8, 11, 14)
4. Production options — Agent templates, Kubernetes/JWT auth, self-hosted Transit auto-unseal, Raft, dynamic DB leases, and Enterprise PKCS#11 where licensed

Your .env gets thinner. Secrets get a real home. And when someone asks where the production database password lives, you point at Vault — not a Slack message from six months ago.