diff --git a/vpn/README.md b/vpn/README.md
new file mode 100644
index 0000000..6af7cc2
--- /dev/null
+++ b/vpn/README.md
@@ -0,0 +1,89 @@
+# About aws-vpc-setup :: vpn
+
+This sets up a VPN for the specified site (hq or bcc) and all the necessary related components:
+* vpn gateway
+* customer gateway per site
+* vpn connection per site
+
+It generates a password for each site and uses the same one for each of the site's two tunnels.
+
+To download the configuration, follow these directions [page 24 from AWS docs](https://docs.aws.amazon.com/vpn/latest/s2svpn/s2s-vpn-user-guide.pdf):
+
+> To download the configuration file
+> 1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.
+> 1. In the navigation pane, choose Site-to-Site VPN Connections.
+> 1. Select your VPN connection and choose Download Configuration.
+> 1. Select the vendor, platform, and software that corresponds to your customer gateway device or
+> 1oftware. If your device is not listed, choose Generic. Choose Download.
+>    * Vendor: Cisco Systems, Inc.
+>    * Platform: Cisco ASR 1000
+>    * Software: IOS 12.4+
+
+# Usage
+
+```hcl
+module "vpn"
+  source          = "git@github.e.it.census.gov:terraform-modules/aws-vpc-setup.git//vpn"
+  vpc_id          = "vpc-1234568"
+  vpc_full_name   = "vpc2-dice-dev"
+  vpc_environment = "dev"
+  vpn_settings = [
+    { site = "hq",  "bgp_asn_id" = 65510, "ip_address" = "148.129.160.100" },
+    { site = "bcc", "bgp_asn_id" = 65511, "ip_address" = "148.129.90.100"  },
+  ]
+  route_table_ids = [ "rtb-1234", "rtb-2345", "rtb-3456" ]
+  tags            = {}
+}
+```
+
+## Requirements
+
+No requirements.
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
+| <a name="provider_random"></a> [random](#provider\_random) | n/a |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [aws_customer_gateway.vpn](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/customer_gateway) | resource |
+| [aws_vpn_connection.vpn](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpn_connection) | resource |
+| [aws_vpn_gateway.vpn](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpn_gateway) | resource |
+| [aws_vpn_gateway_attachment.vpn](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpn_gateway_attachment) | resource |
+| [aws_vpn_gateway_route_propagation.vpn](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpn_gateway_route_propagation) | resource |
+| [random_string.tunnel_preshared_key](https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/string) | resource |
+| [aws_arn.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/arn) | data source |
+| [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
+| [aws_region.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/region) | data source |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_account_alias"></a> [account\_alias](#input\_account\_alias) | AWS Account Alias | `string` | `""` | no |
+| <a name="input_account_id"></a> [account\_id](#input\_account\_id) | AWS Account ID (default will pull from current user) | `string` | `""` | no |
+| <a name="input_override_prefixes"></a> [override\_prefixes](#input\_override\_prefixes) | Override built-in prefixes by component. This should be used primarily for common infrastructure things | `map(string)` | `{}` | no |
+| <a name="input_route_table_ids"></a> [route\_table\_ids](#input\_route\_table\_ids) | List of created route table IDs for privating routing to be used for VPN route propagation | `list(string)` | `[]` | no |
+| <a name="input_tags"></a> [tags](#input\_tags) | AWS Tags to apply to appropriate resources (S3, KMS).  Do not include safeguard tags here, use the data\_safeguard field for such things. | `map(string)` | `{}` | no |
+| <a name="input_vpc_environment"></a> [vpc\_environment](#input\_vpc\_environment) | VPC environment purpose (infrastructure, common, shared, dev, stage, ite, prod) | `string` | `null` | no |
+| <a name="input_vpc_full_name"></a> [vpc\_full\_name](#input\_vpc\_full\_name) | VPC full name component (vpc{index}-{vpc\_name}) | `string` | `null` | no |
+| <a name="input_vpc_index"></a> [vpc\_index](#input\_vpc\_index) | VPC index number (integer starting at 1) | `number` | `null` | no |
+| <a name="input_vpc_name"></a> [vpc\_name](#input\_vpc\_name) | VPC name component used through the VPC descrbing its purpose (ex: dice-dev) | `string` | `null` | no |
+| <a name="input_vpc_short_name"></a> [vpc\_short\_name](#input\_vpc\_short\_name) | VPC short name component (vpc{index}) | `string` | `null` | no |
+| <a name="input_vpn_settings"></a> [vpn\_settings](#input\_vpn\_settings) | List of VPN setting objects including site, BGP ASN ID, and VPN termination IP | <pre>list(object({<br>    site       = string<br>    bgp_asn_id = number<br>    ip_address = string<br>  }))</pre> | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_vpn_label"></a> [vpn\_label](#output\_vpn\_label) | VPN Label for Description field of Endpoint device (Cisco ASR) |
+| <a name="output_vpn_tunnel_endpoints"></a> [vpn\_tunnel\_endpoints](#output\_vpn\_tunnel\_endpoints) | VPN Tunnel Endpoint IP Addresses |