HCPEarn a free $50 credit for HCP Vault or HCP Consul today. Get Started

Vault with Integrated Storage Deployment Guide

This deployment guide outlines the required steps to manually install and configure a single HashiCorp Vault cluster as defined in the Vault with Integrated Storage Reference Architecture on virtual machines (VMs) or bare-metal servers running a Debian- or RedHat-based Linux distribution.

This guide includes general guidance as well as specific recommendations for popular cloud infrastructure platforms. These recommendations have also been encoded into official Terraform modules for AWS, Azure, and GCP.

»Install Vault

Pre-built Vault packages are available from the HashiCorp Linux Repository. In addition to the installing the Vault binary, the official package also seeds Vault with a working configuration, a systemd service unit, and a local vault user account under which the service will be run.

Add the HashiCorp GPG key as a trusted package-signing key.

$ curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -

$ curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -

Add the official HashiCorp Linux repository.

$ sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main"

$ sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main"

Update the package index.

$ sudo apt update

$ sudo apt update

Install Vault.

$ sudo apt install vault-enterprise

$ sudo apt install vault-enterprise

»Prepare TLS certificates

You must have three files to configure TLS for Vault. Place them at these paths:

  • /opt/vault/tls/vault-cert.pem - The Vault TLS certificate itself, which a Common Name (CN) or Subject Alternative Name (SAN) that matches the value set for leader_tls_servername in the Raft configuration. If this file was signed by an intermediate CA, append the certificate of that CA (and any other chained CAs) to the end of this file.
  • /opt/vault/tls/vault-key.pem - The private key of the Vault TLS certificate.
  • /opt/vault/tls/vault-ca.pem - The certificate of the CA root which signed the Vault TLS certificate.

Set the file ownership of the CA and certificate files to be owned by root.

$ sudo chown root:root /opt/vault/tls/vault-cert.pem /opt/vault/tls/vault-ca.pem

$ sudo chown root:root /opt/vault/tls/vault-cert.pem /opt/vault/tls/vault-ca.pem

Set the file group ownership of the private key to allow the Vault service to read the file.

$ sudo chown root:vault /opt/vault/tls/vault-key.pem

$ sudo chown root:vault /opt/vault/tls/vault-key.pem

Set the file permissions of the CA and certificate files to be world-readable.

$ sudo chmod 0644 /opt/vault/tls/vault-cert.pem /opt/vault/tls/vault-ca.pem

$ sudo chmod 0644 /opt/vault/tls/vault-cert.pem /opt/vault/tls/vault-ca.pem

Set the file permissions of the private key file to be readable only by the Vault service.

$ sudo chmod 0640 /opt/vault/tls/vault-key.pem

$ sudo chmod 0640 /opt/vault/tls/vault-key.pem

»Configure Vault

Vault may be configured by editing the /etc/vault.d/vault.hcl file included with the installation package. Refer to the Vault Configuration Overview for additional details about each setting.

»Base configuration

The core required configuration values for Vault are cluster_addr, api_addr, and listener. The configuration below tells vault to advertise its local IPv4 address for internal communication, and to listen to TCP port 8200 on all network interfaces using the TLS configuration files specified.

The configuration also sets disable_mlock to true, which is strongly recommended for the integrated storage backend to avoid out-of-memory errors.

cluster_addr  = "https://<LOCAL_IPV4_ADDRESS>:8201"
api_addr      = "https://<LOCAL_IPV4_ADDRESS>:8200"
disable_mlock = true

listener "tcp" {
  address            = "0.0.0.0:8200"
  tls_cert_file      = "/opt/vault/tls/vault-cert.pem"
  tls_key_file       = "/opt/vault/tls/vault-key.pem"
  tls_client_ca_file = "/opt/vault/tls/vault-ca.pem"
}
/etc/vault.d/vault.hcl
cluster_addr  = "https://<LOCAL_IPV4_ADDRESS>:8201"api_addr      = "https://<LOCAL_IPV4_ADDRESS>:8200"disable_mlock = true
listener "tcp" {  address            = "0.0.0.0:8200"  tls_cert_file      = "/opt/vault/tls/vault-cert.pem"  tls_key_file       = "/opt/vault/tls/vault-key.pem"  tls_client_ca_file = "/opt/vault/tls/vault-ca.pem"}

»Raft configuration

Using Vault integrated storage requires configuring the Raft storage backend. Raft peers may be initialized manually, with hard-coded configuration values, or via the cloud auto-join feature on supported cloud providers. Refer to the Integrated Storage configuration documentation for additional details about each setting.

To use Raft auto-join on AWS, each Vault EC2 instance must be tagged with a key-value pair that is unique to its specific Vault cluster. The instances must also have appropriate permissions via an IAM role attached to their instance profile. See the Cloud auto-join documentation for more details about the format of the auto_join configuration value and the permissions required.

storage "raft" {
  path    = "/opt/vault/data"
  node_id = "<UNIQUE_ID_FOR_THIS_HOST>"

  retry_join {
    auto_join               = "provider=aws region=<AWS_REGION> tag_key=<VAULT_TAG_NAME> tag_value=<VAULT_TAG_VALUE>"
    auto_join_scheme        = "https"
    leader_tls_servername   = "<VALID_TLS_SERVER_NAME>"
    leader_ca_cert_file     = "/opt/vault/tls/vault-ca.pem"
    leader_client_cert_file = "/opt/vault/tls/vault-cert.pem"
    leader_client_key_file  = "/opt/vault/tls/vault-key.pem"
  }
}
/etc/vault.d/vault.hcl
storage "raft" {  path    = "/opt/vault/data"  node_id = "<UNIQUE_ID_FOR_THIS_HOST>"
  retry_join {    auto_join               = "provider=aws region=<AWS_REGION> tag_key=<VAULT_TAG_NAME> tag_value=<VAULT_TAG_VALUE>"    auto_join_scheme        = "https"    leader_tls_servername   = "<VALID_TLS_SERVER_NAME>"    leader_ca_cert_file     = "/opt/vault/tls/vault-ca.pem"    leader_client_cert_file = "/opt/vault/tls/vault-cert.pem"    leader_client_key_file  = "/opt/vault/tls/vault-key.pem"  }}

»Auto-unseal

If you are using a supported cloud provider or have access to a supported hardware security module (HSM), you can enable auto-unseal using the seal configuration stanza.

To use AWS KMS for auto-unsealing securely, your EC2 instances should have appropriate permissions to a KMS key via their instance profile. See the awskms seal documentation for full details of the configuration options and necessary permissions.

seal "awskms" {
  region     = "<AWS_REGION>"
  kms_key_id = "<KMS_KEY_ARN>"
}
/etc/vault.d/vault.hcl
seal "awskms" {  region     = "<AWS_REGION>"  kms_key_id = "<KMS_KEY_ARN>"}

»Enterprise license

Beginning with Vault 1.8, an Enterprise license file must exist on disk and be readable by the Vault service.

Copy your Vault Enterprise license file to /opt/vault/vault.hclic. Then set the file's group ownership to allow the Vault service to read the file.

$ sudo chown root:vault /opt/vault/vault.hclic

$ sudo chown root:vault /opt/vault/vault.hclic

Set the file permissions to allow the Vault service to read the file, but no other users to access the file.

$ sudo chmod 0640 /opt/vault/vault.hclic

$ sudo chmod 0640 /opt/vault/vault.hclic

Add the path to the Enterprise license file to /etc/vault.d/vault.hcl.

license_path = "/opt/vault/vault.hclic"
/etc/vault.d/vault.hcl
license_path = "/opt/vault/vault.hclic"

»Vault web UI

To enable the Vault web UI, set the ui configuration value to true.

ui = true
/etc/vault.d/vault.hcl
ui = true

»Enable and start the Vault service

Enable the systemd vault.service unit to allow the Vault service to start.

$ sudo systemctl enable vault.service

$ sudo systemctl enable vault.service

Start the Vault service.

$ sudo systemctl start vault.service

$ sudo systemctl start vault.service

Check the status of the Vault service to ensure it is running.

$ sudo systemctl status vault.service

$ sudo systemctl status vault.service

»Check the status of Vault

To ensure Vault is running, you can use the vault status command. To ensure TLS connection can be validate, first set the VAULT_CACERT environment variable to the path of the CA root certificate.

$ export VAULT_CACERT=/opt/vault/tls/vault-ca.pem

$ export VAULT_CACERT=/opt/vault/tls/vault-ca.pem

Then use vault status to see the status of the local Vault server.

$ vault status
Key                     Value
---                     -----
[...]
Storage Type            raft
[...]

$ vault statusKey                     Value---                     -----[...]Storage Type            raft[...]

»Initialize Vault

If this is the first time you are running this cluster, Vault will need to be initialized on one host before Raft clients can be joined.

$ vault operator init
Unseal Key 1: <omitted>
[...]
Initial Root Token: s.AJ8gE4odM92zW1clYbPPXpLu
[...]

$ vault operator initUnseal Key 1: <omitted>[...]Initial Root Token: s.AJ8gE4odM92zW1clYbPPXpLu[...]

Take note of these values and store them securely. You will need them to manually unseal Vault and to perform initial setup.

»Unseal Vault

If you configured auto-unseal, Vault should unseal automatically. Use the vault status command to check whether Vault is sealed.

$ vault status
Key                     Value
---                     -----
[...]
Sealed                  false
[...]

$ vault statusKey                     Value---                     -----[...]Sealed                  false[...]

If Vault is sealed, use the vault operator unseal command on each host in the cluster with the unseal keys you received when initializing Vault to unseal it.

$ vault operator unseal
Unseal Key (will be hidden): ******************************
Key                Value
---                -----
[...]
Unseal Progress    1/3
[...]

$ vault operator unsealUnseal Key (will be hidden): ******************************Key                Value---                -----[...]Unseal Progress    1/3[...]

Repeat the unseal command with new keys until the unseal progress is complete and Vault is unsealed.

»Additional configuration

»Autopilot

Integrated storage Autopilot may be configured through the Vault API. See the Autopilot tutorial for more information on each configuration value.

»Telemetry

The telemetry stanza specifies various configurations for Vault to publish metrics to upstream systems. Review the telemetry configuration section of our documentation for details on configuring Vault telemetry for your telemetry collection provider.

»Next Steps

»Additional references

Hashicorp
stdin: is not a tty