Short, accurate documentation for this formula.

This formula installs and configures HashiCorp Vault, supports:

• Binary installation (specified via pillar['vault']['version']) — downloads official Vault zip and installs /usr/bin/vault.
• APT installation (legacy) following HashiCorp apt repository instructions.
• Setting capabilities (CAP_IPC_LOCK, CAP_NET_BIND_SERVICE) so Vault can bind to privileged ports (443).
• Snapshot creation
• Restore from snapshot, initialization, unseal, and full wipe workflows.

• init.sls — install/config (binary and apt branches)
• initialization.sls — runs vault operator init and stores JSON on the Vault host
• unseal.sls — unseal logic using pillar['vault']['unseal_keys']
• audit.sls — enable/disable audit logging to file
• remove_init_files.sls — cleanup of init JSON files after keys are safely stored in pillar
• root_token_file.sls — create /root/.vault-token with root token for quick authentication
• restore.sls — restore snapshot workflow
• wipe.sls — destructive reinstall + wipe

vault:
  version: '1.21.1'          # optional — if present, binary install is used
  privileged_token: '...'
  unseal_keys:
    - 'AAA...='
    - 'BBB...='
    - 'CCC...='
  env_vars:
    VAULT_ADDR: 'https://127.0.0.1:8200'
  init:
    key_shares: 5
    key_threshold: 3
    output_file: /opt/vault/init-temp.json
  restore:
    snapshot_path: /opt/vault/snapshots/vault_YY-MM-DD.snap
    unseal_keys:                  # optional: keys to use only for restore
      - 'ZZZ...='

• With binary: set vault.version in pillar. The formula downloads the specified release zip from releases.hashicorp.com, extracts only the vault binary to /usr/bin/vault, sets perms and capabilities, and creates systemd unit.
• With apt: omit vault.version. The formula follows the official apt repo setup (signed-by keyring) and installs vault package.

• Prerequisite: apply vault.init first (installs binary/package, writes config/env, systemd unit, and starts the service).

salt-ssh 'target' state.apply vault.init
salt-ssh 'target' state.apply vault.initialization

• The vault.initialization state runs vault operator init -format=json only when Vault is not initialized. It saves JSON to /opt/vault/init-temp.json, and prints a pillar-ready YAML snippet to stdout so you can copy it into your pillar.

• vault.unseal reuses pillar['vault']['unseal_keys'].
• During restore, if vault.restore.unseal_keys is provided, those keys will be used for autounsealing restored storage.

• Requirements: pillar['vault']['restore']['snapshot_path'] must be set.
• Behavior:
  • Includes vault.unseal so unseal states are available.
  • Stops/starts vault service appropriately, runs vault operator raft snapshot restore with provided snapshot_path.
  • After restore, it performs unseal steps using vault.restore.unseal_keys.
• Important: Vault must be reachable and the privileged token available in pillar for operations that require authentication.

• Stops Vault, deletes configured data path /opt/vault/data, removes package or binary depending on install mode, then includes vault.init and vault.initialization to reinstall and re-init.

• Enable or disable audit logging via pillar:

  vault:
    audit:
      enable: true
      file: /var/log/vault_audit.log

• Apply the state:

  salt-ssh 'target' state.apply vault.audit

• Requires privileged_token in pillar for authentication.
• Audit logs are written to the specified file in JSON format.

• After initialization, store your privileged_token in pillar and apply:

  salt-ssh 'target' state.apply vault.root_token_file

• Creates /root/.vault-token with mode 600, allowing root to run Vault commands without manually providing VAULT_TOKEN:

  sudo vault status  # will automatically use /root/.vault-token

• After safely copying the JSON output from vault.initialization into your pillar, remove the temporary init file:

  salt-ssh 'target' state.apply vault.remove_init_files

• Deletes /opt/vault/init-temp.json by default (configurable via init.output_file).
• Recommended: do this only after you have verified the keys are stored in a safe location (pillar, sealed backup, etc.).

• The formula always creates /etc/systemd/system/vault.service.d/capabilities.conf with:

  [Service]
  CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK CAP_NET_BIND_SERVICE
  AmbientCapabilities=CAP_NET_BIND_SERVICE
  

• The Vault binary receives capabilities via setcap so binding to port 443 works on both install methods.

# Check Vault status (sealed/unsealed, cluster info)
vault status

# Check if Vault is initialized
vault status -format=json | jq -r '.initialized'

# Check if Vault is sealed
vault status -format=json | jq -r '.sealed'

# Health check endpoint
curl -k https://localhost:8200/v1/sys/health

# Leader status
curl -sk https://localhost:8200/v1/sys/leader | jq

# List Raft peers
vault operator raft list-peers

# Show cluster configuration
vault read sys/storage/raft/configuration

# Check if node is leader
vault read sys/leader

# List snapshots directory
ls -lah /opt/vault/snapshots/

# Verify snapshot integrity
vault operator raft snapshot inspect /opt/vault/snapshots/vault_latest.snap

# Manually create snapshot
vault operator raft snapshot save /tmp/manual-backup.snap

# Check Vault config file
cat /etc/vault.d/vault.hcl

# Verify environment variables
cat /etc/vault.d/vault.env

# Check if VAULT_ADDR is set in current shell
echo $VAULT_ADDR

# Test network connectivity to Vault
curl -k -I -L https://localhost:8200

# Test TLS connection
openssl s_client -connect localhost:8200 -showcerts

# Check audit device status
vault audit list

# View audit log (if file backend enabled)
tail -f /var/log/vault_audit.log | jq

# Login with root token
vault login

# Check token info
vault token lookup

# Renew current token
vault token renew

# List token accessors
vault list auth/token/accessors

# List enabled secrets engines
vault secrets list

# Check secrets engines
vault secrets list -detailed 

# Prometheus metrics endpoint (if enabled)
curl -sk https://localhost:8200/v1/sys/metrics?format=prometheus