ADF terraform extension (#397)

* added .gitignore * added adf terraform role to global.yml * Added DynamoDB permission to adf-codebuild-policy in deployment/global.yml * added adf-terraform-role to Organization Policy adf-build/global.yml * added organizations:ListChildren to OrganizationsReadOnlyPolicy * added DynamoDB table for terraform lock to adf-bootstrap/deployment/global.yml and regional.yml * added DynamoDB table for terraform lock to adf-bootstrap/deployment/global.yml * added sample-terraform repository * Added tfvars examples * clean comments * pull request template * Define PULL REQUEST * clean PULL_REQUEST_TEMPLATE.md * Update samples/sample-terraform/README.md Co-authored-by: Stewart Wallace * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Stewart Wallace * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py clean comments Co-authored-by: Stewart Wallace * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Stewart Wallace * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py clean comments Co-authored-by: Stewart Wallace * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Stewart Wallace * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Stewart Wallace * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py remove comments Co-authored-by: Stewart Wallace * removed .gitignore from sample-terraform * Update samples/sample-terraform/README.md add details to documenation Co-authored-by: Simon <[email protected]> * renamed tf_sec to tf_scan in sample-terraform * added more details to README.md regarding REGIONS parameters * removed restart_execution_on_update: true * Update samples/sample-terraform/README.md Rename parameter from MASTER_ACCOUNT_ID to MANAGEMENT_ACCOUNT_ID Co-authored-by: Simon <[email protected]> * Update samples/sample-terraform/README.md Co-authored-by: Simon <[email protected]> * Update samples/sample-terraform/README.md Co-authored-by: Simon <[email protected]> * Update samples/sample-terraform/README.md Co-authored-by: Simon <[email protected]> * added latest terraform version in sample-terraform example * added terraform version support in documetation * fixed README.md format * added tf pipeline documentation in user guide * added s3 public access block to terraform sample * removed TF_STAGE as adf_terraform.sh input parameter * removed AWS_DEFAULT_REGION from tf_apply and tf_plan * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/adf_terraform.sh Co-authored-by: Simon <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon <[email protected]> * revert to original PULL_REQUEST_TEMPLATE.md * clean .gitignore * add logging module * added main * undo linter changes * removed artifact from tf_apply * added ondemand capacity to DynamoDB table * removed terraform role. This could be added in global-iam by the user * added an example of terraform role. It must be uncommented by the user to enable tf extension * added tf pre-requisites to user-guide * global vars to upper case * added tfrun function to avoid code repetition and add functionality to copy tf plan to S3 bucket in the deployment account * clean documentation * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update samples/sample-terraform/tf/s3.tf Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-bootstrap/example-global-iam.yml Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/adf_terraform.sh Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/adf_terraform.sh Co-authored-by: Simon Kok <[email protected]> * removed extra ] * changed session name * move TERRAFORM_VERSION variable to buildspec.yml * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon Kok <[email protected]> * renamed environment variables * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/get_accounts.py Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/adf_terraform.sh Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/adf_terraform.sh Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/adf_terraform.sh Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/adf_terraform.sh Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * fixed toc identation * added details to terraform sections * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update samples/sample-terraform/README.md Co-authored-by: Simon Kok <[email protected]> * Update samples/sample-terraform/README.md Co-authored-by: Simon Kok <[email protected]> * renamed terraform to upper case and align content of README.md file in sample-terraform * Update samples/sample-terraform/README.md Co-authored-by: Simon Kok <[email protected]> * Update samples/sample-terraform/buildspec.yml Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/adf_terraform.sh Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/adf_terraform.sh Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/adf_terraform.sh Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/adf_terraform.sh Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/adf_terraform.sh Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/adf_terraform.sh Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/helpers/terraform/adf_terraform.sh Co-authored-by: Simon Kok <[email protected]> * removed Terraform IAM role and policy * added support to partitions * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update samples/sample-terraform/README.md Co-authored-by: Simon Kok <[email protected]> * Update samples/sample-terraform/README.md Co-authored-by: Simon Kok <[email protected]> * Update src/lambda_codebase/initial_commit/bootstrap_repository/adf-bootstrap/deployment/example-global-iam.yml Co-authored-by: Simon Kok <[email protected]> * removed TerraformLockTable resource as already defined in regional.yml * Update docs/user-guide.md Co-authored-by: Simon Kok <[email protected]> * Update docs/user-guide.md * Update docs/user-guide.md * Update samples/sample-terraform/README.md * Update samples/sample-terraform/README.md * added newline character * added newline character * added newline character * added docstring * read CROSS_ACCOUNT_ACCESS_ROLE from parameter store * replaced sample adf terraform policy example * replaced sample adf terraform policy example * added details to adf terraform role description * removed trailing spaces * added aws partition variable * added init stage only as option * import extensions parameter in SSM Parameter Store of Management account * import extensions parameter in SSM Parameter Store of Deployment account (all regions) * added condition on DynamoDB table. Deploy only if Tf extension is enabled * added example in adfconfig related to Tf extension * added details related to terraform extension * added details related to terraform extension * fixed indentation * renamed paginator variable * Resolve W1514 - use open with encoding * Fix user guide target via tags * changed default codebuild image to STANDARD_5_0 * Fix YAML lint issues * Fix CFN lint issues * Fix MegaLint issues * Adding in default values for extensions * Remove redundant paginator This is already available at: src/lambda_codebase/initial_commit/bootstrap_repository/adf-build/shared/python/paginator.py * Fix TF doc comments and links * Fix TF line length findings * Revert default CodeBuild container, would introduce a breaking change The default CodeBuild container image to use cannot be changed without introducing a breaking change. A breaking change would imply a major version release. Since we are adding TF support in v3.2.0, a minor version release, we cannot modify this yet. It is on the roadmap though for the next major release :). * Replace redundant code writing extension parameters Co-authored-by: Stefano Montanelli Co-authored-by: Stewart Wallace Co-authored-by: Simon Kok
awslabs · Dec 6, 2022 · 2dd7d95 · 2dd7d95
1 parent beb649d
commit 2dd7d95
Show file tree

Hide file tree

Showing 29 changed files with 886 additions and 146 deletions.
diff --git a/.gitignore b/.gitignore
@@ -139,3 +139,15 @@ dmypy.json
 .pyre/
 
 megalinter-reports/
+
+### Terraform ###
+# Local .terraform directories
+**/.terraform/*
+
+# .tfstate files
+*.tfstate
+*.tfstate.*
+
+# Ignore CLI configuration files
+.terraformrc
+terraform.rc
diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -26,6 +26,11 @@
     - [Deploying Serverless Applications with SAM](#deploying-serverless-applications-with-sam)
     - [Using YAML Anchors and Aliases](#using-yaml-anchors-and-aliases)
     - [One to many relationships](#one-to-many-relationships)
+  - [Terraform pipeline](#terraform-pipeline)
+    - [Prerequisites](#prerequisites)
+    - [Overview](#overview)
+    - [Parameters](#parameters)
+    - [Deployment procedure](#deployment-procedure)
 
 ## Deployment Map
 
@@ -72,7 +77,7 @@ pipelines:
     params:
       notification_endpoint: [email protected]  # Optional
     tags:
-      foo: bar # Pipelines support tagging
+      foo: bar  # Pipelines support tagging
     targets:
       - path: /security
         regions: eu-west-1
@@ -100,7 +105,7 @@ pipelines:
       notification_endpoint: [email protected]
     targets:
       - path: /banking/testing
-        name: fancy-name #Optional way to pass a name for this stage in the pipeline
+        name: fancy-name  # Optional way to pass a name for this stage in the pipeline
 ```
 
 In the above example we are creating two pipelines with AWS CodePipeline. The
@@ -246,7 +251,7 @@ targets:
 targets:
   - target: 9999999999 # Target and Path keys can be used interchangeably
     regions: eu-west-1
-    name: my-special-account # Defaults to adf-cloudformation-deployment-role
+    name: my-special-account  # Defaults to adf-cloudformation-deployment-role
     # If you intend to override the provider for this stage
     # (see providers guide for available providers)
     provider: some_provider
@@ -359,7 +364,7 @@ pipelines:
     triggers:
       on_complete:
         pipelines:
-          - my-web-app-pipeline # Start this pipeline
+          - my-web-app-pipeline  # Start this pipeline
 
   - name: my-web-app-pipeline
     default_providers:
@@ -390,7 +395,7 @@ pipelines:
     # and what should be triggered when it completes
     completion_triggers:
       pipelines:
-        - my-web-app-pipeline # Start this pipeline
+        - my-web-app-pipeline  # Start this pipeline
 
   - name: my-web-app-pipeline
     # Same configuration as defined above.
@@ -540,7 +545,7 @@ pipelines:
         provider: codebuild
         image:
           repository_arn: arn:aws:ecr:region:111111111111:repository/test
-          tag: latest # optional (defaults to latest)
+          tag: latest  # optional (defaults to latest)
     targets:
       - # ...
 ```
@@ -907,7 +912,7 @@ main `template.yml` in our like so:
   MyStack:
     Type: "AWS::CloudFormation::Stack"
     Properties:
-      TemplateURL: another_template.yml # file path to the nested stack template
+      TemplateURL: another_template.yml  # file path to the nested stack template
 ```
 
 When the `package_transform.sh` command is executed, the file will be packaged
@@ -1028,3 +1033,161 @@ By passing in the Repository name *(repository)* we are overriding the
 **name** property which normally is the name of our associated repository.
 This will tie both of these pipelines to the single *sample-vpc* repository on
 the `111111111111` AWS Account.
+
+### Terraform pipeline
+
+#### Prerequisites
+
+To enable ADF Terraform extension the following steps are required:
+
+- Enable ADF Terraform extension. Set the parameter
+  `extensions > terraform > enabled` to `True` in the `adfconfig.yml` file,
+  as shown in the `example-adfconfig.yml`, to deploy all the necessary
+  resources.
+- Rename file `example-global-iam.yml` to `global-iam.yml` in the following
+  path `aws-deployment-framework-bootstrap/adf-bootstrap/` and ensure the
+  CloudFormation resources `ADFTerraformRole` and `ADFTerraformPolicy` are
+  no longer commented out.
+- Rename file `example-global-iam.yml` to `global-iam.yml` in the following
+  path `aws-deployment-framework-bootstrap/adf-bootstrap/deployment`
+  **Please note:** the use of `deployment` at the end)
+  and ensure the CloudFormation resources `ADFTerraformRole` and
+  `ADFTerraformPolicy` are no longer commented out.
+
+**Important note**: `ADFTerraformPolicy` IAM policy is a sample.
+This policies should **NOT** be used for purposes other than testing.
+You should scope this policy depending on what you would like to deploy
+using Terraform within the selected Organizational Units.
+
+#### Overview
+
+ADF support the deployment of Terraform code to multiple accounts and
+regions through Terraform pipelines. The module consists of four build
+stages defined in the following CodeBuild build specification:
+
+- `buildspec.yml`: install the version of Terraform specified in the
+  pipeline configuration.
+- `tf_scan.yml`: (optional) scans for vulnerabilities in the Terraform
+  code using the [Terrascan](https://github.com/accurics/terrascan)
+  application. If vulnerabilities are found, it will fail and block
+  further execution in the pipeline. It is recommended to enable this
+  step in all ADF Terraform pipelines.
+- `tf_plan.yml`: get the list of accounts from the organization and
+  run a Terraform plan.
+- `tf_apply.yml`: get the list of accounts from the organization and
+  run a Terraform plan and apply.
+
+An optional approval step could be added between plan and apply as
+shown in the pipeline definition below.
+
+Please look into the [sample-terraform](../samples/sample-terraform)
+pipeline for more details in the setup and integration.
+
+#### Parameters
+
+- `TERRAFORM_VERSION`: the Terraform version used to deploy the
+  resource. This parameter must be defined in the `buildspec.yml`
+  file of the repository.
+- `TARGET_ACCOUNTS`: comma separated list of target accounts.
+- `TARGET_OUS`: comma separated list of target leaf OUs (parent
+  OUs are supported).
+- `REGIONS`: comma separated list of target regions. If this parameter
+  is empty, the main ADF region is used.
+- `MANAGEMENT_ACCOUNT_ID`: id of the AWS Organizations management account.
+
+#### Deployment procedure
+
+Example Terraform deployment map:
+
+```yaml
+- name: sample-terraform
+  default_providers:
+    source:
+      provider: codecommit
+      properties:
+        account_id: 111111111111  # Source account id
+    build:
+      provider: codebuild
+    deploy:
+      provider: codebuild
+      properties:
+        image: "STANDARD_5_0"
+        environment_variables:
+          TARGET_ACCOUNTS: 111111111111,222222222222  # Target accounts
+          TARGET_OUS: /core/infrastructure,/sandbox  # Target OUs
+          MANAGEMENT_ACCOUNT_ID: 333333333333  # Billing account
+          # Target regions, as a comma separated list is supported
+          # For example, "eu-west-1,us-east-1".
+          REGIONS: eu-west-1
+  targets:
+    - name: terraform-scan  # optional
+      properties:
+        spec_filename: tf_scan.yml  # Terraform scan
+    - name: terraform-plan
+      properties:
+        spec_filename: tf_plan.yml  # Terraform plan
+    - approval  # manual approval
+    - name: terraform-apply
+      properties:
+        spec_filename: tf_apply.yml  # Terraform apply
+```
+
+1. Add a sample-terraform pipeline in ADF `deployment-map.yml` as shown above.
+2. Add the project name in `params/global.yml` file.
+3. Add Terraform code to the `tf` folder. **Please note**: Do not make changes
+   to `backend.tf` file and `main.tf` in the root folder of the sample.
+   These contain the definition of the remote state file location and the
+   Terraform provider definition. Any change to these files could disrupt
+   the standard functionalities of this module.
+4. Add variable definition to `tf/variables.tf` file and variable values to
+   `tfvars/global.auto.tfvars`.
+
+   - Local variables (per account) can be configured using the following
+     naming convention
+
+     ```txt
+     tfvars <-- This folder contains the structure to define Terraform
+     │          variables
+     │
+     └───global.auto.tfvars <-- this file contains global variables applied to
+     │                          all the target accounts
+     │
+     └───111111111111 <-- this folders contains variable files related to
+     │   │                the account
+     │   └──────│   local.auto.tfvars <-- this file contains variables related
+     │          │                         to the account
+     │
+     └───222222222222
+         └──────│   local.auto.tfvars
+     ```
+
+5. Define the desired `TERRAFORM_VERSION` in the `buildspec.yml` file as shown
+   in the sample-terraform example. ADF supports Terraform version v0.13.0 and
+   later.
+6. Push to your Terraform ADF repository, for example the sample-terraform one.
+7. Pipeline contains a manual approval step between Terraform plan and
+   Terraform apply. Confirm to proceed.
+
+Terraform state files are stored in the regional S3 buckets in the deployment
+account. One state file per account/region/module is created.
+
+e.g.
+
+- Project name: sample-tf-module
+- Target accounts: 111111111111, 222222222222
+- Target regions: eu-west-1 (main ADF region), us-east-1
+
+The following state files are created:
+
+- 111111111111 main region (eu-west-1)
+  -> adf-global-base-deployment-pipelinebucketxyz/sample-tf-module/111111111111.tfstate
+- 111111111111 secondary region (us-east-1)
+  -> adf-regional-base-deploy-deploymentframeworkregio-jsm/sample-tf-module/111111111111.tfstate
+- 222222222222 main region (eu-west-1)
+  -> adf-global-base-deployment-pipelinebucketxyz/sample-tf-module/222222222222.tfstate
+- 222222222222 secondary region (us-east-1)
+  -> adf-regional-base-deploy-deploymentframeworkregio-jsm/sample-tf-module/222222222222.tfstate
+
+A DynamoDB table is created to manage the lock of the state file. It is
+deployed in every ADF regions named `adf_locktable`. **Please note**: usage
+of this locking table is charged on the deployment account.
diff --git a/samples/sample-terraform/README.md b/samples/sample-terraform/README.md
@@ -1,19 +1,50 @@
-# Sample Terraform
+# Terraform template
 
-## Deployment Map example
+## Overview
+
+Please read the [user guide on ADF's support for
+Terraform](../../docs/user-guide.md#terraform-pipeline) before you proceed.
+
+## Deployment procedure
+
+1. Add a sample-terraform pipeline in ADF `deployment-map.yml` as in the
+example:
 
 ```yaml
-  - name: my-terraform-example
-    default_providers:
-      source:
-        provider: codecommit
-        properties:
-          account_id: 1111111111111
-      deploy:
-        provider: codebuild
-        properties:
-          image: "STANDARD_5_0"
-    targets:
-      - properties:
-          spec_filename: my_test_spec.yml
+- name: sample-terraform
+  default_providers:
+    source:
+      provider: codecommit
+      properties:
+        account_id: 111111111111  # Source account id
+    build:
+      provider: codebuild
+    deploy:
+      provider: codebuild
+      properties:
+        image: "STANDARD_5_0"
+        environment_variables:
+          TARGET_ACCOUNTS: 111111111111,222222222222  # Target accounts
+          TARGET_OUS: /core/infrastructure,/sandbox  # Target OUs
+          MANAGEMENT_ACCOUNT_ID: 333333333333  # Billing account
+          # Regions in comma-separated list format, for example
+          # "eu-west-1,us-east-1"
+          REGIONS: eu-west-1
+  targets:
+    - name: terraform-scan  # optional
+      properties:
+        spec_filename: tf_scan.yml  # Terraform scan
+    - name: terraform-plan
+      properties:
+        spec_filename: tf_plan.yml  # Terraform plan
+    - approval  # manual approval
+    - name: terraform-apply
+      properties:
+        spec_filename: tf_apply.yml  # Terraform apply
 ```
+
+The sample uses the following configuration, please update accordingly:
+
+- Project name: `sample-tf-module`
+- Target accounts: `111111111111` and `222222222222`
+- Target regions: `eu-west-1` (the main ADF deployment region) and `us-east-1`
diff --git a/samples/sample-terraform/buildspec.yml b/samples/sample-terraform/buildspec.yml
@@ -1,10 +1,19 @@
 version: 0.2
 
+env:
+  variables:
+    # Terraform version to use. ADF supports Terraform version v0.13.0 and later.
+    TERRAFORM_VERSION: "1.0.10"
 phases:
   install:
     commands:
+      - aws s3 cp s3://$S3_BUCKET_NAME/adf-build/ adf-build/ --recursive --quiet
       - export PATH=$PATH:$(pwd)
-      - bash scripts/terraform/install_terraform.sh
+      - bash adf-build/helpers/terraform/install_terraform.sh
+      - pip install -r adf-build/requirements.txt -q
+  build:
+    commands:
+      - python adf-build/generate_params.py
 
 artifacts:
-  files: '**/*'
+  files: "**/*"
diff --git a/samples/sample-terraform/main.tf b/samples/sample-terraform/main.tf
diff --git a/samples/sample-terraform/my_test_spec.yml b/samples/sample-terraform/my_test_spec.yml
diff --git a/samples/sample-terraform/params/global.yml b/samples/sample-terraform/params/global.yml
@@ -0,0 +1,2 @@
+Parameters:
+  ProjectName: "sample-terraform"