This deployment guide covers the steps required to install and configure a single HashiCorp Vault cluster as defined in the Vault with Integrated Storage Reference Architecture. Although not a strict requirement to follow the Vault Reference Architecture, please ensure you are familiar with the overall architecture design; for example, installing Vault on multiple physical and/or virtual hosts for high-availability with correct anti-affinity.
You should also review and apply the recommendations provided in the Vault Production Hardening guide during the installation.
We recommend that the Vault service be deployed to more than one host to provide a highly-available, single cluster architecture as shown in the Vault with Integrated Storage Reference Architecture.
The following setup steps should be completed on all of the Vault hosts:
- Download Vault Binaries
- Install Vault
- Configure Vault Service
- Configure Vault Process
- Start Vault Service
»Step 1: Download Vault Binaries
Precompiled Vault OSS and Enterprise binaries are available for download at https://releases.hashicorp.com/vault/. Find the appropriate package for your system an download it. Vault is packaged as a ZIP file.
You should perform checksum verification of the zip packages to validate your
package using the SHA256SUMS
and SHA256SUMS.sig
files available for the
specific release version. HashiCorp provides a guide on checksum verification for precompiled binaries.
First, export some environment variables to specify the Vault download base URL
and preferred Vault version for convenience and concise commands. Then use
curl
to download the package and SHA256 summary files.
$ export VAULT_URL="https://releases.hashicorp.com/vault" \
VAULT_VERSION="1.4.0"
$ curl \
--silent \
--remote-name \
"${VAULT_URL}/${VAULT_VERSION}/vault_${VAULT_VERSION}_linux_amd64.zip"
$ curl \
--silent \
--remote-name \
"${VAULT_URL}/${VAULT_VERSION}/vault_${VAULT_VERSION}_SHA256SUMS"
$ curl \
--silent \
--remote-name \
"${VAULT_URL}/${VAULT_VERSION}/${VAULT_VERSION}/vault_${VAULT_VERSION}_SHA256SUMS.sig"
You should now have the 3 files present locally:
$ ls -1
vault_1.4.0_SHA256SUMS
vault_1.4.0_SHA256SUMS.sig
vault_1.4.0_linux_amd64.zip
»Step 2: Install Vault
Unzip the downloaded package, move the vault
binary to /usr/local/bin/
, and
check that vault
is available on the system path.
$ unzip vault_${VAULT_VERSION}_linux_amd64.zip
$ sudo chown root:root vault
$ sudo mv vault /usr/local/bin/
$ vault -version
Vault v1.4.0+ent
The vault
command features opt-in autocompletion for flags, subcommands, and
arguments (where supported).
$ vault -autocomplete-install
$ complete -C /usr/local/bin/vault vault
Give vault
the ability to use the mlock syscall without running the process as
root
. The mlock syscall prevents memory from being swapped to disk.
$ sudo setcap cap_ipc_lock=+ep /usr/local/bin/vault
Create a unique, non-privileged system user to run vault
.
$ sudo useradd --system --home /etc/vault.d --shell /bin/false vault
»Step 3: Configure Vault Service
Vault uses documented defaults so only non-default values should be set in the configuration file.
Create a configuration file at /etc/vault.d/vault.hcl
:
$ sudo mkdir --parents /etc/vault.d
$ sudo touch /etc/vault.d/vault.hcl
$ sudo chown --recursive vault:vault /etc/vault.d
$ sudo chmod 640 /etc/vault.d/vault.hcl
»Listener stanza
The listener
stanza configures the addresses and ports on which Vault will
respond to requests.
Add the below configuration to the Vault configuration file:
listener "tcp" {
address = "0.0.0.0:8200"
tls_cert_file = "/path/to/fullchain.pem"
tls_key_file = "/path/to/privkey.pem"
}
The following parameters are set for the tcp
listener stanza:
address
(string: "127.0.0.1:8200")
- Changing from the loopback address to allow external access to the Vault UItls_cert_file
(string: <required-if-enabled>, reloads-on-SIGHUP)
- Must be set when using TLStls_key_file
(string: <required-if-enabled>, reloads-on-SIGHUP)
- Must be set when using TLS
More information about tcp listener configuration.
Vault should always be configured to use TLS to provide secure communication between clients and the Vault cluster. This requires a certificate file and key file be installed on each host running Vault. The certificate file and key file must have permissions allowing the vault user/group to read them.
»Seal stanza
The seal
stanza in the Vault configuration specifies the seal type to use for
additional data protection such as using hardware security module (HSM) or Cloud
KMS solutions to encrypt and decrypt the Vault master key to automatically
unseal Vault. This stanza is optional, and if this is not configured, Vault will
use the Shamir algorithm to cryptographically split the master key.
Review the seal configuration documentation for more detail.
An example PKCS #11 compatible HSM example is:
seal "pkcs11" {
lib = "/usr/vault/lib/libCryptoki2_64.so"
slot = "0"
pin = "AAAA-BBBB-CCCC-DDDD"
key_label = "vault-hsm-key"
hmac_key_label = "vault-hsm-hmac-key"
}
NOTE: HSM integration is only available with Vault Enterprise with Governance & Policy module. Use the supported cloud KMS solutions with OSS Vault.
»Storage stanza
Vault will store state and its encrypted data to the configured directory in the
storage
stanza in the Vault configuration file. The path below is a sample and
suggestion and can be changed to another location if necessary.
The following parameters are set for the raft
storage stanza:
path
- The file system path where all the Vault data gets storednode_id
- The identifier for the node in the Raft clusterretry_join
- (Optional) Enables the node to automatically join a raft cluster during the bootstrap.
Beginning with Vault v1.6.0, Integrated Storage supports cloud auto-join for cloud-hosted clusters. When the IP addresses of the Vault nodes are not static, cloud auto-join can be used to discover the potential leader node address based on the cloud provider-specific configurations.
Refer to the Vault HA Cluster with Integrated Storage on AWS tutorial for a step-by-step instruction.
It is recommended that this directory be created as follows:
$ sudo mkdir /opt/raft
$ sudo chown -R vault:vault /opt/raft
Add the below configuration to the /etc/vault.d/vault.hcl
file:
storage "raft" {
path = "/opt/raft"
node_id = "raft_node_1"
}
Review the documentation on integrated storage for additional configuration specifics.
»Telemetry stanza
The telemetry
stanza specifies various configurations for Vault to publish
metrics to upstream systems.
If you decide to configure Vault to publish telemetry data, you should review the telemetry configuration section of our documentation.
»High Availability Parameters
The api_addr
parameter configures the API address used in high availability
scenarios, when client redirection is used instead of request forwarding. Client
redirection is the fallback method used when request forwarding is turned off or
there is an error performing the forwarding. As such, a redirect address is
always required for all HA setups.
This parameter value defaults to the address
specified in the listener
stanza, but Vault will log a [WARN]
message if it is not explicitly
configured.
Add the below configuration to the Vault configuration file:
api_addr = "{{ full URL to Vault API endpoint }}"
More information about high availability configuration.
»Vault UI
Vault features a web-based user interface, allowing you to easily create, read, update, and delete secrets, authenticate, unseal, and more using a graphical user interface, rather than the CLI or API.
Vault should not be deployed in a public internet facing environment, so enabling the Vault UI is typically of benefit to provide a more familiar experience to administrators who are not as comfortable working on the command line, or who do not have alternative access.
Optionally, add the below configuration to the Vault configuration file to enable the Vault UI:
ui = true
More information about configuring the Vault UI.
»Step 4: Configure Vault Process
»Configure systemd
Systemd uses documented defaults so only non-default values must be set in the configuration file.
Create a Vault service file at /etc/systemd/system/vault.service
.
$ sudo touch /etc/systemd/system/vault.service
Add the below configuration to the Vault service file:
[Unit]
Description="HashiCorp Vault - A tool for managing secrets"
Documentation=https://www.vaultproject.io/docs/
Requires=network-online.target
After=network-online.target
ConditionFileNotEmpty=/etc/vault.d/vault.hcl
StartLimitIntervalSec=60
StartLimitBurst=3
[Service]
User=vault
Group=vault
ProtectSystem=full
ProtectHome=read-only
PrivateTmp=yes
PrivateDevices=yes
SecureBits=keep-caps
AmbientCapabilities=CAP_IPC_LOCK
Capabilities=CAP_IPC_LOCK+ep
CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
NoNewPrivileges=yes
ExecStart=/usr/local/bin/vault server -config=/etc/vault.d/vault.hcl
ExecReload=/bin/kill --signal HUP $MAINPID
KillMode=process
KillSignal=SIGINT
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
LimitNOFILE=65536
LimitMEMLOCK=infinity
[Install]
WantedBy=multi-user.target
The following parameters are set for the [Unit]
stanza:
Description
- Free-form string describing the vault serviceDocumentation
- Link to the vault documentationRequires
- Configure a requirement dependency on the network serviceAfter
- Configure an ordering dependency on the network service being started before the vault serviceConditionFileNotEmpty
- Check for a non-zero sized configuration file before vault is startedStartLimitIntervalSec
,StartLimitBurst
- Limit vault to three start attempts in 60 seconds (support for systemd version 230+)
The following parameters are set for the [Service]
stanza:
User
,Group
- Run vault as the vault userProtectSystem
,ProtectHome
,PrivateTmp
,PrivateDevices
- Sandboxing settings to improve the security of the host by restricting vault privileges and accessSecureBits
,Capabilities
,CapabilityBoundingSet
,AmbientCapabilities
- Configure the capabilities of the vault process (support for multiple systemd versions)NoNewPrivileges
- Prevent vault and any child process from gaining new privilegesExecStart
- Start vault with theserver
argument and path to the configuration fileExecReload
- Send vault a HUP signal to trigger a configuration reload in vaultKillMode
- Treat vault as a single processKillSignal
- Send SIGINT signal when shutting down vaultRestart
- Restart vault (in a sealed state) unless it returned a clean exit codeRestartSec
- Restart vault after 5 seconds of it being considered 'failed'TimeoutStopSec
- Wait 30 seconds for a clean stop before sending a SIGKILL signalLimitNOFILE
,LimitMEMLOCK
- Limit the number of file descriptors to the configured value and prevent memory being swapped to disk
The following parameters are set for the [Install]
stanza:
WantedBy
- Creates a weak dependency on vault being started by the multi-user run level
»Step 5: Start Vault Service
Enable and start Vault using the systemctl
command responsible for controlling
systemd managed services. Check the status of the vault service using systemctl.
$ sudo systemctl enable vault
$ sudo systemctl start vault
$ sudo systemctl status vault
The Vault UI and API should be accessible and running once the above steps have been completed. Browse to http://127.0.0.1:8200 and view the Vault UI to confirm success.
Once Vault is started on the leader node you will need to:
- Unseal Vault on leader
- Join followers to raft cluster by running the following command on each follower cluster instance you wish to join to Vault cluster
$ vault operator raft join https://<IP of Leader>:8200
Key Value
--- -----
Joined true
If the Vault node connection details are known in advance, you can configure
them to connect during bootstrap to automatically join the raft cluster. For
more information, please see the retry_join
configuration for the raft
storage stanza.
»Help and Reference
NOTE: Refer to the Vault High Availability with Integrated Storage tutorial for step-by-step HA cluster deployment example.