This folder contains a script for configuring and running Vault on an AWS server. This
script has been tested on the following operating systems:
Ubuntu 16.04
Ubuntu 18.04
Amazon Linux 2
There is a good chance it will work on other flavors of Debian, CentOS, and RHEL as well.
Quick start
This script assumes you installed it, plus all of its dependencies (including Vault itself), using the install-vault
module. The default install path is /opt/vault/bin, so to start Vault in server mode, you
run:
Generate a Vault configuration file called default.hcl in the Vault config dir (default: /opt/vault/config).
See Vault configuration for details on what this configuration file will contain and how
to override it with your own configuration.
Generate a systemd service file called vault.service in the systemd
config dir (default: /etc/systemd/system) with a command that will run Vault:
vault server -config=/opt/vault/config.
Tell systemd to load the new configuration file, thereby starting Vault.
We recommend using the run-vault command as part of User
Data, so that it executes
when the EC2 Instance is first booting. After running run-vault on that initial boot, the systemd configuration
will automatically restart Vault if it crashes or the EC2 instance reboots.
Note that systemd logs to its own journal by default. To view the Vault logs, run journalctl -u vault.service. To change
the log output location, you can specify the StandardOutput and StandardError options by using the --systemd-stdout and --systemd-stderr
options. See the systemd.exec man pages for available
options, but note that the file:path option requires systemd version >= 236, which is not provided
in the base Ubuntu 16.04 and Amazon Linux 2 images.
The run-vault script accepts the following arguments:
--tls-cert-file (required): Specifies the path to the certificate for TLS. To configure the listener to use a CA
certificate, concatenate the primary certificate and the CA certificate together. The primary certificate should
appear first in the combined file. See How do you handle encryption? for more info.
--tls-key-file (required): Specifies the path to the private key for the certificate. See How do you handle
encryption? for more info.
--port (optional): The port Vault should listen on. Default is 8200.
--log-level (optional): The log verbosity to use with Vault. Default is info.
--systemd-stdout (optional): The StandardOutput option of the systemd unit. If not specified, it will use systemd's default (journal).
--systemd-stderr (optional): The StandardError option of the systemd unit. If not specified, it will use systemd's default (inherit).
--cluster-port (optional): The port Vault should listen on for server-to-server communication. Default is
--port + 1.
--api-addr: The full address to use for Client Redirection when running Vault in HA mode. Defaults to "https://[instance_ip]:8200". Optional.
config-dir (optional): The path to the Vault config folder. Default is to take the absolute path of ../config,
relative to the run-vault script itself.
user (optional): The user to run Vault as. Default is to use the owner of config-dir.
skip-vault-config (optional): If this flag is set, don't generate a Vault configuration file. This is useful if you
have a custom configuration file and don't want to use any of of the default settings from run-vault.
--enable-s3-backend (optional): If this flag is set, an S3 backend will be enabled in addition to the HA Consul backend.
--s3-bucket (optional): Specifies the S3 bucket to use to store Vault data. Only used if --enable-s3-backend is set.
--s3-bucket-path (optional): Specifies the S3 bucket path to use to store Vault data. Default is "". Only used if --enable-s3-backend is set.
--s3-bucket-region (optional): Specifies the AWS region where --s3-bucket lives. Only used if --enable-s3-backend is set.
Optional Arguments for enabling the AWS KMS seal (Vault Enterprise only):
--enable-auto-unseal: If this flag is set, enable the AWS KMS Auto-unseal feature. Default is false.
--auto-unseal-kms-key-id: The key id of the AWS KMS key to be used for encryption and decryption. Required if --enable-auto-unseal is enabled.
--auto-unseal-kms-key-region: The AWS region where the encryption key lives. Required if --enable-auto-unseal is enabled.
--auto-unseal-endpoint: The KMS API endpoint to be used to make AWS KMS requests. Optional. Defaults to "". Only used if --enable-auto-unseal is enabled.
run-vault generates a configuration file for Vault called default.hcl that tries to figure out reasonable
defaults for a Vault cluster in AWS. Check out the Vault Configuration Files
documentation for what configuration settings are
available.
Default configuration
run-vault sets the following configuration values by default:
ui:
Set to "ui = true" only when the installed vault version is >=0.10.0.
api_addr:
Set to https://<PRIVATE_IP>:<PORT> where PRIVATE_IP is the Instance's private IP fetched from
Metadata and PORT is
the value passed to --port.
cluster_addr:
Set to https://<PRIVATE_IP>:<CLUSTER_PORT> where PRIVATE_IP is the Instance's private IP fetched from
Metadata and CLUSTER_PORT is
the value passed to --cluster-port.
storage: Configure Consul as the storage backend
with the following settings:
address: Set the address to
127.0.0.1:8500. This is based on the assumption that the Consul agent is running on the same server.
scheme: Set to http since our
connection is to a Consul agent running on the same server.
To override the default configuration, simply put your own configuration file in the Vault config folder (default:
/opt/vault/config), but with a name that comes later in the alphabet than default.hcl (e.g.
my-custom-config.hcl). Vault will load all the .hcl configuration files in the config dir and merge them together
in alphabetical order, so that settings in files that come later in the alphabet will override the earlier ones.
For example, to set a custom cluster_name setting, you could create a file called name.hcl with the
contents:
cluster_name = "my-custom-name"
If you want to override all the default settings, you can tell run-vault not to generate a default config file
at all using the --skip-vault-config flag:
Since this Vault Module uses Consul as a storage backend (and optionally S3), you may want to enable encryption for your storage too.
Note that Vault encrypts any data before sending it to a storage backend, so this isn't strictly necessary, but may be a good
extra layer of security.
By default, the Vault server nodes communicate with a local Consul agent running on the same server over (unencrypted)
HTTP. However, you can configure those agents to talk to the Consul servers using TLS. Check out the official Consul
encryption docs and the Consul AWS Module How do you handle
encryption docs
for more info.
Questions? Ask away.
We're here to talk about our services, answer any questions, give advice, or just to chat.
{"treedata":{"name":"root","toggled":true,"children":[{"name":".circleci","children":[{"name":"config.yml","path":".circleci/config.yml","sha":"0e379399b7494d3efca5978809c98533993290b5"}]},{"name":".gitignore","path":".gitignore","sha":"6c4ebe4426586b7febbaba178294ef59b8272c05"},{"name":"CODEOWNERS","path":"CODEOWNERS","sha":"4be01a6334d39aa5bf6abe6baae701f5e2a8c5ac"},{"name":"CONTRIBUTING.md","path":"CONTRIBUTING.md","sha":"ea1ca5c8d6ff2d0d62880ee0ea80ef86e0b87dad"},{"name":"LICENSE","path":"LICENSE","sha":"7a4a3ea2424c09fbe48d455aed1eaa94d9124835"},{"name":"NOTICE","path":"NOTICE","sha":"2288082e33ae18a610f6a7747180f7e05e47a001"},{"name":"README.md","path":"README.md","sha":"b1ffac4814fb27564190757df0ebedb4283a27a0"},{"name":"_ci","children":[{"name":"publish-amis-in-new-account.md","path":"_ci/publish-amis-in-new-account.md","sha":"3182a0a90775f7bb9622c037196ac2a1f15e455d"},{"name":"publish-amis.sh","path":"_ci/publish-amis.sh","sha":"3d4a46a02f26d45a5fc27cce07cd3db7bc140399"}]},{"name":"_docs","children":[{"name":"amazon-linux-ami-list.md","path":"_docs/amazon-linux-ami-list.md","sha":"be9f50c689839b099d0222711ec13a86108660f0"},{"name":"architecture-elb.png","path":"_docs/architecture-elb.png","sha":"9e02e4f53afdd2929ec4fc4246ae5e47bd49f295"},{"name":"architecture-with-s3.png","path":"_docs/architecture-with-s3.png","sha":"8a91ef2d06665e40fe82a8ccf7ae4281f338fd50"},{"name":"architecture.png","path":"_docs/architecture.png","sha":"a9f6098b37b1aaafe8c744b154208efc3e642881"},{"name":"ubuntu16-ami-list.md","path":"_docs/ubuntu16-ami-list.md","sha":"60caafe1f2b90046e819f373ed22c0df47043f03"}]},{"name":"examples","children":[{"name":"root-example","children":[{"name":"README.md","path":"examples/root-example/README.md","sha":"4d73916c181c9c4157905162d4ed66d2d7427342"},{"name":"user-data-consul.sh","path":"examples/root-example/user-data-consul.sh","sha":"5043e6904cab4564ed0c7f8337599a884f96a194"},{"name":"user-data-vault.sh","path":"examples/root-example/user-data-vault.sh","sha":"26fad57bb49a78e4e2a4b7ce52427efb27e87ced"}]},{"name":"vault-agent","children":[{"name":"README.md","path":"examples/vault-agent/README.md","sha":"0a80c92a455171b6af0e1774a1e67adee32579d6"},{"name":"main.tf","path":"examples/vault-agent/main.tf","sha":"92b325fb802329e6a754a865da644bd8af547e30"},{"name":"outputs.tf","path":"examples/vault-agent/outputs.tf","sha":"16bb9676e7fa2ec2bb5148c5ca5763d7c01db837"},{"name":"user-data-auth-client.sh","path":"examples/vault-agent/user-data-auth-client.sh","sha":"9ff5ebc6c45f791f9357a71a7f3415f1e333b61e"},{"name":"user-data-consul.sh","path":"examples/vault-agent/user-data-consul.sh","sha":"0c96497e38b05e5b5a54277c95ae129827a3daa2"},{"name":"user-data-vault.sh","path":"examples/vault-agent/user-data-vault.sh","sha":"49983b4b543bd7d28c2adde81629d4a3867ffe13"},{"name":"variables.tf","path":"examples/vault-agent/variables.tf","sha":"9abf58af8a0dc24bd445a1b779f07fcf48a05a0e"}]},{"name":"vault-auto-unseal","children":[{"name":"README.md","path":"examples/vault-auto-unseal/README.md","sha":"770b559d99f84ce103f01fddcdc10c1fef58d482"},{"name":"main.tf","path":"examples/vault-auto-unseal/main.tf","sha":"9ede6183a7c35f7d5dca9a20f5c473c6263c464e"},{"name":"outputs.tf","path":"examples/vault-auto-unseal/outputs.tf","sha":"9e7ebd3be30c61662e8647cfecfec210de53e6d2"},{"name":"user-data-consul.sh","path":"examples/vault-auto-unseal/user-data-consul.sh","sha":"0c96497e38b05e5b5a54277c95ae129827a3daa2"},{"name":"user-data-vault.sh","path":"examples/vault-auto-unseal/user-data-vault.sh","sha":"1d9533ea3ba6f9b89242ce503e8b7ea1e59579ba"},{"name":"variables.tf","path":"examples/vault-auto-unseal/variables.tf","sha":"03847da844d2c5a5c24a27872324da11249d11de"}]},{"name":"vault-cluster-private","children":[{"name":"README.md","path":"examples/vault-cluster-private/README.md","sha":"9467091dc2b6475148cecf2d9c84ed387d78d4a8"},{"name":"main.tf","path":"examples/vault-cluster-private/main.tf","sha":"2f88595829383d4b992b1e5281c868c4b0c2023b"},{"name":"outputs.tf","path":"examples/vault-cluster-private/outputs.tf","sha":"9e7ebd3be30c61662e8647cfecfec210de53e6d2"},{"name":"user-data-consul.sh","path":"examples/vault-cluster-private/user-data-consul.sh","sha":"5043e6904cab4564ed0c7f8337599a884f96a194"},{"name":"user-data-vault.sh","path":"examples/vault-cluster-private/user-data-vault.sh","sha":"ef32d804ab9f1807730bae1551fc3fd3fff6da95"},{"name":"variables.tf","path":"examples/vault-cluster-private/variables.tf","sha":"3e919aff20454c6ef004986d3f28b7f65c5d9379"}]},{"name":"vault-consul-ami","children":[{"name":"README.md","path":"examples/vault-consul-ami/README.md","sha":"97b6eeaf3f45cb12b227eb47059042630ec342a4"},{"name":"auth","children":[{"name":"sign-request.py","path":"examples/vault-consul-ami/auth/sign-request.py","sha":"cba97708676a0d3aa8068ee1b5ecb3bf8d14067f"}]},{"name":"tls","children":[{"name":"README.md","path":"examples/vault-consul-ami/tls/README.md","sha":"92f88219562304b995bd78889a24047bdde336af"},{"name":"ca.crt.pem","path":"examples/vault-consul-ami/tls/ca.crt.pem","sha":"9bf1a62b0649d1ab5c0b16710166c146a1fd1fa3"},{"name":"vault.crt.pem","path":"examples/vault-consul-ami/tls/vault.crt.pem","sha":"e642f0b108bfdebe56331111ce9ce75f8ff42f52"},{"name":"vault.key.pem","path":"examples/vault-consul-ami/tls/vault.key.pem","sha":"0103aa55a5a68ffc002c7c9c14a292adbd97fd2d"}]},{"name":"vault-consul.json","path":"examples/vault-consul-ami/vault-consul.json","sha":"4ca1f5c3c396ab201c5521c6d9efd18fa02faca8"}]},{"name":"vault-dynamodb-backend","children":[{"name":"README.md","path":"examples/vault-dynamodb-backend/README.md","sha":"2249ed2b41e02d06f44df46da19bb344c2f3f912"},{"name":"dynamodb","children":[{"name":"main.tf","path":"examples/vault-dynamodb-backend/dynamodb/main.tf","sha":"7405fba8bd36bc376fe09282d1b2741411c5ed5f"},{"name":"variables.tf","path":"examples/vault-dynamodb-backend/dynamodb/variables.tf","sha":"c48d524ca416c19f4d96a7b860342c07252a8587"}]},{"name":"main.tf","path":"examples/vault-dynamodb-backend/main.tf","sha":"1452cad776f0355c73496d9cbb5cbc79d3bcbf6a"},{"name":"outputs.tf","path":"examples/vault-dynamodb-backend/outputs.tf","sha":"f57334a298c9a9f4eb0c3aaae70619cda73ccbb9"},{"name":"user-data-vault.sh","path":"examples/vault-dynamodb-backend/user-data-vault.sh","sha":"6ff712c8839ce577cb8229df9a6e17685da2820f"},{"name":"variables.tf","path":"examples/vault-dynamodb-backend/variables.tf","sha":"928f9b9e96dda6aa85429d27ab6badb87bfd5314"}]},{"name":"vault-ec2-auth","children":[{"name":"README.md","path":"examples/vault-ec2-auth/README.md","sha":"29af1121fa99b3903b09447c79e127daecb30bfb"},{"name":"images","children":[{"name":"ec2-auth.png","path":"examples/vault-ec2-auth/images/ec2-auth.png","sha":"a98fb916ed6a32204efbc525cac59c0d570d619d"}]},{"name":"main.tf","path":"examples/vault-ec2-auth/main.tf","sha":"0ca10db2a94036ead8cee3068357871ed4279b9a"},{"name":"outputs.tf","path":"examples/vault-ec2-auth/outputs.tf","sha":"8694fbce70e13690b8bca4bab50d2570dcd7bdd9"},{"name":"user-data-auth-client.sh","path":"examples/vault-ec2-auth/user-data-auth-client.sh","sha":"e049ec6dca2d35d6fde5badec4e48ecafe8bfc38"},{"name":"user-data-consul.sh","path":"examples/vault-ec2-auth/user-data-consul.sh","sha":"0c96497e38b05e5b5a54277c95ae129827a3daa2"},{"name":"user-data-vault.sh","path":"examples/vault-ec2-auth/user-data-vault.sh","sha":"dd8a73e43e9a4c42e4687ad4cc3c84a543ce548a"},{"name":"variables.tf","path":"examples/vault-ec2-auth/variables.tf","sha":"f04b84eac1668fa2ca3b92d50b27ca6139fde834"}]},{"name":"vault-examples-helper","children":[{"name":"README.md","path":"examples/vault-examples-helper/README.md","sha":"a28a95258bee372025e4282daf60a20d1bf96bdb"},{"name":"vault-examples-helper.sh","path":"examples/vault-examples-helper/vault-examples-helper.sh","sha":"ebe3d8b9bb599384add9a7c635b397529b10fde5"}]},{"name":"vault-iam-auth","children":[{"name":"README.md","path":"examples/vault-iam-auth/README.md","sha":"7557e5abb41341b82464a36eebd0e759d857625d"},{"name":"images","children":[{"name":"iam-auth.png","path":"examples/vault-iam-auth/images/iam-auth.png","sha":"095dcd0060f6cd1f5dad3be9d5ec83dcbba8316f"}]},{"name":"main.tf","path":"examples/vault-iam-auth/main.tf","sha":"9c2aa5a4d20ddaa65257f2eeee5d82d5f413154c"},{"name":"outputs.tf","path":"examples/vault-iam-auth/outputs.tf","sha":"16bb9676e7fa2ec2bb5148c5ca5763d7c01db837"},{"name":"user-data-auth-client.sh","path":"examples/vault-iam-auth/user-data-auth-client.sh","sha":"4122511229818b6ddf8fe03fd2c314f8a1521ee2"},{"name":"user-data-consul.sh","path":"examples/vault-iam-auth/user-data-consul.sh","sha":"0c96497e38b05e5b5a54277c95ae129827a3daa2"},{"name":"user-data-vault.sh","path":"examples/vault-iam-auth/user-data-vault.sh","sha":"1f32c36dc968467fc59b44f624638e1437703fb9"},{"name":"variables.tf","path":"examples/vault-iam-auth/variables.tf","sha":"9abf58af8a0dc24bd445a1b779f07fcf48a05a0e"}]},{"name":"vault-s3-backend","children":[{"name":"README.md","path":"examples/vault-s3-backend/README.md","sha":"e37fbaec6982c87a87a16d3499db3c17f85dbbfd"},{"name":"main.tf","path":"examples/vault-s3-backend/main.tf","sha":"3d1a11d29a2e840a04cb111f3037d433da1460ec"},{"name":"outputs.tf","path":"examples/vault-s3-backend/outputs.tf","sha":"e1af7046390871d4e63797089c39aebab5d9ac26"},{"name":"user-data-consul.sh","path":"examples/vault-s3-backend/user-data-consul.sh","sha":"5043e6904cab4564ed0c7f8337599a884f96a194"},{"name":"user-data-vault.sh","path":"examples/vault-s3-backend/user-data-vault.sh","sha":"cfc21ee0525b0cee2753e1823b8656bf504a910a"},{"name":"variables.tf","path":"examples/vault-s3-backend/variables.tf","sha":"f526eaaa0c65aa5f8be3d4dbde0dd453781d4461"}]}]},{"name":"main.tf","path":"main.tf","sha":"5ae7851952d5f109d726ecec80d41b029115f5dd"},{"name":"modules","children":[{"name":"install-vault","children":[{"name":"README.md","path":"modules/install-vault/README.md","sha":"6bb7538adb7dd8f8527690d96fc06d701cd79462"},{"name":"install-vault","path":"modules/install-vault/install-vault","sha":"e1564049029f50af3507fb2e57dc188c607cb1aa"}]},{"name":"private-tls-cert","children":[{"name":"README.md","path":"modules/private-tls-cert/README.md","sha":"42f2d131477fae97cdfaeef893b3c916f2f7f209"},{"name":"main.tf","path":"modules/private-tls-cert/main.tf","sha":"f906b61efe2b5356bcf759dc60c47a89cf853894"},{"name":"outputs.tf","path":"modules/private-tls-cert/outputs.tf","sha":"078afd869917866e91d2beab7f91fa0d14af524e"},{"name":"variables.tf","path":"modules/private-tls-cert/variables.tf","sha":"a33036ca45da4c834460d58311041401a63575b9"}]},{"name":"run-vault","children":[{"name":"README.md","path":"modules/run-vault/README.md","sha":"b2f1e1e074ffd65b4c715675bd59657c6eac6992","toggled":true},{"name":"run-vault","path":"modules/run-vault/run-vault","sha":"c7982409275a9e0da41379a8eb725cbda9f932d7"}],"toggled":true},{"name":"update-certificate-store","children":[{"name":"README.md","path":"modules/update-certificate-store/README.md","sha":"1348a7aba71475b5a17d31f3f8d66663f656e672"},{"name":"update-certificate-store","path":"modules/update-certificate-store/update-certificate-store","sha":"e07d9a1d997843d62033ee019121895c91e29447"}]},{"name":"vault-cluster","children":[{"name":"README.md","path":"modules/vault-cluster/README.md","sha":"7b4c4ee5f59dc3a216154c4402acd70b96d6585f"},{"name":"main.tf","path":"modules/vault-cluster/main.tf","sha":"6838267cceea00aef7446fd41e6aef5c6b123c61"},{"name":"outputs.tf","path":"modules/vault-cluster/outputs.tf","sha":"ab03f0accf81c6722c79656844acd1fd39b41e87"},{"name":"variables.tf","path":"modules/vault-cluster/variables.tf","sha":"5d2276d06c36b71f2ecea9b48aab345e3ce9c9f0"}]},{"name":"vault-elb","children":[{"name":"README.md","path":"modules/vault-elb/README.md","sha":"9dc6564baaaaa8176f650e3c548b8c8066631b6f"},{"name":"main.tf","path":"modules/vault-elb/main.tf","sha":"0f85aea4f41332461dadcda41e767f983d53ad66"},{"name":"outputs.tf","path":"modules/vault-elb/outputs.tf","sha":"024b1c73b457ed1c9256b39fc3ee283b39ed6544"},{"name":"variables.tf","path":"modules/vault-elb/variables.tf","sha":"40d18feef81848f2e1da3d293ead59438f9b9fae"}]},{"name":"vault-security-group-rules","children":[{"name":"README.md","path":"modules/vault-security-group-rules/README.md","sha":"48df12587b14b7a0d93333b6c12c19dc7082d8b0"},{"name":"main.tf","path":"modules/vault-security-group-rules/main.tf","sha":"c42c6e6d296dd17c021b134bb2f4c5774cf0079c"},{"name":"variables.tf","path":"modules/vault-security-group-rules/variables.tf","sha":"2e18f3fef1b2ff2b3a32f62a49085480ed61763e"}]}],"toggled":true},{"name":"outputs.tf","path":"outputs.tf","sha":"9d46ba8bb2ee80bf8bb1ba3ac5b7660280be3e1c"},{"name":"test","children":[{"name":"README.md","path":"test/README.md","sha":"dd3f97e937dd02cdd9142d0c25006bd6367e7fef"},{"name":"aws_helpers.go","path":"test/aws_helpers.go","sha":"f686b13f45c0deafbec5215d251c8936e30de421"},{"name":"go.mod","path":"test/go.mod","sha":"ca3620dd7dd203eaf75729f2f1d0052ff5c99a7e"},{"name":"go.sum","path":"test/go.sum","sha":"f42d242737e8b02b81830be0234824df95bff55a"},{"name":"terratest_helpers.go","path":"test/terratest_helpers.go","sha":"61cb21eeaa80d5c93a2eb1d61964991b6710a770"},{"name":"tls_helpers.go","path":"test/tls_helpers.go","sha":"9b95b015104a0c7a684f6f3af999407218121619"},{"name":"vault_cluster_auth_test.go","path":"test/vault_cluster_auth_test.go","sha":"cd9c38a6c70e45694019e6fdb7ea07aa588e02ca"},{"name":"vault_cluster_autounseal_test.go","path":"test/vault_cluster_autounseal_test.go","sha":"c6a32ad54851789044b616c537770a9bd25d3e7e"},{"name":"vault_cluster_dynamodb_backend_test.go","path":"test/vault_cluster_dynamodb_backend_test.go","sha":"c2914c1ba3e7d6beda8db1c0a2b73d526b7c6155"},{"name":"vault_cluster_enterprise_test.go","path":"test/vault_cluster_enterprise_test.go","sha":"4e4aad4f69b04bf7e5233e61fd7efc107e166df0"},{"name":"vault_cluster_private_test.go","path":"test/vault_cluster_private_test.go","sha":"f115b3363e92f26f79e94e56e6551484ed74f455"},{"name":"vault_cluster_public_test.go","path":"test/vault_cluster_public_test.go","sha":"54f9497b60bb84b8383c8785ff11394abd665ba4"},{"name":"vault_cluster_s3_backend_test.go","path":"test/vault_cluster_s3_backend_test.go","sha":"4d9405cc0db461ecf249e6f4ba4098ca94066c26"},{"name":"vault_helpers.go","path":"test/vault_helpers.go","sha":"ef041cc120113a63f9c29a78ba35f110bd2bead6"},{"name":"vault_main_test.go","path":"test/vault_main_test.go","sha":"c8553814ba9d854a5258df835fc7191b3166fbfe"}]},{"name":"variables.tf","path":"variables.tf","sha":"c1e78c623452213f943f69d3a1fac13b3bc3d3d9"}]},"detailsContent":"<h1 class=\"preview__body--title\" id=\"vault-run-script\">Vault Run Script</h1><div class=\"preview__body--border\"></div><p>This folder contains a script for configuring and running Vault on an <a href=\"https://aws.amazon.com/\" class=\"preview__body--description--blue\" target=\"_blank\">AWS</a> server. This\nscript has been tested on the following operating systems:</p>\n<ul>\n<li>Ubuntu 16.04</li>\n<li>Ubuntu 18.04</li>\n<li>Amazon Linux 2</li>\n</ul>\n<p>There is a good chance it will work on other flavors of Debian, CentOS, and RHEL as well.</p>\n<h2 class=\"preview__body--subtitle\" id=\"quick-start\">Quick start</h2>\n<p>This script assumes you installed it, plus all of its dependencies (including Vault itself), using the <a href=\"/repos/v0.16.0/terraform-aws-vault/modules/install-vault\" class=\"preview__body--description--blue\">install-vault\nmodule</a>. The default install path is <code>/opt/vault/bin</code>, so to start Vault in server mode, you\nrun:</p>\n<pre><span class=\"hljs-regexp\">/opt/</span>vault<span class=\"hljs-regexp\">/bin/</span>run-vault --tls-cert-<span class=\"hljs-keyword\">file</span> <span class=\"hljs-regexp\">/opt/</span>vault<span class=\"hljs-regexp\">/tls/</span>vault.crt.pem --tls-key-<span class=\"hljs-keyword\">file</span> <span class=\"hljs-regexp\">/opt/</span>vault<span class=\"hljs-regexp\">/tls/</span>vault.key.pem\n</pre>\n<p>This will:</p>\n<ol>\n<li>\n<p>Generate a Vault configuration file called <code>default.hcl</code> in the Vault config dir (default: <code>/opt/vault/config</code>).\nSee <a href=\"#vault-configuration\" class=\"preview__body--description--blue\">Vault configuration</a> for details on what this configuration file will contain and how\nto override it with your own configuration.</p>\n</li>\n<li>\n<p>Generate a <a href=\"https://www.freedesktop.org/wiki/Software/systemd/\" class=\"preview__body--description--blue\" target=\"_blank\">systemd</a> service file called <code>vault.service</code> in the systemd\nconfig dir (default: <code>/etc/systemd/system</code>) with a command that will run Vault:\n<code>vault server -config=/opt/vault/config</code>.</p>\n</li>\n<li>\n<p>Tell systemd to load the new configuration file, thereby starting Vault.</p>\n</li>\n</ol>\n<p>We recommend using the <code>run-vault</code> command as part of <a href=\"http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html#user-data-shell-scripts\" class=\"preview__body--description--blue\" target=\"_blank\">User\nData</a>, so that it executes\nwhen the EC2 Instance is first booting. After running <code>run-vault</code> on that initial boot, the <code>systemd</code> configuration\nwill automatically restart Vault if it crashes or the EC2 instance reboots.</p>\n<p>Note that <code>systemd</code> logs to its own journal by default. To view the Vault logs, run <code>journalctl -u vault.service</code>. To change\nthe log output location, you can specify the <code>StandardOutput</code> and <code>StandardError</code> options by using the <code>--systemd-stdout</code> and <code>--systemd-stderr</code>\noptions. See the <a href=\"https://www.freedesktop.org/software/systemd/man/systemd.exec.html#StandardOutput=\" class=\"preview__body--description--blue\" target=\"_blank\"><code>systemd.exec</code> man pages</a> for available\noptions, but note that the <code>file:path</code> option requires <a href=\"https://stackoverflow.com/a/48052152\" class=\"preview__body--description--blue\" target=\"_blank\">systemd version >= 236</a>, which is not provided\nin the base Ubuntu 16.04 and Amazon Linux 2 images.</p>\n<p>See the <a href=\"/repos/v0.16.0/terraform-aws-vault/examples/root-example\" class=\"preview__body--description--blue\">root example</a> and\n<a href=\"/repos/v0.16.0/terraform-aws-vault/examples/vault-cluster-private\" class=\"preview__body--description--blue\">vault-cluster-private</a> examples for fully-working sample code.</p>\n<h2 class=\"preview__body--subtitle\" id=\"command-line-arguments\">Command line Arguments</h2>\n<p>The <code>run-vault</code> script accepts the following arguments:</p>\n<ul>\n<li><code>--tls-cert-file</code> (required): Specifies the path to the certificate for TLS. To configure the listener to use a CA\ncertificate, concatenate the primary certificate and the CA certificate together. The primary certificate should\nappear first in the combined file. See <a href=\"#how-do-you_handle-encryption\" class=\"preview__body--description--blue\">How do you handle encryption?</a> for more info.</li>\n<li><code>--tls-key-file</code> (required): Specifies the path to the private key for the certificate. See <a href=\"#how-do-you_handle-encryption\" class=\"preview__body--description--blue\">How do you handle\nencryption?</a> for more info.</li>\n<li><code>--port</code> (optional): The port Vault should listen on. Default is <code>8200</code>.</li>\n<li><code>--log-level</code> (optional): The log verbosity to use with Vault. Default is <code>info</code>.</li>\n<li><code>--systemd-stdout</code> (optional): The StandardOutput option of the systemd unit. If not specified, it will use systemd's default (journal).</li>\n<li><code>--systemd-stderr</code> (optional): The StandardError option of the systemd unit. If not specified, it will use systemd's default (inherit).</li>\n<li><code>--cluster-port</code> (optional): The port Vault should listen on for server-to-server communication. Default is\n<code>--port + 1</code>.</li>\n<li><code>--api-addr</code>: The full address to use for <a href=\"https://www.vaultproject.io/docs/concepts/ha.html#client-redirection\" class=\"preview__body--description--blue\" target=\"_blank\">Client Redirection</a> when running Vault in HA mode. Defaults to "https://[instance_ip]:8200". Optional.</li>\n<li><code>config-dir</code> (optional): The path to the Vault config folder. Default is to take the absolute path of <code>../config</code>,\nrelative to the <code>run-vault</code> script itself.</li>\n<li><code>user</code> (optional): The user to run Vault as. Default is to use the owner of <code>config-dir</code>.</li>\n<li><code>skip-vault-config</code> (optional): If this flag is set, don't generate a Vault configuration file. This is useful if you\nhave a custom configuration file and don't want to use any of of the default settings from <code>run-vault</code>.</li>\n<li><code>--enable-s3-backend</code> (optional): If this flag is set, an S3 backend will be enabled in addition to the HA Consul backend.</li>\n<li><code>--s3-bucket</code> (optional): Specifies the S3 bucket to use to store Vault data. Only used if <code>--enable-s3-backend</code> is set.</li>\n<li><code>--s3-bucket-path</code> (optional): Specifies the S3 bucket path to use to store Vault data. Default is <code>""</code>. Only used if <code>--enable-s3-backend</code> is set.</li>\n<li><code>--s3-bucket-region</code> (optional): Specifies the AWS region where <code>--s3-bucket</code> lives. Only used if <code>--enable-s3-backend</code> is set.</li>\n</ul>\n<p>Optional Arguments for enabling the AWS KMS seal (Vault Enterprise only):</p>\n<ul>\n<li><code>--enable-auto-unseal</code>: If this flag is set, enable the AWS KMS Auto-unseal feature. Default is false.</li>\n<li><code>--auto-unseal-kms-key-id</code>: The key id of the AWS KMS key to be used for encryption and decryption. Required if <code>--enable-auto-unseal</code> is enabled.</li>\n<li><code>--auto-unseal-kms-key-region</code>: The AWS region where the encryption key lives. Required if --enable-auto-unseal is enabled.</li>\n<li><code>--auto-unseal-endpoint</code>: The KMS API endpoint to be used to make AWS KMS requests. Optional. Defaults to <code>""</code>. Only used if --enable-auto-unseal is enabled.</li>\n</ul>\n<p>Example:</p>\n<pre><span class=\"hljs-regexp\">/opt/</span>vault<span class=\"hljs-regexp\">/bin/</span>run-vault --tls-cert-<span class=\"hljs-keyword\">file</span> <span class=\"hljs-regexp\">/opt/</span>vault<span class=\"hljs-regexp\">/tls/</span>vault.crt.pem --tls-key-<span class=\"hljs-keyword\">file</span> <span class=\"hljs-regexp\">/opt/</span>vault<span class=\"hljs-regexp\">/tls/</span>vault.key.pem\n</pre>\n<p>Or if you want to enable an S3 backend:</p>\n<pre>/<span class=\"hljs-meta\">opt</span>/vault/<span class=\"hljs-keyword\">bin/run-vault </span>--tls-cert-file /<span class=\"hljs-meta\">opt</span>/vault/tls/vault.crt.pem --tls-key-file /<span class=\"hljs-meta\">opt</span>/vault/tls/vault.key.pem --enable-<span class=\"hljs-built_in\">s3</span>-<span class=\"hljs-keyword\">backend </span>--<span class=\"hljs-built_in\">s3</span>-<span class=\"hljs-keyword\">bucket </span>my-vault-<span class=\"hljs-keyword\">bucket </span>--<span class=\"hljs-built_in\">s3</span>-<span class=\"hljs-keyword\">bucket-region </span>us-east-<span class=\"hljs-number\">1</span>\n</pre>\n<h2 class=\"preview__body--subtitle\" id=\"vault-configuration\">Vault configuration</h2>\n<p><code>run-vault</code> generates a configuration file for Vault called <code>default.hcl</code> that tries to figure out reasonable\ndefaults for a Vault cluster in AWS. Check out the <a href=\"https://www.vaultproject.io/docs/configuration/index.html\" class=\"preview__body--description--blue\" target=\"_blank\">Vault Configuration Files\ndocumentation</a> for what configuration settings are\navailable.</p>\n<h3 class=\"preview__body--subtitle\" id=\"default-configuration\">Default configuration</h3>\n<p><code>run-vault</code> sets the following configuration values by default:</p>\n<ul>\n<li>\n<p><a href=\"https://www.vaultproject.io/docs/configuration/index.html#ui\" class=\"preview__body--description--blue\" target=\"_blank\">ui</a>:\nSet to "ui = true" only when the installed vault version is >=0.10.0.</p>\n</li>\n<li>\n<p><a href=\"https://www.vaultproject.io/docs/configuration/index.html#api_addr\" class=\"preview__body--description--blue\" target=\"_blank\">api_addr</a>:\nSet to <code>https://<PRIVATE_IP>:<PORT></code> where <code>PRIVATE_IP</code> is the Instance's private IP fetched from\n<a href=\"http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html\" class=\"preview__body--description--blue\" target=\"_blank\">Metadata</a> and <code>PORT</code> is\nthe value passed to <code>--port</code>.</p>\n</li>\n<li>\n<p><a href=\"https://www.vaultproject.io/docs/configuration/index.html#cluster_addr\" class=\"preview__body--description--blue\" target=\"_blank\">cluster_addr</a>:\nSet to <code>https://<PRIVATE_IP>:<CLUSTER_PORT></code> where <code>PRIVATE_IP</code> is the Instance's private IP fetched from\n<a href=\"http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html\" class=\"preview__body--description--blue\" target=\"_blank\">Metadata</a> and <code>CLUSTER_PORT</code> is\nthe value passed to <code>--cluster-port</code>.</p>\n</li>\n<li>\n<p><a href=\"https://www.vaultproject.io/docs/configuration/index.html#storage\" class=\"preview__body--description--blue\" target=\"_blank\">storage</a>: Configure Consul as the storage backend\nwith the following settings:</p>\n<ul>\n<li><a href=\"https://www.vaultproject.io/docs/configuration/storage/consul.html#address\" class=\"preview__body--description--blue\" target=\"_blank\">address</a>: Set the address to\n<code>127.0.0.1:8500</code>. This is based on the assumption that the Consul agent is running on the same server.</li>\n<li><a href=\"https://www.vaultproject.io/docs/configuration/storage/consul.html#scheme\" class=\"preview__body--description--blue\" target=\"_blank\">scheme</a>: Set to <code>http</code> since our\nconnection is to a Consul agent running on the same server.</li>\n<li><a href=\"https://www.vaultproject.io/docs/configuration/storage/consul.html#path\" class=\"preview__body--description--blue\" target=\"_blank\">path</a>: Set to <code>vault/</code>.</li>\n<li><a href=\"https://www.vaultproject.io/docs/configuration/storage/consul.html#service\" class=\"preview__body--description--blue\" target=\"_blank\">service</a>: Set to <code>vault</code>.</li>\n</ul>\n</li>\n<li>\n<p><a href=\"https://www.vaultproject.io/docs/configuration/index.html#listener\" class=\"preview__body--description--blue\" target=\"_blank\">listener</a>: Configure a <a href=\"https://www.vaultproject.io/docs/configuration/listener/tcp.html\" class=\"preview__body--description--blue\" target=\"_blank\">TCP\nlistener</a> with the following settings:</p>\n<ul>\n<li><a href=\"https://www.vaultproject.io/docs/configuration/listener/tcp.html#address\" class=\"preview__body--description--blue\" target=\"_blank\">address</a>: Bind to <code>0.0.0.0:<PORT></code>\nwhere <code>PORT</code> is the value passed to <code>--port</code>.</li>\n<li><a href=\"https://www.vaultproject.io/docs/configuration/listener/tcp.html#cluster_address\" class=\"preview__body--description--blue\" target=\"_blank\">cluster_address</a>: Bind to\n<code>0.0.0.0:<CLUSTER_PORT></code> where <code>CLUSTER</code> is the value passed to <code>--cluster-port</code>.</li>\n<li><a href=\"https://www.vaultproject.io/docs/configuration/listener/tcp.html#tls_cert_file\" class=\"preview__body--description--blue\" target=\"_blank\">tls_cert_file</a>: Set to the\n<code>--tls-cert-file</code> parameter.</li>\n<li><a href=\"https://www.vaultproject.io/docs/configuration/listener/tcp.html#tls_key_file\" class=\"preview__body--description--blue\" target=\"_blank\">tls_key_file</a>: Set to the\n<code>--tls-key-file</code> parameter.</li>\n</ul>\n</li>\n</ul>\n<p><code>run-vault</code> can optionally set the following configuration values:</p>\n<ul>\n<li>\n<p><a href=\"https://www.vaultproject.io/docs/configuration/index.html#storage\" class=\"preview__body--description--blue\" target=\"_blank\">storage</a>: Set the <code>--enable-s3-backend</code> flag to\nconfigure S3 as an additional (non-HA) storage backend with the following settings:</p>\n<ul>\n<li><a href=\"https://www.vaultproject.io/docs/configuration/storage/s3.html#bucket\" class=\"preview__body--description--blue\" target=\"_blank\">bucket</a>: Set to the <code>--s3-bucket</code>\nparameter.</li>\n<li><a href=\"https://www.vaultproject.io/docs/configuration/storage/s3.html#path\" class=\"preview__body--description--blue\" target=\"_blank\">path</a>: Set to the <code>--s3-bucket-path</code>\nparameter.</li>\n<li><a href=\"https://www.vaultproject.io/docs/configuration/storage/s3.html#region\" class=\"preview__body--description--blue\" target=\"_blank\">region</a>: Set to the <code>--s3-bucket-region</code>\nparameter.</li>\n</ul>\n</li>\n</ul>\n<h3 class=\"preview__body--subtitle\" id=\"overriding-the-configuration\">Overriding the configuration</h3>\n<p>To override the default configuration, simply put your own configuration file in the Vault config folder (default:\n<code>/opt/vault/config</code>), but with a name that comes later in the alphabet than <code>default.hcl</code> (e.g.\n<code>my-custom-config.hcl</code>). Vault will load all the <code>.hcl</code> configuration files in the config dir and merge them together\nin alphabetical order, so that settings in files that come later in the alphabet will override the earlier ones.</p>\n<p>For example, to set a custom <code>cluster_name</code> setting, you could create a file called <code>name.hcl</code> with the\ncontents:</p>\n<pre><span class=\"hljs-attr\">cluster_name</span> = <span class=\"hljs-string\">\"my-custom-name\"</span>\n</pre>\n<p>If you want to override <em>all</em> the default settings, you can tell <code>run-vault</code> not to generate a default config file\nat all using the <code>--skip-vault-config</code> flag:</p>\n<pre><span class=\"hljs-regexp\">/opt/</span>vault<span class=\"hljs-regexp\">/bin/</span>run-vault --tls-cert-<span class=\"hljs-keyword\">file</span> <span class=\"hljs-regexp\">/opt/</span>vault<span class=\"hljs-regexp\">/tls/</span>vault.crt.pem --tls-key-<span class=\"hljs-keyword\">file</span> <span class=\"hljs-regexp\">/opt/</span>vault<span class=\"hljs-regexp\">/tls/</span>vault.key.pem --skip-vault-config\n</pre>\n<h2 class=\"preview__body--subtitle\" id=\"how-do-you-handle-encryption\">How do you handle encryption?</h2>\n<p>Vault uses TLS to encrypt all data in transit. To configure encryption, you must do the following:</p>\n<ol>\n<li><a href=\"#provide-tls-certificates\" class=\"preview__body--description--blue\">Provide TLS certificates</a></li>\n<li><a href=\"#consul-encryption\" class=\"preview__body--description--blue\">Consul encryption</a></li>\n</ol>\n<h3 class=\"preview__body--subtitle\" id=\"provide-tls-certificates\">Provide TLS certificates</h3>\n<p>When you execute the <code>run-vault</code> script, you need to provide the paths to the public and private keys of a TLS\ncertificate:</p>\n<pre><span class=\"hljs-regexp\">/opt/</span>vault<span class=\"hljs-regexp\">/bin/</span>run-vault --tls-cert-<span class=\"hljs-keyword\">file</span> <span class=\"hljs-regexp\">/opt/</span>vault<span class=\"hljs-regexp\">/tls/</span>vault.crt.pem --tls-key-<span class=\"hljs-keyword\">file</span> <span class=\"hljs-regexp\">/opt/</span>vault<span class=\"hljs-regexp\">/tls/</span>vault.key.pem\n</pre>\n<p>See the <a href=\"/repos/v0.16.0/terraform-aws-vault/modules/private-tls-cert\" class=\"preview__body--description--blue\">private-tls-cert module</a> for information on how to generate a TLS certificate.</p>\n<h3 class=\"preview__body--subtitle\" id=\"consul-encryption\">Consul encryption</h3>\n<p>Since this Vault Module uses Consul as a storage backend (and optionally S3), you may want to enable encryption for your storage too.\nNote that Vault encrypts any data <em>before</em> sending it to a storage backend, so this isn't strictly necessary, but may be a good\nextra layer of security.</p>\n<p>By default, the Vault server nodes communicate with a local Consul agent running on the same server over (unencrypted)\nHTTP. However, you can configure those agents to talk to the Consul servers using TLS. Check out the <a href=\"https://www.consul.io/docs/agent/encryption.html\" class=\"preview__body--description--blue\" target=\"_blank\">official Consul\nencryption docs</a> and the Consul AWS Module <a href=\"/repos/terraform-aws-consul/modules/run-consul#how-do-you-handle-encryption\" class=\"preview__body--description--blue\">How do you handle\nencryption docs</a>\nfor more info.</p>\n","repoName":"terraform-aws-vault","repoRef":"v0.13.9","serviceDescriptor":{"serviceName":"HashiCorp Vault","serviceRepoName":"terraform-aws-vault","serviceRepoOrg":"hashicorp","cloudProviders":["aws"],"description":"Deploy a Vault cluster. Supports automatic bootstrapping, Consul and S3 backends, self-signed TLS certificates, and auto healing.","imageUrl":"vault.png","licenseType":"open-source","technologies":["Terraform","Bash"],"compliance":[],"tags":[""]},"serviceCategoryName":"Secrets management","fileName":"README.md","filePath":"/modules/run-vault","title":"Repo Browser: HashiCorp Vault","description":"Browse the repos in the Gruntwork Infrastructure as Code Library."}
.circleci
run-vault
