Set up Vault
- 24min
- |
- VaultVault
- VideoVideo
- InteractiveInteractive
Scenario
Danielle is on the HashiCups development team, and builds the applications and plugins which interact with Vault. They have installed the Vault binary on their computer, and can now use a Vault development (dev mode) server for development and testing.
Oliver from the operations team evaluates a self-managed Vault server, and the HashiCorp Cloud Platform (HCP) Vault Dedicated server as solutions for local user acceptance testing.
Danielle and Oliver will start and prepare their Vault servers for use, check the server status, and user their initial root token to authenticate with Vault.
Prerequisites
To complete this tutorial, you need the following:
- Vault binary installed and configured in your system PATH.
Set up the lab
Vault operates as a client-server application. The Vault server is the sole piece of the Vault architecture that interacts with the data storage and backends. All operations done using the Vault CLI interact with the server over a TLS connection.
The HashiCups team members can operate their Vault servers to achieve goals for development, testing, and pre-production.
Here are some key differences in startup and setup between each Vault server type:
Dev mode Vault | Self-managed Vault | HCP Vault Dedicated |
---|---|---|
In-memory storage backend | Configurable storage backend | Integrated storage backend |
Automatic initialization and unsealing | Requires initialization and unsealing | Automatic initialization and unsealing |
Shamir's Secret Sharing seal with a single key share | Configurable seal | Cloud auto seal |
Initial root token automatically generated or specified at runtime | Initial root token part of unseal output | No root token; generate admin tokens in HCP UI |
Choose a tab to start and prepare a dev server, self-managed server, or HCP server.
(Persona: Developer)
The dev server is a built-in, pre-configured server that is not useful for production, but is helpful if you want to use Vault in your local development environment.
Reminder: dev mode in-memory storage backend
The dev server uses an in-memory storage backend. This means that when you stop a dev server, you lose access to any data you wrote to the server.
Before you start the server, use the
vault
binary to print help with the-help
flag.$ vault server -help
$ vault server -help
Scroll to the Dev options section.
Dev Options: -dev Enable development mode. In this mode, Vault runs in-memory and starts unsealed. As the name implies, do not run "dev" mode in production. The default is false. -dev-cluster-json=<string> File to write cluster definition to -dev-listen-address=<string> Address to bind to in "dev" mode. The default is 127.0.0.1:8200. This can also be specified via the VAULT_DEV_LISTEN_ADDRESS environment variable. -dev-no-store-token Do not persist the dev root token to the token helper (usually the local filesystem) for use in future requests. The token will only be displayed in the command output. The default is false. -dev-root-token-id=<string> Initial root token. This only applies when running in "dev" mode. This can also be specified via the VAULT_DEV_ROOT_TOKEN_ID environment variable. -dev-tls Enable TLS development mode. In this mode, Vault runs in-memory and starts unsealed, with a generated TLS CA, certificate and key. As the name implies, do not run "dev-tls" mode in production. The default is false. -dev-tls-cert-dir=<string> Directory where generated TLS files are created if `-dev-tls` is specified. If left unset, files are generated in a temporary directory. -dev-tls-san=<string> Additional Subject Alternative Name (as a DNS name or IP address) to generate the certificate with if `-dev-tls` is specified. The certificate will always use localhost, localhost4, localhost6, localhost.localdomain, and the host name as alternate DNS names, and 127.0.0.1 as an alternate IP address. This flag can be specified multiple times to specify multiple SANs.
Dev Options: -dev Enable development mode. In this mode, Vault runs in-memory and starts unsealed. As the name implies, do not run "dev" mode in production. The default is false. -dev-cluster-json=<string> File to write cluster definition to -dev-listen-address=<string> Address to bind to in "dev" mode. The default is 127.0.0.1:8200. This can also be specified via the VAULT_DEV_LISTEN_ADDRESS environment variable. -dev-no-store-token Do not persist the dev root token to the token helper (usually the local filesystem) for use in future requests. The token will only be displayed in the command output. The default is false. -dev-root-token-id=<string> Initial root token. This only applies when running in "dev" mode. This can also be specified via the VAULT_DEV_ROOT_TOKEN_ID environment variable. -dev-tls Enable TLS development mode. In this mode, Vault runs in-memory and starts unsealed, with a generated TLS CA, certificate and key. As the name implies, do not run "dev-tls" mode in production. The default is false. -dev-tls-cert-dir=<string> Directory where generated TLS files are created if `-dev-tls` is specified. If left unset, files are generated in a temporary directory. -dev-tls-san=<string> Additional Subject Alternative Name (as a DNS name or IP address) to generate the certificate with if `-dev-tls` is specified. The certificate will always use localhost, localhost4, localhost6, localhost.localdomain, and the host name as alternate DNS names, and 127.0.0.1 as an alternate IP address. This flag can be specified multiple times to specify multiple SANs.
The dev server listens on the loopback interface at 127.0.0.1 on TCP port 8200 without TLS enabled by default. At runtime, the dev server also automatically unseals, and prints the unseal key and initial root token values to the standard output.
Open a terminal and start a Vault dev server with the literal string
root
as the root token value, and enable TLS.Root tokens
The dev mode server starts with an initial root token value set.
Root token use should be extremely guarded in production environments because it provides full access to the Vault server.
You can supply the root token value to start Vault in dev mode for convenience and to keep the steps here focused on the learning goals of this tutorial.
$ vault server -dev -dev-root-token-id root -dev-tls
$ vault server -dev -dev-root-token-id root -dev-tls
The server starts and emits startup details, and some helpful suggestions to the standard output.
==> Vault server configuration: Administrative Namespace: Api Address: https://127.0.0.1:8200 Cgo: disabled Cluster Address: https://127.0.0.1:8201 Environment Variables: BROWSER, EDITOR, FZF_DEFAULT_OPTS, GOPATH, GPG_TTY, HOME, LANG, LC_ALL, LESS, LESSOPEN, LOGNAME, LSCOLORS, LS_COLORS, MANPATH, NVM_BIN, NVM_CD_FLAGS, NVM_DIR, NVM_INC, OLDPWD, OS_ARCH, PAGER, PATH, PRODUCT, PWD, SHELL, SHLVL, SSH_AGENT_PID, SSH_AUTH_SOCK, STARSHIP_SESSION_KEY, STARSHIP_SHELL, TERM, TERM_PROGRAM, TERM_PROGRAM_VERSION, TERM_SESSION_ID, TMPDIR, USER, VERSION, VISUAL, XPC_FLAGS, XPC_SERVICE_NAME, ZDOTDIR, ZSH, ZSH_TMUX_CONFIG, ZSH_TMUX_TERM, _, _ZSH_TMUX_FIXED_CONFIG, __CFBundleIdentifier Go Version: go1.21.5 Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", disable_request_limiter: "false", max_request_duration: "1m30s", max_request_size: "33554432", tls: "enabled") Log Level: Mlock: supported: false, enabled: false Recovery Mode: false Request Limiter: disabled Storage: inmem Version: Vault v1.16.0-rc2, built 2024-02-20T22:43:58Z Version Sha: f85545f4f6488615859efe1c25b6b9e2b0fbaea3 ==> Vault server started! Log data will stream in below: 2024-04-04T13:24:07.248-0400 [INFO] proxy environment: http_proxy="" https_proxy="" no_proxy="" 2024-04-04T13:24:07.251-0400 [INFO] incrementing seal generation: generation=1 2024-04-04T13:24:07.251-0400 [WARN] no `api_addr` value specified in config or in VAULT_API_ADDR; falling back to detection if possible, but this value should be manually set 2024-04-04T13:24:07.257-0400 [INFO] core: Initializing version history cache for core 2024-04-04T13:24:07.258-0400 [INFO] events: Starting event system 2024-04-04T13:24:07.262-0400 [INFO] core: security barrier not initialized 2024-04-04T13:24:07.262-0400 [INFO] core: security barrier initialized: stored=1 shares=1 threshold=1 2024-04-04T13:24:07.272-0400 [INFO] core: post-unseal setup starting 2024-04-04T13:24:07.285-0400 [INFO] core: loaded wrapping token key 2024-04-04T13:24:07.285-0400 [INFO] core: successfully setup plugin runtime catalog 2024-04-04T13:24:07.285-0400 [INFO] core: successfully setup plugin catalog: plugin-directory="" 2024-04-04T13:24:07.290-0400 [INFO] core: no mounts; adding default mount table 2024-04-04T13:24:07.301-0400 [INFO] core: successfully mounted: type=cubbyhole version="v1.16.0+builtin.vault" path=cubbyhole/ namespace="ID: root. Path: " 2024-04-04T13:24:07.317-0400 [INFO] core: successfully mounted: type=system version="v1.16.0+builtin.vault" path=sys/ namespace="ID: root. Path: " 2024-04-04T13:24:07.325-0400 [INFO] core: successfully mounted: type=identity version="v1.16.0+builtin.vault" path=identity/ namespace="ID: root. Path: " 2024-04-04T13:24:07.333-0400 [INFO] core: successfully mounted: type=token version="v1.16.0+builtin.vault" path=token/ namespace="ID: root. Path: " 2024-04-04T13:24:07.334-0400 [INFO] rollback: Starting the rollback manager with 256 workers 2024-04-04T13:24:07.335-0400 [INFO] rollback: starting rollback manager 2024-04-04T13:24:07.337-0400 [INFO] core: restoring leases 2024-04-04T13:24:07.339-0400 [INFO] identity: entities restored 2024-04-04T13:24:07.339-0400 [INFO] identity: groups restored 2024-04-04T13:24:07.340-0400 [INFO] expiration: lease restore complete 2024-04-04T13:24:07.341-0400 [INFO] core: Recorded vault version: vault version=1.16.0 upgrade time="2024-04-04 17:24:07.341637 +0000 UTC" build date=2024-02-20T22:43:58Z 2024-04-04T13:24:07.345-0400 [INFO] core: post-unseal setup complete 2024-04-04T13:24:07.346-0400 [INFO] core: root token generated 2024-04-04T13:24:07.346-0400 [INFO] core: pre-seal teardown starting 2024-04-04T13:24:07.347-0400 [INFO] rollback: stopping rollback manager 2024-04-04T13:24:07.347-0400 [INFO] core: pre-seal teardown complete 2024-04-04T13:24:07.347-0400 [INFO] core.cluster-listener.tcp: starting listener: listener_address=127.0.0.1:8201 2024-04-04T13:24:07.347-0400 [INFO] core.cluster-listener: serving cluster requests: cluster_listen_address=127.0.0.1:8201 2024-04-04T13:24:07.348-0400 [INFO] core: post-unseal setup starting 2024-04-04T13:24:07.348-0400 [INFO] core: loaded wrapping token key 2024-04-04T13:24:07.348-0400 [INFO] core: successfully setup plugin runtime catalog 2024-04-04T13:24:07.348-0400 [INFO] core: successfully setup plugin catalog: plugin-directory="" 2024-04-04T13:24:07.350-0400 [INFO] core: successfully mounted: type=system version="v1.16.0+builtin.vault" path=sys/ namespace="ID: root. Path: " 2024-04-04T13:24:07.351-0400 [INFO] core: successfully mounted: type=identity version="v1.16.0+builtin.vault" path=identity/ namespace="ID: root. Path: " 2024-04-04T13:24:07.351-0400 [INFO] core: successfully mounted: type=cubbyhole version="v1.16.0+builtin.vault" path=cubbyhole/ namespace="ID: root. Path: " 2024-04-04T13:24:07.352-0400 [INFO] core: successfully mounted: type=token version="v1.16.0+builtin.vault" path=token/ namespace="ID: root. Path: " 2024-04-04T13:24:07.352-0400 [INFO] rollback: Starting the rollback manager with 256 workers 2024-04-04T13:24:07.352-0400 [INFO] rollback: starting rollback manager 2024-04-04T13:24:07.352-0400 [INFO] core: restoring leases 2024-04-04T13:24:07.353-0400 [INFO] expiration: lease restore complete 2024-04-04T13:24:07.353-0400 [INFO] identity: entities restored 2024-04-04T13:24:07.353-0400 [INFO] identity: groups restored 2024-04-04T13:24:07.354-0400 [INFO] core: post-unseal setup complete 2024-04-04T13:24:07.354-0400 [INFO] core: vault is unsealed 2024-04-04T13:24:07.363-0400 [INFO] expiration: revoked lease: lease_id=auth/token/root/h682dc4863bb61206a91b3ba7ebac7f38ce5a37e3f781538171b7f1dd1f360463 2024-04-04T13:24:07.374-0400 [INFO] core: successful mount: namespace="" path=secret/ type=kv version="v0.17.0+builtin" WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory and starts unsealed with a single unseal key. The root token is already authenticated to the CLI, so you can immediately begin using Vault. You may need to set the following environment variables: $ export VAULT_ADDR='https://127.0.0.1:8200' $ export VAULT_CACERT='/var/folders/qr/zgztx0sj6n1dxy86sl36ntnw0000gn/T/vault-tls3037226588/vault-ca.pem' The unseal key and root token are displayed below in case you want to seal/unseal the Vault or re-authenticate. Unseal Key: 1kDP9lKLzPHZsTzc9TEel3FfclBmKNClhaDhAnDx2J8= Root Token: root Development mode should NOT be used in production installations!
1 2 3 4 5 6 7 8 9 1011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283==> Vault server configuration: Administrative Namespace: Api Address: https://127.0.0.1:8200 Cgo: disabled Cluster Address: https://127.0.0.1:8201 Environment Variables: BROWSER, EDITOR, FZF_DEFAULT_OPTS, GOPATH, GPG_TTY, HOME, LANG, LC_ALL, LESS, LESSOPEN, LOGNAME, LSCOLORS, LS_COLORS, MANPATH, NVM_BIN, NVM_CD_FLAGS, NVM_DIR, NVM_INC, OLDPWD, OS_ARCH, PAGER, PATH, PRODUCT, PWD, SHELL, SHLVL, SSH_AGENT_PID, SSH_AUTH_SOCK, STARSHIP_SESSION_KEY, STARSHIP_SHELL, TERM, TERM_PROGRAM, TERM_PROGRAM_VERSION, TERM_SESSION_ID, TMPDIR, USER, VERSION, VISUAL, XPC_FLAGS, XPC_SERVICE_NAME, ZDOTDIR, ZSH, ZSH_TMUX_CONFIG, ZSH_TMUX_TERM, _, _ZSH_TMUX_FIXED_CONFIG, __CFBundleIdentifier Go Version: go1.21.5 Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", disable_request_limiter: "false", max_request_duration: "1m30s", max_request_size: "33554432", tls: "enabled") Log Level: Mlock: supported: false, enabled: false Recovery Mode: false Request Limiter: disabled Storage: inmem Version: Vault v1.16.0-rc2, built 2024-02-20T22:43:58Z Version Sha: f85545f4f6488615859efe1c25b6b9e2b0fbaea3 ==> Vault server started! Log data will stream in below: 2024-04-04T13:24:07.248-0400 [INFO] proxy environment: http_proxy="" https_proxy="" no_proxy="" 2024-04-04T13:24:07.251-0400 [INFO] incrementing seal generation: generation=1 2024-04-04T13:24:07.251-0400 [WARN] no `api_addr` value specified in config or in VAULT_API_ADDR; falling back to detection if possible, but this value should be manually set 2024-04-04T13:24:07.257-0400 [INFO] core: Initializing version history cache for core 2024-04-04T13:24:07.258-0400 [INFO] events: Starting event system 2024-04-04T13:24:07.262-0400 [INFO] core: security barrier not initialized 2024-04-04T13:24:07.262-0400 [INFO] core: security barrier initialized: stored=1 shares=1 threshold=1 2024-04-04T13:24:07.272-0400 [INFO] core: post-unseal setup starting 2024-04-04T13:24:07.285-0400 [INFO] core: loaded wrapping token key 2024-04-04T13:24:07.285-0400 [INFO] core: successfully setup plugin runtime catalog 2024-04-04T13:24:07.285-0400 [INFO] core: successfully setup plugin catalog: plugin-directory="" 2024-04-04T13:24:07.290-0400 [INFO] core: no mounts; adding default mount table 2024-04-04T13:24:07.301-0400 [INFO] core: successfully mounted: type=cubbyhole version="v1.16.0+builtin.vault" path=cubbyhole/ namespace="ID: root. Path: " 2024-04-04T13:24:07.317-0400 [INFO] core: successfully mounted: type=system version="v1.16.0+builtin.vault" path=sys/ namespace="ID: root. Path: " 2024-04-04T13:24:07.325-0400 [INFO] core: successfully mounted: type=identity version="v1.16.0+builtin.vault" path=identity/ namespace="ID: root. Path: " 2024-04-04T13:24:07.333-0400 [INFO] core: successfully mounted: type=token version="v1.16.0+builtin.vault" path=token/ namespace="ID: root. Path: " 2024-04-04T13:24:07.334-0400 [INFO] rollback: Starting the rollback manager with 256 workers 2024-04-04T13:24:07.335-0400 [INFO] rollback: starting rollback manager 2024-04-04T13:24:07.337-0400 [INFO] core: restoring leases 2024-04-04T13:24:07.339-0400 [INFO] identity: entities restored 2024-04-04T13:24:07.339-0400 [INFO] identity: groups restored 2024-04-04T13:24:07.340-0400 [INFO] expiration: lease restore complete 2024-04-04T13:24:07.341-0400 [INFO] core: Recorded vault version: vault version=1.16.0 upgrade time="2024-04-04 17:24:07.341637 +0000 UTC" build date=2024-02-20T22:43:58Z 2024-04-04T13:24:07.345-0400 [INFO] core: post-unseal setup complete 2024-04-04T13:24:07.346-0400 [INFO] core: root token generated 2024-04-04T13:24:07.346-0400 [INFO] core: pre-seal teardown starting 2024-04-04T13:24:07.347-0400 [INFO] rollback: stopping rollback manager 2024-04-04T13:24:07.347-0400 [INFO] core: pre-seal teardown complete 2024-04-04T13:24:07.347-0400 [INFO] core.cluster-listener.tcp: starting listener: listener_address=127.0.0.1:8201 2024-04-04T13:24:07.347-0400 [INFO] core.cluster-listener: serving cluster requests: cluster_listen_address=127.0.0.1:8201 2024-04-04T13:24:07.348-0400 [INFO] core: post-unseal setup starting 2024-04-04T13:24:07.348-0400 [INFO] core: loaded wrapping token key 2024-04-04T13:24:07.348-0400 [INFO] core: successfully setup plugin runtime catalog 2024-04-04T13:24:07.348-0400 [INFO] core: successfully setup plugin catalog: plugin-directory="" 2024-04-04T13:24:07.350-0400 [INFO] core: successfully mounted: type=system version="v1.16.0+builtin.vault" path=sys/ namespace="ID: root. Path: " 2024-04-04T13:24:07.351-0400 [INFO] core: successfully mounted: type=identity version="v1.16.0+builtin.vault" path=identity/ namespace="ID: root. Path: " 2024-04-04T13:24:07.351-0400 [INFO] core: successfully mounted: type=cubbyhole version="v1.16.0+builtin.vault" path=cubbyhole/ namespace="ID: root. Path: " 2024-04-04T13:24:07.352-0400 [INFO] core: successfully mounted: type=token version="v1.16.0+builtin.vault" path=token/ namespace="ID: root. Path: " 2024-04-04T13:24:07.352-0400 [INFO] rollback: Starting the rollback manager with 256 workers 2024-04-04T13:24:07.352-0400 [INFO] rollback: starting rollback manager 2024-04-04T13:24:07.352-0400 [INFO] core: restoring leases 2024-04-04T13:24:07.353-0400 [INFO] expiration: lease restore complete 2024-04-04T13:24:07.353-0400 [INFO] identity: entities restored 2024-04-04T13:24:07.353-0400 [INFO] identity: groups restored 2024-04-04T13:24:07.354-0400 [INFO] core: post-unseal setup complete 2024-04-04T13:24:07.354-0400 [INFO] core: vault is unsealed 2024-04-04T13:24:07.363-0400 [INFO] expiration: revoked lease: lease_id=auth/token/root/h682dc4863bb61206a91b3ba7ebac7f38ce5a37e3f781538171b7f1dd1f360463 2024-04-04T13:24:07.374-0400 [INFO] core: successful mount: namespace="" path=secret/ type=kv version="v0.17.0+builtin" WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory and starts unsealed with a single unseal key. The root token is already authenticated to the CLI, so you can immediately begin using Vault. You may need to set the following environment variables: $ export VAULT_ADDR='https://127.0.0.1:8200' $ export VAULT_CACERT='/var/folders/qr/zgztx0sj6n1dxy86sl36ntnw0000gn/T/vault-tls3037226588/vault-ca.pem' The unseal key and root token are displayed below in case you want to seal/unseal the Vault or re-authenticate. Unseal Key: 1kDP9lKLzPHZsTzc9TEel3FfclBmKNClhaDhAnDx2J8= Root Token: root Development mode should NOT be used in production installations!
The first section lists Vault server configuration details. This information is helpful to confirm that the server is operating under your desired configuration.
The second section shows server startup log output. This information relates to the operational status of the server during startup.
Since this is a dev server, Vault adds some extra helpful suggestions to the output in the third section.
You can use these suggestions to prepare your Vault client for communicating with the server.
In a new terminal, export the
VAULT_ADDR
andVAULT_CACERT
environment variables using the commands suggested in your Vault dev server output. Copy each command (without the$
) from the server output, and paste it into the new terminal session.Here is an example of the first export command that instructs the client to communicate with the dev mode server.
export VAULT_ADDR='https://127.0.0.1:8200'
export VAULT_ADDR='https://127.0.0.1:8200'
Here is an example of the second command to specify the certificate authority file path.
$ export VAULT_CACERT='/var/folders/qr/zgztx0sj6n1dxy86sl36ntnw0000gn/T/vault-tls3037226588/vault-ca.pem'
$ export VAULT_CACERT='/var/folders/qr/zgztx0sj6n1dxy86sl36ntnw0000gn/T/vault-tls3037226588/vault-ca.pem'
Remember to use your dev server's values, not the examples shown here.
(Persona: Operations)
Launch Terminal
This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.
A dev server requires little configuration to use, but a self-managed Vault server needs configuration for networking, storage, and other Vault-specific options.
As the operations persona, your task here is to prepare a Vault server environment, TLS certificate and key material, and a configuration file for the server.
You can define Vault server configuration in HashiCorp Configuration Language (HCL) as a file or collection of files that the server reads at runtime.
You'll use the following example Vault server configuration file:
api_addr = "https://127.0.0.1:8200" cluster_addr = "https://127.0.0.1:8201" cluster_name = "learn-vault-cluster" disable_mlock = true ui = true listener "tcp" { address = "127.0.0.1:8200" tls_cert_file = "/tmp/vault-cert.pem" tls_key_file = "/tmp/vault-key.pem" } backend "raft" { path = "/tmp/vault-data" node_id = "learn-vault-server" }
1 2 3 4 5 6 7 8 9 10111213141516api_addr = "https://127.0.0.1:8200"
cluster_addr = "https://127.0.0.1:8201"
cluster_name = "learn-vault-cluster"
disable_mlock = true
ui = true
listener "tcp" {
address = "127.0.0.1:8200"
tls_cert_file = "/tmp/vault-cert.pem"
tls_key_file = "/tmp/vault-key.pem"
}
backend "raft" {
path = "/tmp/vault-data"
node_id = "learn-vault-server"
}
Lines 1 through 5 are global options:
api_addr
: the server API address is what all clients connect to for interacting with Vault, and formatted as a URL with a port number.cluster_addr
: the server cluster address, required for intra-cluster communication between Vault servers participating in a cluster. This address is also expressed as a URL with port.cluster_name
: the server cluster name is the same for all servers participating in a cluster.disable_mlock
: for servers which use integrated storage, disable operating system memory locking for the Vault process, as it can cause undesired behavior with the integrated storage backend. Disable memory locking by setting this option's value totrue
.ui
: If you want to use the Vault web user interface, you must explicitly enable it. Enable the Vault UI by setting this option's value totrue
.
Lines 7 through 11 are part of the listener
stanza, and define how and where the Vault server listens for incoming connections. Vault can listen on TCP ports or Unix domain sockets.
In this example, the server address
is the loopback interface at address 127.0.0.1
with the TCP port 8200
. When you define a TCP port listener, the server expects TLS enabled by default. You must then also configure tls_cert_file
and tls_key_file
by setting their values to the fully qualified path to a valid TLS certificate and key file respectively.
Lines 13 through 16 are part of the storage
stanza, and define which type of storage backend the server uses, along with related options.
In this example, the server uses the storage type raft
(integrated storage) while specifying the required local data storage path and node identifier.
Minimal example configuration
This configuration file is a minimal example just for use in the tutorial.
You've learned about the configuration you'll use with the self-managed Vault server, and now you're ready to prepare and start the server.
Create a directory for storing the server data.
$ mkdir /tmp/vault-data
$ mkdir /tmp/vault-data
Use
openssl
to generate a self-signed TLS certificate and key for the server to use, and write them to the files/tmp/vault-cert.pem
and/tmp/vault-key.pem
.$ openssl req -x509 -newkey rsa:4096 -sha256 -days 365 \ -nodes -keyout /tmp/vault-key.pem -out /tmp/vault-cert.pem \ -subj "/CN=localhost" \ -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
$ openssl req -x509 -newkey rsa:4096 -sha256 -days 365 \ -nodes -keyout /tmp/vault-key.pem -out /tmp/vault-cert.pem \ -subj "/CN=localhost" \ -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
Create a basic server configuration file at the path
/tmp/vault-server.hcl
.$ cat > /tmp/vault-server.hcl << EOF api_addr = "https://127.0.0.1:8200" cluster_addr = "https://127.0.0.1:8201" cluster_name = "learn-vault-cluster" disable_mlock = true ui = true listener "tcp" { address = "127.0.0.1:8200" tls_cert_file = "/tmp/vault-cert.pem" tls_key_file = "/tmp/vault-key.pem" } backend "raft" { path = "/tmp/vault-data" node_id = "learn-vault-server" } EOF
$ cat > /tmp/vault-server.hcl << EOF api_addr = "https://127.0.0.1:8200" cluster_addr = "https://127.0.0.1:8201" cluster_name = "learn-vault-cluster" disable_mlock = true ui = true listener "tcp" { address = "127.0.0.1:8200" tls_cert_file = "/tmp/vault-cert.pem" tls_key_file = "/tmp/vault-key.pem" } backend "raft" { path = "/tmp/vault-data" node_id = "learn-vault-server" } EOF
Start the server, and specify the full path to the server configuration file.
$ vault server -config=/tmp/vault-server.hcl
$ vault server -config=/tmp/vault-server.hcl
The server starts, and streams information to the standard output as shown in this example:
==> Vault server configuration: Administrative Namespace: Api Address: https://127.0.0.1:8200 Cgo: disabled Cluster Address: https://127.0.0.1:8201 Environment Variables: BROWSER, EDITOR, FZF_DEFAULT_OPTS, GOPATH, GPG_TTY, HOME, LANG, LC_ALL, LESS, LESSOPEN, LOGNAME, LSCOLORS, LS_COLORS, MANPATH, NVM_BIN, NVM_CD_FLAGS, NVM_DIR, NVM_INC, OLDPWD, PAGER, PATH, PWD, SHELL, SHLVL, SSH_AGENT_PID, SSH_AUTH_SOCK, STARSHIP_SESSION_KEY, STARSHIP_SHELL, TERM, TERM_PROGRAM, TERM_PROGRAM_VERSION, TERM_SESSION_ID, TMPDIR, USER, VAULT_ADDR, VAULT_SKIP_VERIFY, VISUAL, XPC_FLAGS, XPC_SERVICE_NAME, ZDOTDIR, ZSH, ZSH_TMUX_CONFIG, ZSH_TMUX_TERM, _, _ZSH_TMUX_FIXED_CONFIG, __CFBundleIdentifier Go Version: go1.21.8 Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", disable_request_limiter: "false", max_request_duration: "1m30s", max_request_size: "33554432", tls: "enabled") Log Level: Mlock: supported: false, enabled: false Recovery Mode: false Storage: raft (HA available) Version: Vault v1.16.1, built 2024-04-03T12:35:53Z Version Sha: 6b5986790d7748100de77f7f127119c4a0f78946 ==> Vault server started! Log data will stream in below: 2024-04-18T11:39:14.675-0400 [INFO] proxy environment: http_proxy="" https_proxy="" no_proxy="" 2024-04-18T11:39:14.743-0400 [INFO] incrementing seal generation: generation=1 2024-04-18T11:39:14.748-0400 [INFO] core: Initializing version history cache for core 2024-04-18T11:39:14.748-0400 [INFO] events: Starting event system
==> Vault server configuration: Administrative Namespace: Api Address: https://127.0.0.1:8200 Cgo: disabled Cluster Address: https://127.0.0.1:8201 Environment Variables: BROWSER, EDITOR, FZF_DEFAULT_OPTS, GOPATH, GPG_TTY, HOME, LANG, LC_ALL, LESS, LESSOPEN, LOGNAME, LSCOLORS, LS_COLORS, MANPATH, NVM_BIN, NVM_CD_FLAGS, NVM_DIR, NVM_INC, OLDPWD, PAGER, PATH, PWD, SHELL, SHLVL, SSH_AGENT_PID, SSH_AUTH_SOCK, STARSHIP_SESSION_KEY, STARSHIP_SHELL, TERM, TERM_PROGRAM, TERM_PROGRAM_VERSION, TERM_SESSION_ID, TMPDIR, USER, VAULT_ADDR, VAULT_SKIP_VERIFY, VISUAL, XPC_FLAGS, XPC_SERVICE_NAME, ZDOTDIR, ZSH, ZSH_TMUX_CONFIG, ZSH_TMUX_TERM, _, _ZSH_TMUX_FIXED_CONFIG, __CFBundleIdentifier Go Version: go1.21.8 Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", disable_request_limiter: "false", max_request_duration: "1m30s", max_request_size: "33554432", tls: "enabled") Log Level: Mlock: supported: false, enabled: false Recovery Mode: false Storage: raft (HA available) Version: Vault v1.16.1, built 2024-04-03T12:35:53Z Version Sha: 6b5986790d7748100de77f7f127119c4a0f78946 ==> Vault server started! Log data will stream in below: 2024-04-18T11:39:14.675-0400 [INFO] proxy environment: http_proxy="" https_proxy="" no_proxy="" 2024-04-18T11:39:14.743-0400 [INFO] incrementing seal generation: generation=1 2024-04-18T11:39:14.748-0400 [INFO] core: Initializing version history cache for core 2024-04-18T11:39:14.748-0400 [INFO] events: Starting event system
The first section lists Vault server configuration details. This information is helpful to confirm that the server is operating under your desired configuration.
The second section shows server startup log output. This information relates to the operational status of the server during startup.
Before you can use the server, you must first initialize and unseal it. For this tutorial, you can initialize Vault with the default Shamir's Secret Sharing seal, but specify just 1 key share and a key threshold of 1.
This means that you can unseal Vault in the next step with just one key share instead of the default 3 of 5 key shares.
In a new terminal session, export the
VAULT_ADDR
environment variable to address the server.$ export VAULT_ADDR=https://127.0.0.1:8200
$ export VAULT_ADDR=https://127.0.0.1:8200
Vault uses strict verification of all TLS certificates by default. Since you're using a self-signed TLS certificate without a certificate authority, you should disable this strict checking by exporting the
VAULT_SKIP_VERIFY
environment variable and setting its value totrue
.$ export VAULT_SKIP_VERIFY=true
$ export VAULT_SKIP_VERIFY=true
Initialize the server.
$ vault operator init -key-shares=1 -key-threshold=1
$ vault operator init -key-shares=1 -key-threshold=1
Vault responds to your initialization request with output containing the unseal key value and initial root token value as shown in this example.
Unseal Key 1: HLOCX7/wwvFg10EMvT9Zfa+5HfiPjKTaJRub06PDMnc= Initial Root Token: hvs.YOo2eCJlbW3wKIKtj9lHSoz4 Vault initialized with 1 key shares and a key threshold of 1. Please securely distribute the key shares printed above. When the Vault is re-sealed, restarted, or stopped, you must supply at least 1 of these keys to unseal it before it can start servicing requests. Vault does not store the generated root key. Without at least 1 keys to reconstruct the root key, Vault will remain permanently sealed! It is possible to generate new unseal keys, provided you have a quorum of existing unseal keys shares. See "vault operator rekey" for more information.
Unseal Key 1: HLOCX7/wwvFg10EMvT9Zfa+5HfiPjKTaJRub06PDMnc= Initial Root Token: hvs.YOo2eCJlbW3wKIKtj9lHSoz4 Vault initialized with 1 key shares and a key threshold of 1. Please securely distribute the key shares printed above. When the Vault is re-sealed, restarted, or stopped, you must supply at least 1 of these keys to unseal it before it can start servicing requests. Vault does not store the generated root key. Without at least 1 keys to reconstruct the root key, Vault will remain permanently sealed! It is possible to generate new unseal keys, provided you have a quorum of existing unseal keys shares. See "vault operator rekey" for more information.
Tip
You must initialize Vault to configure it for use. You do this just once, when the server is started against a new storage backend. When you run Vault in HA mode, you initialize once per cluster, not once per server. Vault generates the encryption keys, unseal keys, and the initial root token during initialization.
Every initialized Vault server starts in the sealed state. Vault can access the physical storage backend, but it can't read any of it because it doesn't know how to decrypt it. After you unseal Vault, it can read and write encrypted values in the storage backend.
You can unseal the server with
vault operator unseal
and pass in the unseal key value as an argument to the command, but in this example you'll just use the command.$ vault operator unseal
$ vault operator unseal
Vault responds to the command without arguments by prompting you for the unseal key.
Unseal Key (will be hidden):
Unseal Key (will be hidden):
Copy the Unseal Key 1: value from the initialization output, paste it at the prompt for unseal key and press
RETURN
.Vault responds by unsealing, and showing the server status.
Key Value --- ----- Seal Type shamir Initialized true Sealed false Total Shares 1 Threshold 1 Version 1.16.1 Build Date 2024-04-03T12:35:53Z Storage Type raft Cluster Name learn-vault-cluster Cluster ID 8bbda9de-6f92-1a6c-90d5-925b6e88c3c3 HA Enabled true HA Cluster n/a HA Mode standby Active Node Address <none> Raft Committed Index 29 Raft Applied Index 29
Key Value --- ----- Seal Type shamir Initialized true Sealed false Total Shares 1 Threshold 1 Version 1.16.1 Build Date 2024-04-03T12:35:53Z Storage Type raft Cluster Name learn-vault-cluster Cluster ID 8bbda9de-6f92-1a6c-90d5-925b6e88c3c3 HA Enabled true HA Cluster n/a HA Mode standby Active Node Address <none> Raft Committed Index 29 Raft Applied Index 29
(Persona: Operations)
Note
This tutorial assumes you have not previously created HashiCorp Virtual Network (HVN) in your HashiCorp Cloud Platform account.
Launch the HCP Portal and login.
If you have logged in before, the portal opens the last project you were in. Navigate back to the organization level from the breadcrumbs, or click on the HashiCorp icon at the top-left to choose another organization.
Click on the HashiCorp icon to list your organizations, and select the organization in which you'll create your HCP Vault Dedicated cluster.
HashiCorp Cloud Platform (HCP) provides your account with an organization. Your account may invite others to join your organization or you may be invited to join other organizations.
Click Projects, and select the target project.
- Click + Create project.
- Enter the Project name and Project description.
- Click Create project to complete.
You can use projects to separate access within an organization, such as by team, use cases, or environment (e.g. development, staging, production, etc.).
From the Overview page, click Get started with Vault Dedicated.
From the Vault overview page you have the option to deploy HCP Vault Dedicated using a pre-configured template that deploys Vault with a sample configuration or you can choose to Start from scratch to deploy a standard Vault Dedicated instance with no existing configuration.
For the purposes of this tutorial and learning about Vault, click the Create cluster button under Start from scratch.
Select your preferred cloud provider.
Click the Vault tier pull down menu and select Development.
Tip
The development tier should not be used for production workloads.
Click the Cluster size pull down menu and select Extra Small.
For the development tier, Extra Small is the only available cluster size.
Under the Network section, accept or edit the Network ID, Region selection, and CIDR block for the HVN.
Under the Basics section, accept or edit the default Cluster ID (
vault-cluster
).Under Templates, select Start from scratch. Templates provide sample configurations for various use cases.
Click Create cluster.
Wait for the cluster to initialize before proceeding.
After the cluster is created, refresh the page.
Click Cluster networking. The cluster networking page allows you to configure whether the cluster is configured for public or private access.
By default, all development tier clusters are configured for public access and all production tier clusters are configured for private access.
The IP Allow list allows you to add specific IP addresses or CIDR ranges that will be permitted to access the HCP Vault clusters public endpoint (if public access is enabled).
You can also enable or disable the HCP Proxy. The proxy allows you to access the Vault user interface when private access is enabled.
Click Overview to return to the Vault cluster overview page.
The Vault page displays the created Vault cluster. Within that view, the Overview page displays information to help you learn about HCP Vault, Vault configuration, Vault usage, and cluster details. The Access Vault pane contains details that enable you to administer the Vault cluster through the Web UI or command-line interface (CLI).
Note
The cluster is created with a top-level Namespace called admin
. Namespaces enable you to create isolated Vault environments.
Now that you have created a new HCP Vault instance, you will need to perform some initial configuration to support your use case such as enabling secrets engines to store or generate secrets, or adding additional auth methods to allow users or applications to authenticate with HCP Vault.
HCP Vault provides the same type of access as a traditional Vault cluster. You can access it through a command line interface (CLI) using the Vault binary, through the Vault API using common programming languages or tools such as cURL, or by using the Vault User Interface (UI).
Access the Vault cluster
Security consideration
When an HCP Vault cluster has public access enabled, you can connect to Vault from any internet connected device. If your use case requires public access to be enabled, we recommend configuring the IP allow list to limit which IPv4 public IP addresses or CIDR ranges can connect to Vault to limit the attack surface.
When the HCP Vault cluster has private access enabled you will need to access the cluster from a connected cloud provider such as AWS with a VPC peering connection, a AWS transit gateway connection, or Azure with a Azure Virtual Network peering connection. For the purposes of this tutorial, your cluster should have public access enabled.
Under Quick actions, click Command-line (CLI).
Click the copy button under Use public URL to copy the commands to export the correct
VAULT_ADDR
andVAULT_NAMESPACE
values to the system Clipboard.In a terminal, paste the copied commands.
$ export VAULT_ADDR="https://vault-cluster-hashicups-operations-public-vault-c0ff331a.1d58aa23.z0.hashicorp.cloud:8200"; export VAULT_NAMESPACE="admin"
$ export VAULT_ADDR="https://vault-cluster-hashicups-operations-public-vault-c0ff331a.1d58aa23.z0.hashicorp.cloud:8200"; export VAULT_NAMESPACE="admin"
You're now ready to check the server status.
Check the server status
Now that you have a running Vault server, you can check its status from the command line.
Open a new terminal session, and check the server status.
(Persona: developer)
Check the status of your Vault dev server.
$ vault status
$ vault status
Example output:
Key Value --- ----- Seal Type shamir Initialized true Sealed false Total Shares 1 Threshold 1 Version 1.16.0 Build Date 2024-02-20T22:43:58Z Storage Type inmem Cluster Name vault-cluster-eabfb52b Cluster ID 6150648b-ed4d-4e5f-8927-223137b0507b HA Enabled false
Key Value
--- -----
Seal Type shamir
Initialized true
Sealed false
Total Shares 1
Threshold 1
Version 1.16.0
Build Date 2024-02-20T22:43:58Z
Storage Type inmem
Cluster Name vault-cluster-eabfb52b
Cluster ID 6150648b-ed4d-4e5f-8927-223137b0507b
HA Enabled false
(Persona: operations)
Check the status of your Vault server.
$ vault status
$ vault status
Example output:
Key Value --- ----- Seal Type shamir Initialized true Sealed false Total Shares 1 Threshold 1 Version 1.16.1 Build Date 2024-04-03T12:35:53Z Storage Type raft Cluster Name learn-vault-cluster Cluster ID 8bbda9de-6f92-1a6c-90d5-925b6e88c3c3 HA Enabled true HA Cluster https://127.0.0.1:8201 HA Mode active Active Since 2024-04-18T11:49:39.87382-04:00 Raft Committed Index 56 Raft Applied Index 56
Key Value
--- -----
Seal Type shamir
Initialized true
Sealed false
Total Shares 1
Threshold 1
Version 1.16.1
Build Date 2024-04-03T12:35:53Z
Storage Type raft
Cluster Name learn-vault-cluster
Cluster ID 8bbda9de-6f92-1a6c-90d5-925b6e88c3c3
HA Enabled true
HA Cluster https://127.0.0.1:8201
HA Mode active
Active Since 2024-04-18T11:49:39.87382-04:00
Raft Committed Index 56
Raft Applied Index 56
(Persona: operations)
Check the status of your HCP Vault Dedicated server.
$ vault status
$ vault status
Example output:
Key Value --- ----- Seal Type awskms Recovery Seal Type shamir Initialized true Sealed false Total Recovery Shares 1 Threshold 1 Version 1.15.5+ent Build Date 2024-01-26T21:04:45Z Storage Type raft Cluster Name vault-cluster-a998d6c8 Cluster ID b8c0ff33-a0cd-e74d-9c15-430ec1bb5e17 HA Enabled true HA Cluster https://172.25.16.84:8201 HA Mode active Active Since 2024-04-18T17:08:16.431186562Z Raft Committed Index 2111 Raft Applied Index 2111 Last WAL 732
Key Value
--- -----
Seal Type awskms
Recovery Seal Type shamir
Initialized true
Sealed false
Total Recovery Shares 1
Threshold 1
Version 1.15.5+ent
Build Date 2024-01-26T21:04:45Z
Storage Type raft
Cluster Name vault-cluster-a998d6c8
Cluster ID b8c0ff33-a0cd-e74d-9c15-430ec1bb5e17
HA Enabled true
HA Cluster https://172.25.16.84:8201
HA Mode active
Active Since 2024-04-18T17:08:16.431186562Z
Raft Committed Index 2111
Raft Applied Index 2111
Last WAL 732
Your HCP Vault Dedicated server is initialized and unsealed. By default Vault enables the token authentication method.
Authenticate with Vault
You have a running server, and have checked its status. You're ready to authenticate with Vault.
(Persona: developer)
Authenticate with Vault using the initial root token value.
$ vault login root
$ vault login root
Vault prompts you for the token value:
Token (will be hidden):
Token (will be hidden):
Type in the literal string root
, and press RETURN
.
Vault responds with a success message, and output containing the token value and metadata.
Success! You are now authenticated. The token information displayed below is already stored in the token helper. You do NOT need to run "vault login" again. Future Vault requests will automatically use this token. Key Value --- ----- token hvs.Iz85NhcoJ9yl3q9q0FiBqd65 token_accessor Xph6WI0roJRmLmVuM8J9Akky token_duration ∞ token_renewable false token_policies ["root"] identity_policies [] policies ["root"]
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
Key Value
--- -----
token hvs.Iz85NhcoJ9yl3q9q0FiBqd65
token_accessor Xph6WI0roJRmLmVuM8J9Akky
token_duration ∞
token_renewable false
token_policies ["root"]
identity_policies []
policies ["root"]
Root tokens
Root token use should be extremely guarded in production environments. The root token is used here for convenience and to keep the tutorial steps focused on what you'll learn.
(Persona: operations)
Authenticate with Vault using the initial root token value from the initialization output.
$ vault login
$ vault login
Vault prompts you for the token value:
Token (will be hidden):
Token (will be hidden):
Copy the Initial Root Token value from the initialization output, and paste it at the prompt.
Vault responds with a success message, and output containing the token value and metadata.
Success! You are now authenticated. The token information displayed below is already stored in the token helper. You do NOT need to run "vault login" again. Future Vault requests will automatically use this token. Key Value --- ----- token hvs.Iz85NhcoJ9yl3q9q0FiBqd65 token_accessor Xph6WI0roJRmLmVuM8J9Akky token_duration ∞ token_renewable false token_policies ["root"] identity_policies [] policies ["root"]
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
Key Value
--- -----
token hvs.Iz85NhcoJ9yl3q9q0FiBqd65
token_accessor Xph6WI0roJRmLmVuM8J9Akky
token_duration ∞
token_renewable false
token_policies ["root"]
identity_policies []
policies ["root"]
(Persona: operations)
Return to the Overview page and click Generate token.
Within a few moments a new token is generated.
Copy the Admin Token.
Return to the terminal and login with Vault. When prompted, enter the generated admin token.
$ vault login Token (will be hidden): <token>
$ vault login Token (will be hidden): <token>
The
<token>
placeholder represents the copied token value.Example output:
Success! You are now authenticated. The token information displayed below is already stored in the token helper. You do NOT need to run "vault login" again. Future Vault requests will automatically use this token. token hvs.QRSTUV-WXypd-96-ANTSChh5sqa5IB4ZVQ0Qo_iLBWaNIbnQGiYKImh2cy5raE1qZmtBd2lzTkJ3bExITjVZcjRhbFMuSjlxNGcQeg token_accessor CDeirnF8ijVMtkckQozs4hdk.J9q4g token_duration 5h19m35s token_renewable false token_policies ["default" "hcp-root"] identity_policies [] policies ["default" "hcp-root"]
Success! You are now authenticated. The token information displayed below is already stored in the token helper. You do NOT need to run "vault login" again. Future Vault requests will automatically use this token. token hvs.QRSTUV-WXypd-96-ANTSChh5sqa5IB4ZVQ0Qo_iLBWaNIbnQGiYKImh2cy5raE1qZmtBd2lzTkJ3bExITjVZcjRhbFMuSjlxNGcQeg token_accessor CDeirnF8ijVMtkckQozs4hdk.J9q4g token_duration 5h19m35s token_renewable false token_policies ["default" "hcp-root"] identity_policies [] policies ["default" "hcp-root"]
You've started your Vault server, checked its status and authenticated with Vault. From here, you can explore Vault further on your own or clean up the environment.
What are two common environment variables used to configure the Vault CLI?
VAULT_ADDR
specifies the address of the Vault server you are trying to connect
to.
VAULT_CACERT
specifies the path to the TLS certificates used for secure
connections to Vault.
Clean up
(Persona: developer)
Use CTRL+C
to stop the server process in the terminal window where you started the server, or use this command to kill the server process from any local terminal session:
$ pkill vault
$ pkill vault
Unset environment variables.
$ unset VAULT_ADDR VAULT_CACERT
$ unset VAULT_ADDR VAULT_CACERT
(Persona: operations)
Use
CTRL+C
to stop the server process in the terminal window where you started the server, or use this command to kill the server process from any local terminal session:$ pkill vault
$ pkill vault
Remove the Vault data directory.
$ rm -rf /tmp/vault-data
$ rm -rf /tmp/vault-data
Remove the server configuration file.
$ rm -f /tmp/vault-server.hcl
$ rm -f /tmp/vault-server.hcl
Remove the TLS files.
$ rm -f /tmp/vault-cert.pem /tmp/vault-key.pem
$ rm -f /tmp/vault-cert.pem /tmp/vault-key.pem
Unset environment variables.
$ unset VAULT_ADDR VAULT_SKIP_VERIFY
$ unset VAULT_ADDR VAULT_SKIP_VERIFY
(Persona: operations)
Unset environment variables.
$ unset VAULT_ADDR VAULT_NAMESPACE
$ unset VAULT_ADDR VAULT_NAMESPACE
Summary
Vault has different setup options based on your use case. Developers can run Vault in dev mode to support local testing and development against Vault. For production workloads, operations teams will need to follow the self-managed Vault setup and create a properly written configuration file. Teams can also opt for a production ready cluster managed by HashiCorp by choosing to deploy Vault Enterprise on the HashiCorp Cloud Platform (HCP).