Terraform Infrastructure

Terraform is an open-source infrastructure as code software tool that enables you to safely and predictably create, change, and improve infrastructure.

The Terraform infrastructure generator creates a Terraform infrastructure project. The generated application includes security best practices through Checkov security checks.

Usage

Generate a Terraform Project

You can generate a new Terraform project in two ways:

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - terraform#project
5. Fill in the required parameters
   • name: tf-infra
6. Click Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=tf-infra

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=tf-infra

npm

npx nx g @aws/nx-plugin:terraform#project --name=tf-infra

bun

bunx nx g @aws/nx-plugin:terraform#project --name=tf-infra

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

npm

npx nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

bun

bunx nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

Options

Parameter	Type	Default	Description
name Required	string	-	The name of the project.
type	string	application	Whether this is a terraform lib (re-usable modules) or app (deployable).
directory	string	packages	The directory of the new project.

Generator Output

The generator creates different file structures depending on the project type:

Application Type

For application projects (--type=application), the generator creates a complete Terraform application with remote state management:

• Directorysrc

  • main.tf Main Terraform configuration file
  • providers.tf Provider configuration with S3 backend
  • variables.tf Input variable definitions
  • outputs.tf Output value definitions
  • Directoryenv Environment-specific variable files

    • dev.tfvars Development environment variables
• Directorybootstrap Bootstrap configuration for remote state

  • main.tf S3 bucket and policies for state storage
  • providers.tf AWS provider configuration
  • variables.tf Bootstrap variable definitions
• project.json Project configuration and build targets

Note

The generator also creates a packages/common/terraform library which initially just adds a metrics module (creates an empty Cloudformation stack with metadata) that is automatically instrumented so that the nx-plugin-for-aws team can track usage metrics.

Library Type

For library projects (--type=library), the generator creates a simpler structure for reusable Terraform modules:

• Directorysrc

  • main.tf Main Terraform module file
• project.json Project configuration and build targets

Tip

Application projects include full deployment capabilities with remote state management, while library projects are designed for creating reusable Terraform modules that can be consumed by other projects.

Implementing your Terraform Infrastructure

You can start writing your Terraform infrastructure inside src/main.tf, for example:

src/main.tf

locals {
  account_id = data.aws_caller_identity.current.account_id
  aws_region = data.aws_region.current.id
}

resource "null_resource" "print_info" {
  # triggers = {
  #   always_run = timestamp()
  # }

  provisioner "local-exec" {
    command = "echo 'AWS Region: ${local.aws_region}, AWS Account: ${local.account_id}, Environment: ${var.environment}'"
  }
}

# Declare your infrastructure here
resource "aws_s3_bucket" "my_bucket" {
  bucket = "my-unique-bucket-name"
}

Cross project dependencies

If you wanted to execute a module from a seperate project (lib), you could do so as follows:

module "lib_module" {
  source = "../../path/to/my-lib/src"
}

This will automatically update the Nx graph to add a dependency between your consuming application and your lib.

Environment Configuration

Configure environment-specific variables in the src/env/*.tfvars files.

To add new environments, create a new src/env/<environment>.tfvars file with the environment-specific variables and add new entries for apply, destroy, init, plan in the project.json for the new env configuration. For example, let’s assume we want to add a prod env:

src/env/prod.tfvars

# Production environment variables
environment = "prod"
region      = "us-west-2"

project.json

{
  "targets": {
        "apply": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "command": "terraform apply ../../../dist/packages/infra/terraform/dev.tfplan"
                },
                "prod": {
                    "command": "terraform apply ../../../dist/packages/infra/terraform/prod.tfplan"
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd": "{projectRoot}/src"
            },
            "dependsOn": ["plan"]
        },
        "destroy": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "command": "terraform destroy -var-file=env/dev.tfvars"
                },
                "prod": {
                    "command": "terraform destroy -var-file=env/prod.tfvars"
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd":"{projectRoot}/src"
            },
            "dependsOn": ["init"]
        },
        "init": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "command": "terraform init -reconfigure -backend-config=\"region=$(aws configure get region)\" -backend-config=\"bucket=$(aws sts get-caller-identity --query Account --output text)-tf-state-$(aws configure get region)\" -backend-config=\"key=dev/terraform.tfstate\""
                },
                "prod": {
                    "command": "terraform init -reconfigure -backend-config=\"region=$(aws configure get region)\" -backend-config=\"bucket=$(aws sts get-caller-identity --query Account --output text)-tf-state-$(aws configure get region)\" -backend-config=\"key=prod/terraform.tfstate\""
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd": "{projectRoot}/src"
            }
        },
        "plan": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "command": "terraform plan -var-file=env/dev.tfvars -out=../../../dist/packages/infra/terraform/dev.tfplan"
                },
                "prod": {
                    "command": "terraform plan -var-file=env/dev.tfvars -out=../../../dist/packages/infra/terraform/prod.tfplan"
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd": "{projectRoot}/src"
            },
            "dependsOn": ["init"]
        }
    }
}

Tip

By default, all targets assume dev environment, however you can target a specific environment as follows:

• pnpm
• yarn
• npm
• bun

pnpm nx run tf-infra:apply --configuration=prod

yarn nx run tf-infra:apply --configuration=prod

npx nx run tf-infra:apply --configuration=prod

bunx nx run tf-infra:apply --configuration=prod

You can also swap environment at any time as the state segments the tfstate automatically between environments.

Remote State Bootstrap (Application Projects Only)

For application projects, before deploying your infrastructure, you’ll need to bootstrap the remote state backend. This creates an S3 bucket to store your Terraform state files:

pnpm

pnpm nx run tf-infra:bootstrap

yarn

yarn nx run tf-infra:bootstrap

npm

npx nx run tf-infra:bootstrap

bun

bunx nx run tf-infra:bootstrap

Note

Ensure your AWS CLI profile is configured to the account/region you wish to deploy the bootstrap resources into.

The bootstrap target is only available for application type projects. Library projects don’t require remote state management as they are designed to be reusable modules.

Available Targets

The available targets depend on your project type:

Common Targets (Both Application and Library)

Validating your Infrastructure

You can validate your Terraform configuration using the validate target:

pnpm

pnpm nx run tf-infra:validate

yarn

yarn nx run tf-infra:validate

npm

npx nx run tf-infra:validate

bun

bunx nx run tf-infra:validate

Formatting your Code

Format your Terraform code using the fmt target:

pnpm

pnpm nx run tf-infra:fmt

yarn

yarn nx run tf-infra:fmt

npm

npx nx run tf-infra:fmt

bun

bunx nx run tf-infra:fmt

Security Testing

Run security checks on your infrastructure using Checkov with the test target:

pnpm

pnpm nx run tf-infra:test

yarn

yarn nx run tf-infra:test

npm

npx nx run tf-infra:test

bun

bunx nx run tf-infra:test

You will find your security test results in the root dist folder, under dist/packages/<my-terraform-project>/checkov.

Application-Only Targets

The following targets are only available for application type projects:

Planning your Infrastructure

Before applying changes, you can see what Terraform will do by running the plan target:

pnpm

pnpm nx run tf-infra:plan

yarn

yarn nx run tf-infra:plan

npm

npx nx run tf-infra:plan

bun

bunx nx run tf-infra:plan

This will create a plan file in dist/packages/<my-terraform-project>/terraform/dev.tfplan.

Initializing Terraform

Initialize your Terraform working directory with the init target:

pnpm

pnpm nx run tf-infra:init

yarn

yarn nx run tf-infra:init

npm

npx nx run tf-infra:init

bun

bunx nx run tf-infra:init

Deploying to AWS

After planning, you can deploy your infrastructure to AWS using the apply target:

pnpm

pnpm nx run tf-infra:apply

yarn

yarn nx run tf-infra:apply

npm

npx nx run tf-infra:apply

bun

bunx nx run tf-infra:apply

Tip

The above command applies the plan created by the plan target. Make sure to run plan first to review the changes.

Getting Outputs

Retrieve output values from your Terraform configuration:

pnpm

pnpm nx run tf-infra:output

yarn

yarn nx run tf-infra:output

npm

npx nx run tf-infra:output

bun

bunx nx run tf-infra:output

Destroying Infrastructure

When you need to tear down your infrastructure, use the destroy target:

pnpm

pnpm nx run tf-infra:destroy

yarn

yarn nx run tf-infra:destroy

npm

npx nx run tf-infra:destroy

bun

bunx nx run tf-infra:destroy

Caution

This will permanently delete all resources managed by this Terraform configuration. Use with caution!

Destroying Bootstrap Resources

To clean up the bootstrap resources (S3 bucket for state storage):

pnpm

pnpm nx run tf-infra:bootstrap-destroy

yarn

yarn nx run tf-infra:bootstrap-destroy

npm

npx nx run tf-infra:bootstrap-destroy

bun

bunx nx run tf-infra:bootstrap-destroy

More Information

For more information about Terraform, please refer to the Terraform Documentation and AWS Provider Documentation.