7.4 KiB
| layout | page_title | sidebar_current | description |
|---|---|---|---|
| intro | Deploy Vault | gettingstarted-deploy | Learn how to deploy Vault into production, how to initialize it, configure it, etc. |
Deploy Vault
Up to this point, we've been working with the dev server, which automatically authenticated us, setup in-memory storage, etc. Now that you know the basics of Vault, it is important to learn how to deploy Vault into a real environment.
On this page, we'll cover how to configure Vault, start Vault, the seal/unseal process, and scaling Vault.
Configuring Vault
Vault is configured using HCL files. As a reminder, these files are also JSON-compatible. The configuration file for Vault is relatively simple. An example is shown below:
backend "consul" {
address = "demo.consul.io:80"
path = "vault"
}
listener "tcp" {
address = "127.0.0.1:8200"
tls_disable = 1
}
Within the configuration file, there are two primary configurations:
-
backend- This is the physical backend that Vault uses for storage. Up to this point the dev server has used "inmem" (in memory), but in the example above we're using Consul, a much more production-ready backend. -
listener- One or more listeners determine how Vault listens for API requests. In the example above we're listening on localhost port 8200 without TLS.
For now, copy and paste the configuration above. Change the path
for Consul to something unique for you to make sure you don't overlap
with anyone else following this guide. We'll use this demo cluster to
learn how to deploy Vault.
~> Warning: The demo consul cluster deletes its data every 30 minutes. If this happens while you're learning to use Vault, you'll lose your data. Just restart Vault and start over, knowing you have another 30 minutes.
Starting the Server
With the configuration in place, starting the server is simple, as
shown below. Modify the -config flag to point to the the proper path
where you saved the configuration above.
$ vault server -config=example.hcl
==> Vault server configuration:
Log Level: info
Backend: consul
Listener 1: tcp (addr: "127.0.0.1:8200", tls: "disabled")
==> Vault server started! Log data will stream in below:
Vault outputs some information about its configuration, and then blocks. This process should be run using a resource manager such as systemd or upstart.
You'll notice that you can't execute any commands. We don't have any auth information! When you first setup a Vault server, you have to start by initializing it.
Initializing the Vault
Initialization is the process of first configuring the Vault. This only happens once when the server is started against a new backend that has never been used with Vault before.
During initialization, the encryption keys are generated, unseal keys
are created, and the initial root token is setup. To initialize Vault
use vault init. This is an unauthenticated request, but it only works
on brand new Vaults with no data:
$ vault init
Key 1: 427cd2c310be3b84fe69372e683a790e01
Key 2: 0e2b8f3555b42a232f7ace6fe0e68eaf02
Key 3: 37837e5559b322d0585a6e411614695403
Key 4: 8dd72fd7d1af254de5f82d1270fd87ab04
Key 5: b47fdeb7dda82dbe92d88d3c860f605005
Initial Root Token: eaf5cc32-b48f-7785-5c94-90b5ce300e9b
Vault initialized with 5 keys and a key threshold of 3!
Please securely distribute the above keys. Whenever a Vault server
is started, it must be unsealed with 3 (the threshold)
of thekeys above (any of the keys, as long as the total number equals
the threshold).
Vault does not store the original master key. If you lose the keys
above such that you no longer have the minimum number (the
threshold), then your Vault will not be able to be unsealed.
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 guide, save all these keys somewhere, and continue. In a real deployment scenario, you would never save these keys together.
Seal/Unseal
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.
-> Note: Vault does not store any of the unseal key shards. Vault uses an algorithm known as Shamir's Secret Sharing to split the master key into shards. Only with the threshold number of keys can it be reconstructed and your data finally accessed.
Begin unsealing the Vault with vault unseal:
$ vault unseal
Key (will be hidden):
Sealed: true
Key Shares: 5
Key Threshold: 3
Unseal Progress: 1
After pasting in a valid key and confirming, you'll see that the Vault is still sealed, but progress is made. Vault knows it has 1 key out of 3. Due to the nature of the algorith, 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 unseal, and as long as its 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 mailicious.
Continue with vault unseal to complete unsealing the Vault. Note that
all 3 keys must be different, but they can be any other keys. As long as
they're correct, you should soon see output like this:
$ vault unseal
Key (will be hidden):
Sealed: false
Key Shares: 5
Key Threshold: 3
Unseal Progress: 0
The Sealed: false means 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. It is very important.
Once you're ready to move on, use vault auth to authenticate with
the root token.
As a root user, you can reseal the Vault with vault 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.
Next
You now know how to configure, initialize, and unseal/seal Vault. This is the basic knowledge necessary to deploy Vault into a real environment. Once the Vault is unsealed, you access it as you have throughout this getting started guide (which worked with an unsealed Vault).
Congratulations! You now know all the basics to get started with Vault.
Next, we have a page dedicated to next steps depending on what you'd like to achieve.