This folder shows an example of Terraform code that deploys a Vault cluster
in AWS with auto unseal. Auto unseal is a Vault feature
that automatically unseals each node in the cluster at boot using Amazon KMS.
Without auto unseal, Vault operators are expected to manually unseal each Vault node
after it boots, a cumbersome process that typically requires multiple Vault operators
to each enter a Vault master key shard.
This example creates a private Vault cluster that is accessible only from within
the VPC within the AWS account in which it resides, or other VPCs that are peered
with the Vault VPC. The Vault cluster uses Consul as the storage backend,
so this example also deploys a separate Consul server cluster using the
consul-cluster module from the Consul AWS Module. Each of the
servers in this example has Dnsmasq installed (via the install-dnsmasq module)
or setup-systemd-resolved (in the case of Ubuntu 18.04)
which allows them to use the Consul server cluster for service discovery and thereby
access Vault via DNS using the domain name vault.service.consul.
For more info on how the Vault cluster works, check out the vault-cluster
documentation.
Note: To keep this example as simple to deploy and test as possible, it deploys
the Vault cluster into your default VPC and default subnets, all of which are publicly
accessible. This is OK for learning and experimenting, but for production usage,
we strongly recommend deploying the Vault cluster into the private subnets of a custom VPC.
Billing Warning: Every time you create a KMS key, you're charged $1 for the month,
even if you immediately delete it.
Quick start
git clone this repo to your computer.
Build a Vault and Consul AMI. See the vault-consul-ami example
documentation for instructions. Don't forget to set the variable vault_download_url
with the url of the enterprise version of Vault if you wish to use Vault Enterprise.
Make sure to note down the ID of the AMI.
Open variables.tf, set the environment variables specified at the top of the file,
and fill in any other variables that don't have a default. Put the AMI ID you
previously took note into the ami_id variable and the KMS key alias into
auto_unseal_kms_key_alias.
Run terraform init.
Run terraform apply.
Run the vault-examples-helper.sh script to
print out the IP addresses of the Vault server and some example commands you
can run to interact with the cluster: ../vault-examples-helper/vault-examples-helper.sh.
Ssh to an instance in the vault cluster and run vault operator init to initialize
the cluster, then vault status to check that it is unsealed. If you ssh to a
different node in the cluster, you might have to restart Vault first with
sudo systemctl restart vault.service so it will rejoin the cluster and unseal.
To avoid doing that, you can start your cluster with initially just one node and
start the server, then change the vault_cluster_size variable back to 3 and and
run terraform apply again. The new nodes will join the cluster already unsealed
in this case.
Seal
All data stored by Vault is encrypted with a Master Key which is not stored anywhere
and Vault only ever keeps in memory. When Vault first boots, it does not have the
Master Key in memory, and therefore it can access its storage, but it cannot decrypt
its own data. So you can't really do anything apart from unsealing it or checking
the server status. While Vault is at this state, we say it is "sealed".
Since vault uses Shamir's Secret Sharing, which splits the master key into
pieces, running vault operator unseal <unseal key> adds piece by piece until there
are enough parts to reconstruct the master key. This is done on different machines in the
vault cluster for better security. When Vault is unsealed and it has the recreated
master key in memory, it can then be used to read the stored decryption keys, which
can decrypt the data, and then you can start performing other operations on Vault.
Vault remains unsealed until it reboots or until someone manually reseals it.
Auto-unseal
Vault has a feature that allows automatic unsealing via Amazon KMS. It
allows operators to delegate the unsealing process to AWS, which is useful for failure
situations where the server has to restart and then it will be already unsealed or
for the creation of ephemeral clusters. This process uses an AWS KMS key as
a seal wrap mechanism: it encrypts and decrypts Vault's master key
(and it does so with the whole key, replacing the Shamir's Secret Sharing method).
This feature is enabled by adding a awskms stanza at Vault's configuration. This
module takes this into consideration on the run-vault binary, allowing
you to pass the following flags to it:
--enable-auto-unseal: Enables the AWS KMS Auto-unseal feature and adds the awskms
stanza to the configuration
--auto-unseal-kms-key-id: The key id of the AWS KMS key to be used
--auto-unseal-region: The AWS region where the KMS key lives
In this example, like in other examples, we execute run-vault at the user-data
script, which runs on boot for every node in the Vault cluster. The
key-id is passed to this script by Terraform, after Terraform reads this value from a
data source through the key alias. This means that the AWS key has to be previously
manually created and we are using Terraform just to find this resource, not to
create it. It is important to notice that AWS KMS keys have a cost
per month per key, as well as an API usage cost.
data"aws_kms_alias""vault-example" {
name = "alias/${var.auto_unseal_kms_key_alias}"
}
If you wish to use Vault Enterprise, you still need to apply your Vault
Enterprise License to the cluster with vault write /sys/license "text=$LICENSE_KEY_TEXT".
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":"be1841a927697869a942fb91e86672c646cc32bb"}]},{"name":".gitignore","path":".gitignore","sha":"6c4ebe4426586b7febbaba178294ef59b8272c05"},{"name":"CODEOWNERS","path":"CODEOWNERS","sha":"5949dbc0fa6d4dd6610575e3c878c353d92da44a"},{"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":"1a2de50f26400eda43c1067fccf4aa49b3db8dfe"},{"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":"1411aff0b44e6554a96d0481d0ffa31a1b4a27ea"},{"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","toggled":true},{"name":"main.tf","path":"examples/vault-auto-unseal/main.tf","sha":"56169fcd17ecacb9dd028c7f9e8a1e880a9badd6"},{"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"}],"toggled":true},{"name":"vault-cluster-private","children":[{"name":"README.md","path":"examples/vault-cluster-private/README.md","sha":"ca0abbac27030e0041b221b8c96b68868615d46c"},{"name":"main.tf","path":"examples/vault-cluster-private/main.tf","sha":"8d799c376e723c81a781fee11a5ca279fc6aeac4"},{"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":"34fc05d0337fd83fdb42faa143e6b216a8f6585b"}]},{"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":"5417c9d851c4b9ad99033205e615aff8c9b59cf1"},{"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":"6e1034d29495a9b8895e79f5cf716689782a51cc"},{"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":"64617b4235bca44d381e7007a29d39a02e0edd03"},{"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"}]}],"toggled":true},{"name":"main.tf","path":"main.tf","sha":"3e2db19f150bfb9ae8b8d1b33ce9e20d3b076dde"},{"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":"57720d8462ddd0a472082d76f1605ea32c443612"}]},{"name":"run-vault","children":[{"name":"README.md","path":"modules/run-vault/README.md","sha":"b2f1e1e074ffd65b4c715675bd59657c6eac6992"},{"name":"run-vault","path":"modules/run-vault/run-vault","sha":"192feb7aa74fde7c93df0e091352780adfeb46c4"}]},{"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":"d8e6b486f28dc2fc35591d7389e6b2ad4d4bf4df"},{"name":"outputs.tf","path":"modules/vault-cluster/outputs.tf","sha":"ab03f0accf81c6722c79656844acd1fd39b41e87"},{"name":"variables.tf","path":"modules/vault-cluster/variables.tf","sha":"4067580ffe82b3c9aaf558887c413ba2992e9394"}]},{"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":"f6ec2cedeb90b046d4caf020482f0169f872f17d"}]},{"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"}]}]},{"name":"outputs.tf","path":"outputs.tf","sha":"9d46ba8bb2ee80bf8bb1ba3ac5b7660280be3e1c"},{"name":"test","children":[{"name":"Gopkg.lock","path":"test/Gopkg.lock","sha":"568bc5956806e4aed616ba1416be9f34c6297153"},{"name":"Gopkg.toml","path":"test/Gopkg.toml","sha":"0b963bee63cabb891409e7bc306361206047d368"},{"name":"README.md","path":"test/README.md","sha":"dd3f97e937dd02cdd9142d0c25006bd6367e7fef"},{"name":"aws_helpers.go","path":"test/aws_helpers.go","sha":"f686b13f45c0deafbec5215d251c8936e30de421"},{"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":"6dc38ca9feb145131336742a05305a63716a663d"},{"name":"vault_cluster_autounseal_test.go","path":"test/vault_cluster_autounseal_test.go","sha":"6378645baf5b1882e25cc1a9a6ea33c2a499670a"},{"name":"vault_cluster_enterprise_test.go","path":"test/vault_cluster_enterprise_test.go","sha":"4b2ca281392b651c889ea0a6f9b4c4afb703ddee"},{"name":"vault_cluster_private_test.go","path":"test/vault_cluster_private_test.go","sha":"9b4c9c7e3c58a9b87df4ab34952b9f908f890f1b"},{"name":"vault_cluster_public_test.go","path":"test/vault_cluster_public_test.go","sha":"adeceaf1a85f323c920117c27992048335bd38a8"},{"name":"vault_cluster_s3_backend_test.go","path":"test/vault_cluster_s3_backend_test.go","sha":"cb028cf873c350aeb24bf5b01e9574790cf2fddb"},{"name":"vault_helpers.go","path":"test/vault_helpers.go","sha":"68cf62618b5510e55577780c65b48528c39a2c44"},{"name":"vault_main_test.go","path":"test/vault_main_test.go","sha":"905a37d2df09a4053104f163ddbd8d0d8bbab28d"}]},{"name":"variables.tf","path":"variables.tf","sha":"c1e78c623452213f943f69d3a1fac13b3bc3d3d9"}]},"detailsContent":"<h1 class=\"preview__body--title\" id=\"vault-auto-unseal-example\">Vault auto unseal example</h1><div class=\"preview__body--border\"></div><p>This folder shows an example of Terraform code that deploys a <a href=\"https://www.vaultproject.io/\" class=\"preview__body--description--blue\" target=\"_blank\">Vault</a> cluster\nin AWS with <a href=\"https://www.vaultproject.io/docs/enterprise/auto-unseal/index.html\" class=\"preview__body--description--blue\" target=\"_blank\">auto unseal</a>. Auto unseal is a Vault feature\nthat automatically <a href=\"https://www.vaultproject.io/docs/concepts/seal.html\" class=\"preview__body--description--blue\" target=\"_blank\">unseals</a> each node in the cluster at boot using <a href=\"https://aws.amazon.com/kms/\" class=\"preview__body--description--blue\" target=\"_blank\">Amazon KMS</a>.\nWithout auto unseal, Vault operators are expected to manually unseal each Vault node\nafter it boots, a cumbersome process that typically requires multiple Vault operators\nto each enter a Vault master key shard.</p>\n<p>This example creates a private Vault cluster that is accessible only from within\nthe VPC within the AWS account in which it resides, or other VPCs that are peered\nwith the Vault VPC. The Vault cluster uses <a href=\"https://www.consul.io/\" class=\"preview__body--description--blue\" target=\"_blank\">Consul</a> as the storage backend,\nso this example also deploys a separate Consul server cluster using the\n<a href=\"/repos/terraform-aws-consul/modules/consul-cluster\" class=\"preview__body--description--blue\">consul-cluster module</a> from the Consul AWS Module. Each of the\nservers in this example has <a href=\"http://www.thekelleys.org.uk/dnsmasq/doc.html\" class=\"preview__body--description--blue\" target=\"_blank\">Dnsmasq</a> installed (via the <a href=\"/repos/terraform-aws-consul/modules/install-dnsmasq\" class=\"preview__body--description--blue\">install-dnsmasq module</a>)\nor <a href=\"/repos/terraform-aws-consul/modules/setup-systemd-resolved\" class=\"preview__body--description--blue\">setup-systemd-resolved</a> (in the case of Ubuntu 18.04)\nwhich allows them to use the Consul server cluster for service discovery and thereby\naccess Vault via DNS using the domain name <code>vault.service.consul</code>.</p>\n<p>For more info on how the Vault cluster works, check out the <a href=\"/repos/v0.13.6/terraform-aws-vault/modules/vault-cluster\" class=\"preview__body--description--blue\">vault-cluster</a>\ndocumentation.</p>\n<p><strong>Note</strong>: To keep this example as simple to deploy and test as possible, it deploys\nthe Vault cluster into your default VPC and default subnets, all of which are publicly\naccessible. This is OK for learning and experimenting, but for production usage,\nwe strongly recommend deploying the Vault cluster into the private subnets of a custom VPC.</p>\n<p><strong>Billing Warning</strong>: Every time you create a KMS key, you're charged $1 for the month,\neven if you immediately delete it.</p>\n<h3 class=\"preview__body--subtitle\" id=\"quick-start\">Quick start</h3>\n<ol>\n<li><code>git clone</code> this repo to your computer.</li>\n<li>Build a Vault and Consul AMI. See the <a href=\"/repos/v0.13.6/terraform-aws-vault/examples/vault-consul-ami\" class=\"preview__body--description--blue\">vault-consul-ami example</a>\ndocumentation for instructions. Don't forget to set the variable <code>vault_download_url</code>\nwith the url of the enterprise version of Vault if you wish to use Vault Enterprise.\nMake sure to note down the ID of the AMI.</li>\n<li>Install <a href=\"https://www.terraform.io/\" class=\"preview__body--description--blue\" target=\"_blank\">Terraform</a>.</li>\n<li><a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html\" class=\"preview__body--description--blue\" target=\"_blank\">Create an AWS KMS key</a>. Take note of the key alias.</li>\n<li>Open <code>variables.tf</code>, set the environment variables specified at the top of the file,\nand fill in any other variables that don't have a default. Put the AMI ID you\npreviously took note into the <code>ami_id</code> variable and the KMS key alias into\n<code>auto_unseal_kms_key_alias</code>.</li>\n<li>Run <code>terraform init</code>.</li>\n<li>Run <code>terraform apply</code>.</li>\n<li>Run the <a href=\"/repos/v0.13.6/terraform-aws-vault/examples/vault-examples-helper/vault-examples-helper.sh\" class=\"preview__body--description--blue\">vault-examples-helper.sh script</a> to\nprint out the IP addresses of the Vault server and some example commands you\ncan run to interact with the cluster: <code>../vault-examples-helper/vault-examples-helper.sh</code>.</li>\n<li>Ssh to an instance in the vault cluster and run <code>vault operator init</code> to initialize\nthe cluster, then <code>vault status</code> to check that it is unsealed. If you ssh to a\ndifferent node in the cluster, you might have to restart Vault first with\n<code>sudo systemctl restart vault.service</code> so it will rejoin the cluster and unseal.\nTo avoid doing that, you can start your cluster with initially just one node and\nstart the server, then change the <code>vault_cluster_size</code> variable back to 3 and and\nrun <code>terraform apply again</code>. The new nodes will join the cluster already unsealed\nin this case.</li>\n</ol>\n<h3 class=\"preview__body--subtitle\" id=\"seal\">Seal</h3>\n<p>All data stored by Vault is encrypted with a Master Key which is not stored anywhere\nand Vault only ever keeps in memory. When Vault first boots, it does not have the\nMaster Key in memory, and therefore it can access its storage, but it cannot decrypt\nits own data. So you can't really do anything apart from unsealing it or checking\nthe server status. While Vault is at this state, we say it is "sealed".</p>\n<p>Since vault uses <a href=\"https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing\" class=\"preview__body--description--blue\" target=\"_blank\">Shamir's Secret Sharing</a>, which splits the master key into\npieces, running <code>vault operator unseal <unseal key></code> adds piece by piece until there\nare enough parts to reconstruct the master key. This is done on different machines in the\nvault cluster for better security. When Vault is unsealed and it has the recreated\nmaster key in memory, it can then be used to read the stored decryption keys, which\ncan decrypt the data, and then you can start performing other operations on Vault.\nVault remains unsealed until it reboots or until someone manually reseals it.</p>\n<h3 class=\"preview__body--subtitle\" id=\"auto-unseal\">Auto-unseal</h3>\n<p>Vault has a feature that allows automatic unsealing via Amazon KMS. It\nallows operators to delegate the unsealing process to AWS, which is useful for failure\nsituations where the server has to restart and then it will be already unsealed or\nfor the creation of ephemeral clusters. This process uses an AWS KMS key as\na <a href=\"https://www.vaultproject.io/docs/enterprise/sealwrap/index.html\" class=\"preview__body--description--blue\" target=\"_blank\">seal wrap</a> mechanism: it encrypts and decrypts Vault's master key\n(and it does so with the whole key, replacing the Shamir's Secret Sharing method).</p>\n<p>This feature is enabled by adding a <code>awskms</code> stanza at Vault's configuration. This\nmodule takes this into consideration on the <a href=\"/repos/v0.13.6/terraform-aws-vault/modules/run-vault\" class=\"preview__body--description--blue\"><code>run-vault</code></a> binary, allowing\nyou to pass the following flags to it:</p>\n<ul>\n<li><code>--enable-auto-unseal</code>: Enables the AWS KMS Auto-unseal feature and adds the <code>awskms</code>\nstanza to the configuration</li>\n<li><code>--auto-unseal-kms-key-id</code>: The key id of the AWS KMS key to be used</li>\n<li><code>--auto-unseal-region</code>: The AWS region where the KMS key lives</li>\n</ul>\n<p>In this example, like in other examples, we execute <code>run-vault</code> at the <a href=\"/repos/v0.13.6/terraform-aws-vault/examples/vault-auto-unseal/user-data-vault.sh\" class=\"preview__body--description--blue\"><code>user-data</code>\nscript</a>, which runs on boot for every node in the Vault cluster. The\n<code>key-id</code> is passed to this script by Terraform, after Terraform reads this value from a\ndata source through the key alias. This means that the AWS key has to be previously\nmanually created and we are using Terraform just to find this resource, not to\ncreate it. It is important to notice that AWS KMS keys have a <a href=\"https://aws.amazon.com/kms/pricing/\" class=\"preview__body--description--blue\" target=\"_blank\">cost</a>\nper month per key, as well as an API usage cost.</p>\n<pre><span class=\"hljs-keyword\">data</span> <span class=\"hljs-string\">\"aws_kms_alias\"</span> <span class=\"hljs-string\">\"vault-example\"</span> {\n name = <span class=\"hljs-string\">\"alias/<span class=\"hljs-variable\">${var.auto_unseal_kms_key_alias}</span>\"</span>\n}\n</pre>\n<p>If you wish to use Vault Enterprise, you still need to apply your Vault\nEnterprise License to the cluster with <code>vault write /sys/license "text=$LICENSE_KEY_TEXT"</code>.</p>\n","repoName":"terraform-aws-vault","repoRef":"v0.13.4","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":"/examples/vault-auto-unseal","title":"Repo Browser: HashiCorp Vault","description":"Browse the repos in the Gruntwork Infrastructure as Code Library."}
.circleci
main.tf
