AWS prescriptive-guidance documentation change
Summary
Added CodeCommit deprecation notice, fixed formatting/typos, clarified instructions for local Terraform execution with AFT, and corrected documentation markup
Security assessment
Changes include a service availability notice and documentation improvements. While there's a recommendation to .gitignore sensitive config files, this is a pre-existing security best practice reinforcement rather than addressing a new vulnerability or adding new security features.
Diff
diff --git a/prescriptive-guidance/latest/patterns/validate-account-factory-for-terraform-aft-code-locally.md b/prescriptive-guidance/latest/patterns/validate-account-factory-for-terraform-aft-code-locally.md index a1c8aa5b0..dd1a9a621 100644 --- a/prescriptive-guidance/latest/patterns/validate-account-factory-for-terraform-aft-code-locally.md +++ b/prescriptive-guidance/latest/patterns/validate-account-factory-for-terraform-aft-code-locally.md @@ -12,0 +13,2 @@ SummaryPrerequisites and limitationsArchitectureToolsEpics +**Notice** : AWS CodeCommit is no longer available to new customers. Existing customers of AWS CodeCommit can continue to use the service as normal. [Learn more](https://aws.amazon.com/blogs/devops/how-to-migrate-your-aws-codecommit-repository-to-another-git-provider/) + @@ -36 +38 @@ This procedure can also be used to run Terraform commands that aren’t part of - * [AWS CLI credential helper for Code Commit](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-https-unixes.html), installed and configured + * [AWS CLI credential helper for AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-https-unixes.html), installed and configured @@ -42 +44 @@ This procedure can also be used to run Terraform commands that aren’t part of - * git-remote-commit utility, [installed and configured](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-git-remote-codecommit.html#setting-up-git-remote-codecommit-install) + * `git-remote-commit` utility, [installed and configured](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-git-remote-codecommit.html#setting-up-git-remote-codecommit-install) @@ -77 +79 @@ This pattern shows how to locally invoke Terraform code for AFT global account c -You can also use a similar process to run AFT account customizations in a local terminal. To locally invoke Terraform code from AFT account customizations, clone the **aft-account-customizations repository** instead of **aft-global-account-customizations** repository from CodeCommit in your AFT management account. +You can also use a similar process to run AFT account customizations in a local terminal. To locally invoke Terraform code from AFT account customizations, clone the **aft-account-customizations** repository instead of **aft-global-account-customizations** repository from CodeCommit in your AFT management account. @@ -101 +103 @@ You can also use a similar process to run AFT account customizations in a local -The following is an example bash script that can be used to locally run Terraform code that’s managed by AFT. To use the script, follow the instructions in the _Epics_ section of this pattern. +The following is an example bash script that can be used to locally run Terraform code that’s managed by AFT. To use the script, follow the instructions in the Epics section of this pattern. @@ -106 +108 @@ The following is an example bash script that can be used to locally run Terrafor - # 1.0 2022-02-02 Initial Version + # 1.0 2022-02-02 Initial Version @@ -109,2 +111,2 @@ The following is an example bash script that can be used to locally run Terrafor - # * Facilitates testing of what the AFT pipline will do - # * Provides the ability to run terraform with custom arguments (like 'plan' or 'move') which are currently not supported within the pipeline. + # * Facilitates testing of what the AFT pipline will do + # * Provides the ability to run terraform with custom arguments (like 'plan' or 'move') which are currently not supported within the pipeline. @@ -120,5 +122,5 @@ The following is an example bash script that can be used to locally run Terrafor - # 1. local copy of ct GIT repositories - # 2. local backend.tf and aft-providers.tf filled with data for the target account on which terraform is to be run - # Hint: The contents of above files can be obtain from the logs of a previous execution of the AFT pipeline for the target account. - # 3. 'terraform' binary is available in local PATH - # 4. Recommended: .gitignore file containing 'backend.tf', 'aft_providers.tf' so the local copy of these files are not pushed back to git + # 1. local copy of ct GIT repositories + # 2. local backend.tf and aft-providers.tf filled with data for the target account on which terraform is to be run + # Hint: The contents of above files can be obtain from the logs of a previous execution of the AFT pipeline for the target account. + # 3. 'terraform' binary is available in local PATH + # 4. Recommended: .gitignore file containing 'backend.tf', 'aft_providers.tf' so the local copy of these files are not pushed back to git @@ -127,3 +129,3 @@ The following is an example bash script that can be used to locally run Terrafor - --role-arn arn:aws:iam::$(aws sts get-caller-identity --query "Account" --output text ):role/AWSAFTAdmin \ - --role-session-name AWSAFT-Session \ - --query Credentials ) + --role-arn arn:aws:iam::$(aws sts get-caller-identity --query "Account" --output text ):role/AWSAFTAdmin \ + --role-session-name AWSAFT-Session \ + --query Credentials ) @@ -144 +146 @@ Save the example code as a local file.| - 2. Name the file `ct_terraform.sh`. Then, save the file locally inside a dedicated folder, such as `~/scripts` or `~/bin`. + 2. Name the file `ct_terraform.sh`, and then save the file locally inside a dedicated folder, such as `~/scripts` or `~/bin`. @@ -167 +166 @@ Verify access to AFT management account in the correct AWS Region.| -Make sure that you use the same terminal session that you authenticated into your AFT management account with. +Make sure that you use the same terminal session with which you authenticated into your AFT management account. @@ -173,2 +172,2 @@ Make sure that you use the same terminal session that you authenticated into you - 2. Make sure that you’re in the correct account by doing the following: - * Run the following command: + 2. Make sure that you’re in the correct account. + 1. Run the following command: @@ -178 +177 @@ Make sure that you use the same terminal session that you authenticated into you - * Then, verify that the repositories listed in the output match the names of the repositories that are in your AFT management account. + 2. Verify that the repositories listed in the output match the names of the repositories that are in your AFT management account. @@ -196,2 +195,2 @@ Clone the remote AFT repository code.| -For simplicity, this procedure and AFT use a main code branch only. To use code branching, you can enter code branching commands here as well. However, any applied changes from the non-main branch will be rolled back when AFT automation applies code from the main branch. - 2. Then, navigate into the cloned directory by running the following command: +**** For simplicity, this procedure and AFT use a main code branch only. To use code branching, you can enter code branching commands here as well. However, any applied changes from the non-main branch will be rolled back when AFT automation applies code from the main branch. + 2. Navigate into the cloned directory: @@ -210 +209 @@ Open a previously run AFT pipeline and copy the Terraform configuration files to -The **backend.tf** and **aft-providers.tf** configuration files that are created in this epic are needed for the AFT pipeline to run locally. These files are created automatically within the cloud-based AFT pipeline, but must be created manually for the pipeline to run locally. Running the AFT pipeline locally requires one set of files that represents running the pipeline within a single AWS account. +The `backend.tf` and `aft-providers.tf` configuration files that are created in this epic are needed for the AFT pipeline to run locally. These files are created automatically within the cloud-based AFT pipeline, but must be created manually for the pipeline to run locally. Running the AFT pipeline locally requires one set of files that represent running the pipeline within a single AWS account. @@ -212 +211 @@ The **backend.tf** and **aft-providers.tf** configuration files that are created - 1. Using your AWS Control Tower management account credentials, sign in to the AWS Management Console. Then open the [AWS CodePipeline console](https://console.aws.amazon.com/codesuite/codepipeline/home). Make sure that you’re in the same AWS Region where you deployed AFT. + 1. Using your AWS Control Tower management account credentials, sign in to the AWS Management Console, and open the [AWS CodePipeline console](https://console.aws.amazon.com/codesuite/codepipeline/home). Make sure that you’re in the same AWS Region where you deployed AFT. @@ -214 +213 @@ The **backend.tf** and **aft-providers.tf** configuration files that are created - 3. Choose **###########-customizations-pipeline**. (The **############** is the AWS account ID that you’re using to run Terraform code locally). + 3. Choose **###########-customizations-pipeline**. (The **############** is the AWS account ID that you’re using to run Terraform code locally.) @@ -220 +219,6 @@ The **backend.tf** and **aft-providers.tf** configuration files that are created - 9. In the runtime log, look for the section that begins and ends with the following lines:**“\n\n aft-providers.tf … “\n \n backend.tf”** + 9. In the runtime log, look for the section that begins and ends with the following lines: + + "\n\n aft-providers.tf + ... + "\n \n backend.tf" + @@ -237 +241,6 @@ The **backend.tf** and **aft-providers.tf** configuration files that are created - 11. In the runtime log, look for the section that begins and ends with the following lines:**“\n\n tf … “\n \n backup.tf”** + 11. In the runtime log, look for the section that begins and ends with the following lines: + + "\n\n tf + ... + "\n \n backend.tf" + @@ -240 +249 @@ The **backend.tf** and **aft-providers.tf** configuration files that are created -**Example autogenerated backend.tf statement** +**Example auto-generated backend.tf statement** @@ -253 +261,0 @@ The **backend.tf** and **aft-providers.tf** configuration files that are created - kms_key_id = "cbdc21d6-e04d-4c37-854f-51e199cfcb7c" @@ -261 +269 @@ The **backend.tf** and **aft-providers.tf** configuration files that are created -The `backend.tf` and `aft-providers.tf` files are tied to a specific AWS account, AFT deployment, and folder. These files are also different, depending on if they’re in the **aft-global-customizations** repository and **aft-account-customizations** repository within the same AFT deployment. Make sure that you generate both files from the same runtime listing.| AWS administrator +**** The `backend.tf` and `aft-providers.tf` files are tied to a specific AWS account, AFT deployment, and folder. These files are also different, depending on whether they’re in the **aft-global-customizations** and **aft-account-customizations** repository within the same AFT deployment. Make sure that you generate both files from the same runtime listing.| AWS administrator @@ -277 +285 @@ The files `backend.tf`**** and `aft-providers.tf`**** are in this directory. The -Run the ct_terraform.sh script and review the output.| +Run the `ct_terraform.sh` script and review the output.| @@ -288,2 +296,2 @@ Run the ct_terraform.sh script and review the output.| -you can run any Terraform command during this step. To see a complete list of Terraform commands, run the following command: - 3. Review the command output. Then, debug the code changes locally before committing and pushing the changes back to the AFT repository. +You can run any Terraform command during this step. To see a complete list of Terraform commands, run the following command: + 3. Review the command output, and then debug the code changes locally before committing and pushing the changes back to the AFT repository. @@ -295 +303,3 @@ you can run any Terraform command during this step. To see a complete list of Te - * Any changes made locally and not pushed back to the remote repository are temporary and may be undone at any time by a running AFT pipeline automation. +**** + + * Any changes made locally and not pushed back to the remote repository are temporary and might be undone at any time by a running AFT pipeline automation. @@ -303 +313 @@ Task| Description| Skills required -Add references to the backend.tf and aft-providers.tf files to a .gitignore file.| Add the `backend.tf`**** and `aft-providers.tf` files that you created to a `.gitignore` file by running the following commands: +Add references to the `backend.tf` and `aft-providers.tf` files to a `.gitignore` file.| Add the `backend.tf`**** and `aft-providers.tf` files that you created to a `.gitignore` file by running the following commands: @@ -318 +328 @@ Commit and push your code changes to the remote AFT repository.| - 2. To commit your changes and push them to the remote AFT repository in AWS CodeCommit, run the following commands: + 2. To commit your changes and push them to the remote AFT repository in CodeCommitt, run the following commands: @@ -332 +342 @@ Task| Description| Skills required -Roll out the changes to all of your accounts managed by AFT.| To roll out the changes to multiple AWS accounts managed by AFT, follow the instructions in [Re-invoke customizations](https://docs.aws.amazon.com/controltower/latest/userguide/aft-account-customization-options.html#aft-re-invoke-customizations) in the AWS Control Tower documentation.| AWS administrator +Roll out the changes to all of your accounts that are managed by AFT.| To roll out the changes to multiple AWS accounts that are managed by AFT, follow the instructions in [Re-invoke customizations](https://docs.aws.amazon.com/controltower/latest/userguide/aft-account-customization-options.html#aft-re-invoke-customizations) in the AWS Control Tower documentation.| AWS administrator