add docs

peer/README.md

@@ -3,24 +3,55 @@
 This submodule creates a peering connection with a different VPC, and sets up appropriate network
 ACLs and routing between the two CIDR blocks.
 
+You must pass the `providers` block to associate `aws.self` with your local AWS provider (whatever
+its name or alias is) and `aws.peer` with the remote peer AWS provider name or alias.
+
+There are a lot of variables to pass.  Most of them are for labeling.  You can explicitly pass
+the `route_table_ids` and `network_acl_ids` for more control, but by default if you do not, it will
+use the `vpc_id`, find the route tables for `*services*`, find the subnets associated with that/those
+route tables, eliminate those with `public` in the name, and use that to find the network acl IDs.
+For now, until we move to 0.13, this will only use the **first** found network acl ID to create the
+appropriate network acl rules.
+
+This creates:
+* peering in local and remote account
+  * requires `credentials.peers.tf` with appropriate profile and values
+* accepts peering in both locations
+* finds or uses route table IDs to add routes
+  * local CIDR in peer route tables
+  * peer CIDR in local route tables
+* finds or uses network acl IDs to add rules
+  * local all in, all out to peer CIDR
+  * peer all in, all out to local CIDR
+
+It uses the `vpc_index` as an offset (-1) from the `rule_number` and `peer_rule_number`.  For example,
+for `vpc_index=2` (aka, vpc2), the rule number in the NACL rule at `rule_number + 1`.
+
+`peer_tags`, if not passed will default to `tags`.
+
+`vpc_cidr_block` and `peer_vpc_cidr_block` are retrieved from the VPC itself, so it too is optional.
+
 # Usage
 
 ```hcl
 module "peer_services" {
   source               = "git@github.e.it.census.gov:terraform-modules/aws-vpc-setup.git//peer"
+  providers = {
+    aws.self = aws
+    aws.peer = aws.us-gov-east-1
+  }
 
 # self
   vpc_id               = module.vpc.vpc_id
   vpc_name             = var.vpc_name
-  vpc_cidr_block       = var.vpc_cidr_block
+  # vpc_cidr_block       = var.vpc_cidr_block
   vpc_index            = var.vpc_index
   vpc_short_name       = var.vpc_short_name
   vpc_full_name        = var.vpc_full_name
-  vpc_environment      = var.vpc_environment
-  route_table_ids      = [ "rtb-12345678" ]
-  network_acl_ids      = [ "nacl-12345678" ]
+  # route_table_ids      = [ "rtb-12345678" ]
+  # network_acl_ids      = [ "nacl-12345678" ]
   rule_number          = 2500
-  rule_increment       = 1
+  # rule_increment       = 1
   tags = {}
 
 # peer
@@ -31,17 +62,11 @@ module "peer_services" {
   peer_vpc_index            = var.peer_vpc_index
   peer_vpc_short_name       = var.peer_vpc_short_name
   # peer_vpc_full_name        = var.peer_vpc_full_name
-  # peer_vpc_environment      = var.peer_vpc_environment
   # peer_tags = {}
-  peer_route_table_ids      = [ "rtb-87654321" ]
-  peer_network_acl_ids      = [ "nacl-87654321" ]
+  # peer_route_table_ids      = [ "rtb-87654321" ]
+  # peer_network_acl_ids      = [ "nacl-87654321" ]
   peer_rule_number          = 2500
-  peer_rule_increment       = 1
-
-  providers = {
-    aws.self = aws
-    aws.peer = aws.us-gov-east-1
-  }
+  # peer_rule_increment       = 1
 }
 ```
 

peer/main.tf

@@ -3,25 +3,56 @@
 * 
 * This submodule creates a peering connection with a different VPC, and sets up appropriate network
 * ACLs and routing between the two CIDR blocks.
+*
+* You must pass the `providers` block to associate `aws.self` with your local AWS provider (whatever
+* its name or alias is) and `aws.peer` with the remote peer AWS provider name or alias.
+*
+* There are a lot of variables to pass.  Most of them are for labeling.  You can explicitly pass
+* the `route_table_ids` and `network_acl_ids` for more control, but by default if you do not, it will
+* use the `vpc_id`, find the route tables for `*services*`, find the subnets associated with that/those
+* route tables, eliminate those with `public` in the name, and use that to find the network acl IDs.
+* For now, until we move to 0.13, this will only use the **first** found network acl ID to create the
+* appropriate network acl rules.
+*
+* This creates:
+* * peering in local and remote account
+*   * requires `credentials.peers.tf` with appropriate profile and values
+* * accepts peering in both locations
+* * finds or uses route table IDs to add routes
+*   * local CIDR in peer route tables
+*   * peer CIDR in local route tables
+* * finds or uses network acl IDs to add rules
+*   * local all in, all out to peer CIDR
+*   * peer all in, all out to local CIDR
+*
+* It uses the `vpc_index` as an offset (-1) from the `rule_number` and `peer_rule_number`.  For example,
+* for `vpc_index=2` (aka, vpc2), the rule number in the NACL rule at `rule_number + 1`.
+*
+* `peer_tags`, if not passed will default to `tags`.
+*
+* `vpc_cidr_block` and `peer_vpc_cidr_block` are retrieved from the VPC itself, so it too is optional.
 * 
 * # Usage
 * 
 * ```hcl
 * module "peer_services" {
 *   source               = "git@github.e.it.census.gov:terraform-modules/aws-vpc-setup.git//peer"
+*   providers = {
+*     aws.self = aws
+*     aws.peer = aws.us-gov-east-1
+*   }
 *
 * # self
 *   vpc_id               = module.vpc.vpc_id
 *   vpc_name             = var.vpc_name
-*   vpc_cidr_block       = var.vpc_cidr_block
+*   # vpc_cidr_block       = var.vpc_cidr_block
 *   vpc_index            = var.vpc_index
 *   vpc_short_name       = var.vpc_short_name
 *   vpc_full_name        = var.vpc_full_name
-*   vpc_environment      = var.vpc_environment
-*   route_table_ids      = [ "rtb-12345678" ]
-*   network_acl_ids      = [ "nacl-12345678" ]
+*   # route_table_ids      = [ "rtb-12345678" ]
+*   # network_acl_ids      = [ "nacl-12345678" ]
 *   rule_number          = 2500
-*   rule_increment       = 1
+*   # rule_increment       = 1
 *   tags = {}
 *
 * # peer
@@ -32,17 +63,11 @@
 *   peer_vpc_index            = var.peer_vpc_index
 *   peer_vpc_short_name       = var.peer_vpc_short_name
 *   # peer_vpc_full_name        = var.peer_vpc_full_name
-*   # peer_vpc_environment      = var.peer_vpc_environment
 *   # peer_tags = {}
-*   peer_route_table_ids      = [ "rtb-87654321" ]
-*   peer_network_acl_ids      = [ "nacl-87654321" ]
+*   # peer_route_table_ids      = [ "rtb-87654321" ]
+*   # peer_network_acl_ids      = [ "nacl-87654321" ]
 *   peer_rule_number          = 2500
-*   peer_rule_increment       = 1
-*
-*   providers = {
-*     aws.self = aws
-*     aws.peer = aws.us-gov-east-1
-*   }
+*   # peer_rule_increment       = 1
 * }
 * ```
 */