Parameters

VAULT provides eight parameters in two groups:

• VAULT: five parameters for deployment and configuration.
• VAULT_REMOVE: three parameters controlling cluster removal.

VAULT deliberately exposes few settings. Member count determines cluster mode, HA access reuses NODE’s VIP parameters, and other ports, directories, engines, and backup policies follow fixed conventions.

Parameter Overview

The VAULT group configures instance identity, cluster name, data directory, port, and service domain.

The VAULT_REMOVE group controls removal safeguards, data cleanup, and package removal.

VAULT

This section lists parameters for the vault role, used by the vault.yml playbook.

They are defined in roles/vault/defaults/main.yml.

#vault_seq: 1                     # Required vault instance identifier
vault_cluster: vault              # Cluster name, default vault
vault_data: /data/vault           # Data directory for Raft storage and local snapshots
vault_port: 8200                  # API port; Raft cluster port is this value +1
vault_domain: vault.pigsty        # Service domain for certificate SANs and all clients

vault_seq

Name: vault_seq, type: int, level: I

Required VAULT instance number. Assign every member a nonnegative integer unique within the group.

The instance name is <vault_cluster>-<vault_seq>, for example vault-1. It is also the Raft node ID, server certificate CN, and monitoring label ins.

The member with the lowest vault_seq performs initial cluster initialization. Keep instance numbers immutable once assigned; do not reuse them for other nodes.

vault:
  hosts:
    10.10.10.11: { vault_seq: 1 }  # vault-1 performs initial initialization
    10.10.10.12: { vault_seq: 2 }  # vault-2
    10.10.10.13: { vault_seq: 3 }  # vault-3

The playbook verifies that every vault_seq is a nonnegative integer unique in the vault group, stopping immediately on failure.

vault_cluster

Name: vault_cluster, type: string, level: C

VAULT cluster name, default vault.

Used as the instance name prefix, OpenBao cluster_name, and monitoring label cls, and in generating the seal key ID.

The Ansible group name is hardcoded as vault, independently of vault_cluster. Each Pigsty deployment has one VAULT cluster; this parameter usually needs no change.

vault_data

Name: vault_data, type: path, level: C

VAULT data directory, default /data/vault.

Contains raft/ for Raft storage and backup/ for local snapshots.

Use a dedicated absolute path at least two levels deep, such as /data/vault, with no .. components. Removal deletes the entire directory; never point it at a shared parent such as /var/lib.

vault_port

Name: vault_port, type: port, level: G

VAULT API port, default 8200.

The Raft cluster port is fixed at vault_port + 1, default 8201. This follows OpenBao’s convention and has no separate parameter.

Clients, HAProxy, and monitoring all use this port. Do not change it after creating the cluster.

vault_domain

Name: vault_domain, type: string, level: G

VAULT service domain, default vault.pigsty.

Included in every member’s server certificate SAN. All clients should use https://<vault_domain>:<vault_port>.

Pigsty does not resolve this name automatically. Use node_etc_hosts to point it to the single member or the three-member cluster’s VIP; see Service Domain.

VAULT_REMOVE

This section lists parameters for the vault_remove role, used by the vault-rm.yml playbook.

They are defined in roles/vault_remove/defaults/main.yml.

vault_safeguard: true             # Removal safeguard, default true
vault_rm_data: true               # Delete vault data and configuration? Default true
vault_rm_pkg: false               # Uninstall openbao? Default false

vault_safeguard

Name: vault_safeguard, type: bool, level: G/C/A

VAULT removal safeguard, default true. When enabled, vault-rm.yml aborts before taking any action.

Like MYSQL’s mysql_safeguard, this safeguard is enabled by default. Deleting VAULT destroys all keys it stores: databases, objects, and all their backups encrypted with those keys become permanently unreadable.

To remove it, explicitly override the parameter on the command line:

./vault-rm.yml -l <exact-target> -e vault_safeguard=false   # Override only after verifying the target and snapshot

vault_rm_data

Name: vault_rm_data, type: bool, level: G/C/A

Delete VAULT data and configuration during removal? Default true.

Deletes /etc/openbao on members, including local copies of TLS certificates, the seal key, and backup token; the vault_data directory, including local snapshots; the systemd unit, client environment, log rotation configuration, and vault-backup script.

When removing the whole cluster with this enabled, the playbook first takes a final snapshot and retrieves it to files/pki/vault/backup/ on the admin node. Failure aborts removal.

Regardless of this setting, files/pki/vault/ on the admin node and /var/log/openbao/ audit logs on members are never deleted.

./vault-rm.yml -l 10.10.10.13 -e vault_safeguard=false -e vault_rm_data=false  # Stop service while retaining data

vault_rm_pkg

Name: vault_rm_pkg, type: bool, level: G/C/A

Uninstall openbao during removal? Default false.

./vault-rm.yml -l vault -e vault_safeguard=false -e vault_rm_pkg=true  # Also uninstall the package

Related Parameters

VAULT reuses existing parameters for HA access and domain resolution:

Fixed Conventions

The following conventions have no configurable parameters: