add readme

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]
 }
+```