update readme

tag-shared-vpc-resources/README.md

@@ -1,23 +1,48 @@
 # About aws-vpc-setup ::  tag-shared-vpc-resources
 
-This will tag resources shared to this account.  Currently, you can tag the following shared resources locally, when shared
-through RAM:
+This code reads a list of shared VPC resources, through RAM, available to the account and region, and will use the EC2 tag resouce to
+set tags within this account.
 
-* vpc
-* route-table
-* subnet
-* dhcp-option-set
-* network-acl
+This is necessary because resources shared by RAM do not include tags in the shared accounts.  This is handled per
+account and region.
+
+It is required to have access to the appropriate remote account. Currently, it's the standard profile name ({account\_id}-{account\_alias}),but we will set this
+up to use one's specific account profile with an assume role to get at the target account where the resources are shared.
+
+For VPCs, it is expected that the account shared is the Network Production account, but any account and profile may be used if it shares VPC resources.
+
+This reads tags and updates them in the local account and region from these resources:
+
+* vpcs
+* dhcp-option-sets
+* subnets
+* route-tables
+* network-acls
 
 These resources are not compatible for sharing.  AWS does not support remote (i.e., in a shared to account) tagging:
 
 * transit-gateway
 
+## How it works
+
+We get a list of VPCs, subnets, route tables and network ACLs which are owned by the network source account.
+For each of these, other than network ACLs, we read each item with a `data` resource, and then the tags and owner on the
+the resource in our account and region
+
+For DHCP options sets, it reads the associated `dhcp_option_set` on the shared VPC.  It uses that to obtain the tags
+and set them accordingly.
+
+Network ACLS are different.  There is no data resource to get a specific network ACL. We read the list of network ACLs, but then
+pass that into a `null_resource` to call the `aws` CLI.  This gets a JSON file, which is then parsed and Tag and OwnerID extracted
+to apply tags on the local network ACLs.  There are enhancements issues for this missing resource in the terraform aws provider
+[1](https://github.com/hashicorp/terraform-provider-aws/issues/19754),
+[2](https://github.com/hashicorp/terraform-provider-aws/issues/4260).
+
 # Usage
 
 ```hcl
 module "tag_shared" {
-  source          = "git@github.e.it.census.gov:terraform-modules/aws-vpc-setup.git//tag-shared-vpc-resources?ref=tf-upgrade"
+  source                  = "git@github.e.it.census.gov:terraform-modules/aws-vpc-setup.git//tag-shared-vpc-resources?ref=tf-upgrade"
   network_account_profile = "057445207498-ent-gov-network-sa"
 
   ## optional, with defaults
@@ -30,6 +55,74 @@ module "tag_shared" {
 }
 ```
 
+**NOTE**
+This is a multi-step module, if using the `tag_enabled_network_acls=true` (the default).  This is because there is no Terraform
+resource to get a network ACL (described above).  As such, you must execute a `tf-apply` twice, once to create a file
+indicating the AWS CLI has been run to obtain the data, and the second to tag the local network acls.
+
+## Access Requirements
+
+You need to have these AWS CLI IAM profiles and accounts available:
+
+* AWS Profile for account where VPC resources are shared (primarily the ability to tag resoruces)
+* AWS Profile for account from which VPC resoruces are shared (read access to specific VPC resouces, `ec2:Describe*`)
+
+## Application Requirements
+
+This requires the `aws` CLI v2.
+
+## Input Variables
+
+* network\_account\_profile
+
+Use the appropriate source account where the VPC resource were shared as the `network_account_profile` input variable.
+The Account ID is obtained from that remote account.
+
+## Output Variables
+
+This module does not have any outputs.
+
+# Terraform Directions
+
+Run this once per account and region. This module call belongs in `vpc/{region}/shared-vpc-setup`. This may be re-run when new
+subnets and VPCs are shared to an account, or if tags change in the source account, and they need to be updated in this particular
+account.
+
+```script
+tf-run apply
+```
+
+## tf-run.data
+
+To use this with `tf-run`, you can will need to either use the module name twice, or use the statement `ALL` twice (preferred).
+
+* example with module name twice
+
+```script
+VERSION 1.1.0
+REMOTE-STATE
+COMMAND tf-directory-setup.py -l none -f
+COMMAND setup-new-directory.sh
+COMMAND tf-init -upgrade
+module.tag_shared
+module.tag_shared
+ALL
+COMMAND tf-directory-setup.py -l s3
+```
+
+* example with ALL twice (recommended)
+
+```script
+VERSION 1.1.0
+REMOTE-STATE
+COMMAND tf-directory-setup.py -l none -f
+COMMAND setup-new-directory.sh
+COMMAND tf-init -upgrade
+ALL
+ALL
+COMMAND tf-directory-setup.py -l s3
+```
+
 ## Requirements
 
 | Name | Version |

tag-shared-vpc-resources/main.tf

@@ -1,26 +1,51 @@
 /*
 * # About aws-vpc-setup ::  tag-shared-vpc-resources
 * 
-* This will tag resources shared to this account.  Currently, you can tag the following shared resources locally, when shared
-* through RAM:
-*
-* * vpc
-* * route-table
-* * subnet
-* * dhcp-option-set
-* * network-acl
-*
+* This code reads a list of shared VPC resources, through RAM, available to the account and region, and will use the EC2 tag resouce to
+* set tags within this account.
+* 
+* This is necessary because resources shared by RAM do not include tags in the shared accounts.  This is handled per
+* account and region.
+* 
+* It is required to have access to the appropriate remote account. Currently, it's the standard profile name ({account_id}-{account_alias}),but we will set this
+* up to use one's specific account profile with an assume role to get at the target account where the resources are shared.
+* 
+* For VPCs, it is expected that the account shared is the Network Production account, but any account and profile may be used if it shares VPC resources.
+* 
+* This reads tags and updates them in the local account and region from these resources:
+* 
+* * vpcs
+* * dhcp-option-sets
+* * subnets
+* * route-tables
+* * network-acls
+* 
 * These resources are not compatible for sharing.  AWS does not support remote (i.e., in a shared to account) tagging:
-*
+* 
 * * transit-gateway
-*
+* 
+* ## How it works
+* 
+* We get a list of VPCs, subnets, route tables and network ACLs which are owned by the network source account.
+* For each of these, other than network ACLs, we read each item with a `data` resource, and then the tags and owner on the
+* the resource in our account and region
+* 
+* For DHCP options sets, it reads the associated `dhcp_option_set` on the shared VPC.  It uses that to obtain the tags
+* and set them accordingly.
+* 
+* Network ACLS are different.  There is no data resource to get a specific network ACL. We read the list of network ACLs, but then
+* pass that into a `null_resource` to call the `aws` CLI.  This gets a JSON file, which is then parsed and Tag and OwnerID extracted
+* to apply tags on the local network ACLs.  There are enhancements issues for this missing resource in the terraform aws provider
+* [1](https://github.com/hashicorp/terraform-provider-aws/issues/19754),
+* [2](https://github.com/hashicorp/terraform-provider-aws/issues/4260).
+* 
 * # Usage
 * 
 * ```hcl
 * module "tag_shared" {
-*   source          = "git@github.e.it.census.gov:terraform-modules/aws-vpc-setup.git//tag-shared-vpc-resources?ref=tf-upgrade"
+*   source                  = "git@github.e.it.census.gov:terraform-modules/aws-vpc-setup.git//tag-shared-vpc-resources?ref=tf-upgrade"
 *   network_account_profile = "057445207498-ent-gov-network-sa"
-*
+* 
 *   ## optional, with defaults
 *   ###  tag_enabled_vpcs = true
 *   ###  tag_enabled_dhcp_options = true
@@ -30,6 +55,74 @@
 *   ###  tag_enabled_transit_gateway = false
 * }
 * ```
+* 
+* **NOTE**
+* This is a multi-step module, if using the `tag_enabled_network_acls=true` (the default).  This is because there is no Terraform
+* resource to get a network ACL (described above).  As such, you must execute a `tf-apply` twice, once to create a file
+* indicating the AWS CLI has been run to obtain the data, and the second to tag the local network acls.
+* 
+* ## Access Requirements
+* 
+* You need to have these AWS CLI IAM profiles and accounts available:
+* 
+* * AWS Profile for account where VPC resources are shared (primarily the ability to tag resoruces)
+* * AWS Profile for account from which VPC resoruces are shared (read access to specific VPC resouces, `ec2:Describe*`)
+* 
+* ## Application Requirements
+* 
+* This requires the `aws` CLI v2.
+* 
+* ## Input Variables
+* 
+* * network_account_profile
+* 
+* Use the appropriate source account where the VPC resource were shared as the `network_account_profile` input variable.
+* The Account ID is obtained from that remote account.
+* 
+* ## Output Variables
+* 
+* This module does not have any outputs.
+* 
+* # Terraform Directions
+* 
+* Run this once per account and region. This module call belongs in `vpc/{region}/shared-vpc-setup`. This may be re-run when new
+* subnets and VPCs are shared to an account, or if tags change in the source account, and they need to be updated in this particular
+* account.
+* 
+* ```script
+* tf-run apply
+* ```
+* 
+* ## tf-run.data 
+* 
+* To use this with `tf-run`, you can will need to either use the module name twice, or use the statement `ALL` twice (preferred).
+* 
+* * example with module name twice
+* 
+* ```script
+* VERSION 1.1.0
+* REMOTE-STATE
+* COMMAND tf-directory-setup.py -l none -f
+* COMMAND setup-new-directory.sh
+* COMMAND tf-init -upgrade
+* module.tag_shared
+* module.tag_shared
+* ALL
+* COMMAND tf-directory-setup.py -l s3
+* ```
+* 
+* * example with ALL twice (recommended)
+* 
+* ```script
+* VERSION 1.1.0
+* REMOTE-STATE
+* COMMAND tf-directory-setup.py -l none -f
+* COMMAND setup-new-directory.sh
+* COMMAND tf-init -upgrade
+* ALL
+* ALL
+* COMMAND tf-directory-setup.py -l s3
+* ```
 */
 
 locals {