From e2a738cf2355cbc2fc7a840da0d71649e7c756cb Mon Sep 17 00:00:00 2001 From: badra001 Date: Tue, 18 Oct 2022 07:29:22 -0400 Subject: [PATCH] add readme --- vpc-transit-gateway-association/README.md | 105 ++++++++++++++++++++++ 1 file changed, 105 insertions(+) diff --git a/vpc-transit-gateway-association/README.md b/vpc-transit-gateway-association/README.md index 84c6c4c..8727fb0 100644 --- a/vpc-transit-gateway-association/README.md +++ b/vpc-transit-gateway-association/README.md @@ -1,3 +1,107 @@ +# About aws-vpc-setup :: vpc-transit-gateway-association + +This sets up the necessary transit gateway configuration for attaching a VPC with all of the components. This is part of a three +section TGW setup, consisting of data (required), self, and peer (remote(s)). They do the following: + +* [data](data/) + * gets transit gateway ID shared to this account and region + * gets transit gateway route tables +* [self](self/) + * creates routes for the attachment subnets to the transit gatewway + * creates routes to all other things on the transit gateway through a network prefix + * attaches the VPC to the transit gateway + * propagates the route to the associated route tables for the envirornment/VRF + * services is propagated to all +* [peer](peer/) + * creates static routes for transit gateway route tables in a peer region + +# Setup + +Due to the nature of some of the data resources and `for_each` not being able to be determined properly, this is split into three +parts. The first part, `data`, must be completed prior to the others. It collects the needed data resources and returns in `module.NAME.data_output`. This is suitable for +passing into the other modules in the `data_input`. + +It needs the `network_account_profile` of the account where TGW is defined. This is the *network* account (sa, prod, or other). Permissions needed to +execute in that account are: + +* sts:GetCallerIdentity +* ec2:Describe* +* ec2:DescribeTransit* +* ec2:GetTransit* +* ec2:CreateRoute* +* ram:* +* (to be completed) + +The standard `r-inf-cloud-admin` role (for federation) or `g-inf-cloud-admin` group (for IAM) is appropriate here. + +The `private_subnets_ids` is a list of objects generated from the `module.subnets` module. It looks like this, with one entry per subnet per AZ. Generally, +you should be able to use the output from the module without any further work. + +```hcl +private_subnets_ids = [ + { + "availability_zone" = "us-gov-east-1a" + "id" = "subnet-02299c01ade7093ac" + "label" = "apps-us-gov-east-1a" + "subnet" = "10.128.33.0/26" + "tags" = {} + }, + { + "availability_zone" = "us-gov-east-1b" + "id" = "subnet-096037c26b0959f58" + "label" = "apps-us-gov-east-1b" + "subnet" = "10.128.33.64/26" + "tags" = {} + }, + }, + { + "availability_zone" = "us-gov-east-1c" + "id" = "subnet-0e63ce4fb8547fedc" + "label" = "apps-us-gov-east-1c" + "subnet" = "10.128.33.128/26" + "tags" = {} + }, +# ... +``` + +An `attachment` subnet block is required with one subnet per AZ for the VPC attachment to work. It requires a tag: + +```hcl + "boc:vpc:route-table" = "attachment" +``` + +This should be the smallest subnet possible (IPv4, a /28), defined like this in `variables.subnets.auto.tfvars` (example, see second subnet +block). + +```hcl +private_subnets = [ + { base_cidr = "10.128.32.0/25", label = "endpoints", bits = 2, private = true, tags = {} }, + { base_cidr = "10.128.32.128/26", label = "attachment", bits = 2, private = true, tags = { "boc:vpc:route-table" = "attachment" } }, + { base_cidr = "10.128.33.0/24", label = "apps", bits = 2, private = true, tags = {} }, +] +``` + +The VPC attachment to the TGW is made to one ENI per each AZ. This is the **only** use of this subnet. No workloads should go in here, +or it causes some issues. Here is an [article](https://www.linkedin.com/pulse/aws-transit-gateway-use-dedicated-subnets-just-local-watson) +describing the setup. AWS documentation and best practice also recommends this approach. + +# Usage + +This uses four different AWS providers. + +1. The unqualified provider is the local AWS account and region in which you are working. The all the others use the `network_account_profile`. +1. The `aws.network_account` profile pulls data from the network account. +1. The `aws.self` uses the `network_account_profile` in your current region. +1. The `aws.peer` uses the `network_account_profile` in the target peer region. + +For GovCloud, there are two regions, us-gov-east-1 and us-gov-west-1. You would need use one +*self* and one *peer*. For the Commercial regions, you have multiple peers, each pointing at its respective target region. + +The `route_prefix_list_name` allows you to select a route shared prefix (automatically handled at the network account level) for +simplicity of routing setup to direct traffic through the TGW (vs using 0.0.0.0/0, the default route). A future feature +will allow the use of the default route and add the use of a VPN prefix list. + +```hcl module "vpc_tgw_data" { source = "git@github.e.it.census.gov:terraform-modules/aws-vpc-setup.git//vpc-transit-gateway-association/data?ref=tf-upgrade" providers = { @@ -61,3 +165,4 @@ module "vpc_tgw_peer" { depends_on = [module.vpc_tgw_self] } +```