From 8a206269b55ca7671c68795cb96a9c760b47837b Mon Sep 17 00:00:00 2001 From: badra001 Date: Sat, 8 Oct 2022 11:40:16 -0400 Subject: [PATCH] update readme --- tag-shared-vpc-resources/README.md | 109 ++++++++++++++++++++++-- tag-shared-vpc-resources/main.tf | 119 ++++++++++++++++++++++++--- tag-shared-vpc-resources/tf-run.data | 8 -- 3 files changed, 207 insertions(+), 29 deletions(-) delete mode 100644 tag-shared-vpc-resources/tf-run.data diff --git a/tag-shared-vpc-resources/README.md b/tag-shared-vpc-resources/README.md index 6b79260..644b4c8 100644 --- a/tag-shared-vpc-resources/README.md +++ b/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 | diff --git a/tag-shared-vpc-resources/main.tf b/tag-shared-vpc-resources/main.tf index dae0c6d..6a16e29 100644 --- a/tag-shared-vpc-resources/main.tf +++ b/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 { diff --git a/tag-shared-vpc-resources/tf-run.data b/tag-shared-vpc-resources/tf-run.data deleted file mode 100644 index 37405d2..0000000 --- a/tag-shared-vpc-resources/tf-run.data +++ /dev/null @@ -1,8 +0,0 @@ -VERSION 1.0.1 -REMOTE-STATE -COMMAND tf-directory-setup.py -l none -f -COMMAND setup-new-directory.sh -COMMAND tf-init -upgrade -null_resource.network_acl -ALL -COMMAND tf-directory-setup.py -l s3