Deploying Vault on VMs with Let's encrypt! TLS certs
In this get started tutorial, we install the vault container in a VM and configure a TLS certificates with let's encrypt.
Last updated
In this get started tutorial, we install the vault container in a VM and configure a TLS certificates with let's encrypt.
Last updated
Throughout this tutorial, we assume docker and docker-compose are installed, and the user has permission to the vault container from the repo. We further assume access to a DNS server in order to pass the ACME let's encrypt challenge.
Please consult your DNS administrator. Add an A or AAA to point the VM's IP address to the domain mydomain.com.
You may want to create folder for shared mounts between the vault and certbot co
Create a file config.json and store the file in folder ./config. Below some example configurations.
Within the configuration file, there are two primary configurations:
storage - This is the physical backend that Vault uses for storage. Up to this point the dev server has used in memory (inmem), but the example above uses the filesystem (file) and integrated Storage (raft), a much more production-ready backend.
listener - One or more listeners determine how Vault listens for API requests. The example above listens on 0.0.0.0 port 8200. In your environment set VAULT_ADDR=https://mydomain.com so the Vault client will connect without TLS.
Run the docker-compose.yml and replace flags --email and --domain with the email address and domain name of your choice.
Within the docker-compose file, there are some configurations:
--cert-name: Pass this name to specify a particular certificate.
--standalone: Use standalone mode to obtain a certificate for any server. This plugin needs to bind to port 80 in order to perform domain validation.
--reinstall: If the requested certificate matches an existing certificate, always keep the existing one until it is due for renewal.
In non-production use we recommend to enable the following flags to avoid rate limits:
--dry-run : Simulates the certificate generation. No keys are generated. This flag is useful in testing the configuration and the DNS challenge.
--staging : Uses the Let's Encrypt staging server to obtain or revoke test (invalid) certificates.
Initialization is the process of configuring Vault. This only happens once when the server is started against a new backend that has never been used with Vault before. When running in HA mode, this happens once per cluster, not per server. During initialization, the encryption keys are generated, unseal keys are created, and the initial root token is created.
Launch a new terminal session, and set VAULT_ADDR environment variable.
To initialize Vault use vault operator init. This is an unauthenticated request, but it only works on brand new Vaults without existing data:
Initialization outputs two incredibly important pieces of information: the unseal keys and the initial root token. This is the only time ever that all of this data is known by Vault, and also the only time that the unseal keys should ever be so close together.
For the purpose of this getting started tutorial, save all of these keys somewhere, and continue. In a real deployment scenario, you would never save these keys together. Instead, you would likely use Vault's PGP and Keybase.io support to encrypt each of these keys with the users' PGP keys. This prevents one single person from having all the unseal keys. Please see the documentation on using PGP, GPG, and Keybase for more information.
Every initialized Vault server starts in the sealed state. From the configuration, Vault can access the physical storage, but it can't read any of it because it doesn't know how to decrypt it. The process of teaching Vault how to decrypt the data is known as unsealing the Vault.
Unsealing has to happen every time Vault starts. It can be done via the API and via the command line. To unseal the Vault, you must have the threshold number of unseal keys. In the output above, notice that the "key threshold" is 3. This means that to unseal the Vault, you need 3 of the 5 keys that were generated.
After pasting in a valid key and confirming, you see that Vault is still sealed, but progress is made. Vault knows it has 1 key out of 3. Due to the nature of the algorithm, Vault doesn't know if it has the correct key until the threshold is reached.
Also notice that the unseal process is stateful. You can go to another computer, use vault operator unseal, and as long as it's pointing to the same server, that other computer can continue the unseal process. This is incredibly important to the design of the unseal process: multiple people with multiple keys are required to unseal the Vault. The Vault can be unsealed from multiple computers and the keys should never be together. A single malicious operator does not have enough keys to be malicious.
Continue with vault operator unseal to complete unsealing the Vault. To unseal the vault you must use three different unseal keys, the same key repeated will not work.
As you use keys, as long as they are correct, you should soon see output like this:
When the value for Sealed changes to false, the Vault is unsealed.
Feel free to play around with entering invalid keys, keys in different orders, etc. in order to understand the unseal process.
Finally, authenticate as the initial root token (it was included in the output with the unseal keys).
Enter the token value when prompted.
As a root user, you can reseal the Vault with vault operator seal. A single operator is allowed to do this. This lets a single operator lock down the Vault in an emergency without consulting other operators.
When the Vault is sealed again, it clears all of its state (including the encryption key) from memory. The Vault is secure and locked down from access.