Vault Sandcastle

Quick Start

• Prequisites:

  • Ensure you have credentials for an admin-like AWS user in the terminal shell where you will be running Terraform apply.
  • Run aws sts get-caller-identity to verify your AWS identity.

• Step 1

  • From the project's root directory run terraform init.
  • Run terraform apply
  • Type yes and hit enter.
  • Retrieve the Public DNS name for the created EC2 instance:
    • Via web ui: Navigate to EC2 page, select instance, copy the value for Public IPv4 DNS
    • Via aws cli: run the following command and copy the value for DNS NAME:

      aws ec2 describe-instances \
      --filter Name=instance-state-name,Values=running \
      --output table \
      --query 'sort_by(Reservations[].Instances[].{NAME: Tags[?Key==`Name`].Value | [0], "DNS NAME": PublicDnsName, "INSTANCE ID": InstanceId}, &NAME)'
      

• Step 2

  • Prepend http:// to the public DNS name and append :8200.
  • Set this new value to shell env variable VAULT_ADDR
    • export VAULT_ADDR=http://<Public DNS Name>:8200

• Step 3

  • Run vault status

SSH-ing into an Instance

• Step 1

  • Retrieve the name of the EC2 key pair you use for SSH-ing into EC2 instances.

• Step 2

  • In the project's root directory, create a file called terraform.tfvars.
  • Add your EC2 key pair name value as a variable called ec2_key_pair_name:
    • terraform.tfvars

      ec2_key_pair_name = "<Your EC2 key pair name>"
      

  • Run terraform apply
  • Type yes and hit enter.

• Step 3

  • Once that completes, you should now be able to SSH in to the instance as either the vault user or ec2-user using the instance's public DNS and your EC2 key pair.
    • ssh -i /Users/maxwinslow/.ssh/ec2/us-west-2.pem -A vault@<Public DNS Name>
    • ssh -i /Users/maxwinslow/.ssh/ec2/us-west-2.pem -A ec2-user@<Public DNS Name>
      • Note: The vault user is only created when the Terraform variable bootstrap_vault is set to true. By default this variable is set to true. However, if set to false, the vault user is not created and therefore you cannot ssh into the instance as that user.

• Step 4

  • Run terraform apply
  • Type yes and hit enter.

Scale-in and Out

• Step 1
  • Add your desired number of servers as a variable called desired_capacity in your terraform.tfvars file.
    • terraform.tfvars

      desired_capacity = <YOUR DESIRED # of servers>
      

• Step 2
  • Run terraform apply
  • Type yes and hit enter.

Versioning

• Step 1
  • Add your desired vault version as a variable called vault_version in your terraform.tfvars file.
    • Syntax used is (as an example): 1.17.0, 1.17.0+ent
    • terraform.tfvars

      vault_version = "<YOUR DESIRED vault version>"
      

• Step 2
  • Run terraform apply
  • Type yes and hit enter.
    • Note: Instances with the updated Vault version will only be created on new instances. It will not upgrade existing instances.

Load Balancers

• Step 1
  • Add a variable called create_load_balancer in your terraform.tfvars file and set it to true.
    • terraform.tfvars

      create_load_balancer = true
      

• Step 2
  • Run terraform apply
  • Type yes and hit enter.
  • Note: You can change this to a network load balancer by setting the variable load_balancer_type to network (it is application by default).

Replication

• Step 1
  • Add a variable called create_secondary_cluster in your terraform.tfvars file and set it to true.
    • terraform.tfvars

      create_secondary_cluster = true
      

• Step 2
  • Run terraform apply
  • Type yes and hit enter.

Consul Mode

• Step 1
  • Add a variable called consul_mode in your terraform.tfvars file and set it to true.
    • terraform.tfvars

      consul_mode = true
      

• Step 2
  • Run terraform apply
  • Type yes and hit enter.
  • Note: Set desired_capacity to zero and run a terraform apply before changing this variable.
    Otherwise you're going to have a bad time.

Full Terraform Documentation (generated via terraform-docs)

Modules

Name	Source	Version
consul	./consul	n/a
iam	./iam	n/a
kms	./kms	n/a
load_balancer	./load_balancer	n/a
network	./network	n/a
security	./security	n/a
servers	./servers	n/a

Resources

No resources.

Inputs

Name	Description	Type	Default	Required
ami_name_filters	n/a	list(string)	[ "al2023-ami-2023.4.20240611.0-kernel-6.1-x86_64" ]	no
ami_owners	n/a	list(string)	[ "amazon" ]	no
bootstrap_vault	n/a	bool	true	no
consul_mode	n/a	bool	false	no
consul_version	n/a	string	"1.19.0"	no
create_load_balancer	n/a	bool	false	no
create_secondary_cluster	n/a	bool	false	no
deletion_window_in_days	n/a	number	7	no
desired_capacity	n/a	number	1	no
ec2_key_pair_name	n/a	string	""	no
enable_dns_hostnames	n/a	bool	true	no
instance_type	n/a	string	"t2.micro"	no
kms_key_arn	n/a	string	"*"	no
listener_port	n/a	string	"80"	no
listener_protocol	n/a	string	""	no
load_balancer_port	n/a	number	80	no
load_balancer_type	n/a	string	"application"	no
map_public_ip_on_launch	n/a	bool	true	no
max_size	n/a	number	5	no
min_size	n/a	number	0	no
most_recent_ami	n/a	bool	true	no
security_groups	n/a	list(string)	[]	no
server_name	n/a	list(string)	[ "primary", "secondary" ]	no
subnet_a_cidr_block	n/a	string	"10.0.1.0/24"	no
subnet_b_cidr_block	n/a	string	"10.0.2.0/24"	no
subnets	n/a	list(string)	[]	no
target_group_arns	n/a	list(string)	[]	no
target_group_health_check_codes	n/a	string	"200,473"	no
target_group_health_check_path	n/a	string	"/v1/sys/health"	no
target_group_port	n/a	string	"8200"	no
target_group_protocol	n/a	string	"HTTP"	no
vault_api_port	n/a	number	8200	no
vault_cluster_port	n/a	number	8201	no
vault_license	n/a	string	""	no
vault_version	n/a	string	"1.16.0"	no
vpc_cidr_block	n/a	string	"10.0.0.0/16"	no
vpc_id	n/a	string	""	no