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:

Run this generator@aws/nx-plugin:terraform#project

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:terraform#project

yarn

$ yarn nx g @aws/nx-plugin:terraform#project

npm

$ npx nx g @aws/nx-plugin:terraform#project

bun

$ bunx nx g @aws/nx-plugin:terraform#project

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
6. Click Generate

Build your command5

nameRequired

type

applicationlibrary

directory

subDirectory

preferInstallDependencies

true

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

Options

Generator Options5 options

nameRequiredstring

The name of the project.

typeenumDefault: application

Whether this is a terraform lib (re-usable modules) or app (deployable).

applicationlibrary

directorystringDefault: packages

The directory of the new project.

subDirectorystring

The sub directory the project is placed in. By default this is the project name.

preferInstallDependenciesbooleanDefault: true

Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

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

type = application

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
• Directoryscripts Node helpers run by the nx bootstrap, bootstrap-destroy and init targets

  • aws-config.ts Resolves account + region via the AWS SDK credential chain
  • bootstrap.ts Pulls/pushes the bootstrap tfstate and runs terraform apply
  • bootstrap-destroy.ts Empties the state bucket and runs terraform destroy
  • init.ts Runs terraform init with the S3 backend config
  • env.ts Points terraform init at the shared provider cache
• checkov.yml Checkov configuration, including the checks to skip
• project.json Project configuration and build targets

Shared Terraform Modules

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.

type = library

Library Type

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

• Directorysrc

  • main.tf Main Terraform module file
• checkov.yml Checkov configuration, including the checks to skip
• project.json Project configuration and build targets

Application vs Library

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"
}

Note that the S3 bucket above would fail the Checkov security scan, which checks that the bucket has the appropriate security settings enabled.

Cross project dependencies

If you wanted to execute a module from a separate 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"
aws_region  = "us-west-2"

Variable names

Every name you set here must be declared in src/variables.tf — the generator declares aws_region and environment.

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": {
                    "env": { "TF_ENV": "dev" }
                },
                "prod": {
                    "env": { "TF_ENV": "prod" }
                }
            },
            "options": {
                "forwardAllArgs": true,
                "commands": ["tsx {projectRoot}/scripts/init.ts {projectRoot}"],
                "cwd": "{workspaceRoot}"
            }
        },
        "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/prod.tfvars -out=../../../dist/packages/infra/terraform/prod.tfplan"
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd": "{projectRoot}/src"
            },
            "dependsOn": ["init"]
        }
    }
}

Default Environment

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

• pnpm
• yarn
• npm
• bun

pnpm nx apply tf-infra --configuration=prod

yarn nx apply tf-infra --configuration=prod

npx nx apply tf-infra --configuration=prod

bunx nx apply tf-infra --configuration=prod

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

type = application

Remote State Bootstrap (Application Projects Only)

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 bootstrap tf-infra

yarn

yarn nx bootstrap tf-infra

npm

npx nx bootstrap tf-infra

bun

bunx nx bootstrap tf-infra

AWS Profile Configuration

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 validate tf-infra

yarn

yarn nx validate tf-infra

npm

npx nx validate tf-infra

bun

bunx nx validate tf-infra

Linting

Terraform projects use terraform fmt to check formatting.

Running the Linter

To invoke the linter to check your project, you can run the lint target.

pnpm

pnpm nx lint tf-infra

yarn

yarn nx lint tf-infra

npm

npx nx lint tf-infra

bun

bunx nx lint tf-infra

Fixing Lint Issues

The majority of linting or formatting issues can be fixed automatically by running with the --configuration=fix argument.

pnpm

pnpm nx lint tf-infra --configuration=fix

yarn

yarn nx lint tf-infra --configuration=fix

npm

npx nx lint tf-infra --configuration=fix

bun

bunx nx lint tf-infra --configuration=fix

Similarly if you would like to fix all lint issues in all packages in your workspace, you can run:

pnpm

pnpm nx run-many --target lint --all --configuration=fix

yarn

yarn nx run-many --target lint --all --configuration=fix

npm

npx nx run-many --target lint --all --configuration=fix

bun

bunx nx run-many --target lint --all --configuration=fix

Shorthand Command

This has a shorthand command from the root of your workspace:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Skipping Lint Issues

To avoid linting issues slowing you down during development (particularly if you have non auto-fixable issues in your project), you can run a build with the skip-lint configuration:

pnpm

pnpm nx run-many --target build --configuration=skip-lint

yarn

yarn nx run-many --target build --configuration=skip-lint

npm

npx nx run-many --target build --configuration=skip-lint

bun

bunx nx run-many --target build --configuration=skip-lint

This skips the format check entirely during build.

Shorthand Command

This has a shorthand command from the root of your workspace:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint

Security Testing

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

pnpm

pnpm nx checkov tf-infra

yarn

yarn nx checkov tf-infra

npm

npx nx checkov tf-infra

bun

bunx nx checkov tf-infra

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

Checkov runs as part of build.

Checks are configured in the project’s checkov.yml. Add a check id to skip-check to suppress it across the whole project:

checkov.yml

skip-check:
  - CKV_AWS_115 # Concurrent execution limit
  - CKV_AWS_116 # Dead Letter Queue

To suppress a check for a single resource instead, add a #checkov:skip=<id>:<reason> comment inside the resource block:

resource "aws_s3_bucket" "example" {
  #checkov:skip=CKV_AWS_18:Access logging not required for this bucket
  bucket = "example"
}

Running Terraform Tests

The test target runs Terraform’s native test framework over any .tftest.hcl files in your project:

pnpm

pnpm nx test tf-infra

yarn

yarn nx test tf-infra

npm

npx nx test tf-infra

bun

bunx nx test tf-infra

A project with no test files is a no-op success, so you can add tests when you need them. build runs this target, so your tests run as part of a normal build.

Each run block evaluates your configuration. Use command = plan to check what Terraform would do (this expands the whole module graph, so it catches plan-time errors that validate cannot), or command = apply to create real resources and assert on their outputs. Declaring mock_provider means no API calls are made and no AWS credentials are needed, which keeps plan tests fast and safe to run in CI:

src/main.tftest.hcl

mock_provider "aws" {
  mock_data "aws_caller_identity" {
    defaults = { account_id = "123456789012" }
  }
  mock_data "aws_region" {
    defaults = { region = "us-east-1" }
  }
}

variables {
  aws_region  = "us-east-1"
  environment = "dev"
}

run "plan_is_valid" {
  command = plan

  assert {
    condition     = data.aws_caller_identity.current.account_id == "123456789012"
    error_message = "Unexpected account id"
  }
}

Set every variable your configuration requires in the variables block, otherwise the run fails with “has a required variable … with no set value”.

Every target that runs terraform init reuses a provider cache under .terraform/plugin-cache in your workspace root, so providers are downloaded once rather than on every run. Each project gets its own directory there: two terraform init runs filling one cache at the same time can each compute a different hash for the same provider, which terraform then rejects against your .terraform.lock.hcl. See the Terraform documentation for more information.

Set TF_PLUGIN_CACHE_DIR in your environment to point the vended init script at a cache you manage yourself — a volume shared between workspaces, say. Note that the test target reads its path from project.json, so change it there too.

type = application

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 plan tf-infra

yarn

yarn nx plan tf-infra

npm

npx nx plan tf-infra

bun

bunx nx plan tf-infra

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

plan depends on assemble, so it produces the artifacts your modules reference, such as the Lambda bundles and generated operations metadata, without running the lint, test and type-check gates.

Use build in your pipeline

assemble is used for faster iteration during development. Run build in your CI pipeline to ensure your project passes quality gates prior to a production deployment.

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 apply tf-infra

yarn

yarn nx apply tf-infra

npm

npx nx apply tf-infra

bun

bunx nx apply tf-infra

Auto-Approve

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

Deploy Alias

A deploy target is also available as an alias for apply. You can use either

• pnpm
• yarn
• npm
• bun

pnpm nx deploy tf-infra

yarn nx deploy tf-infra

npx nx deploy tf-infra

bunx nx deploy tf-infra

or

pnpm

pnpm nx apply tf-infra

yarn

yarn nx apply tf-infra

npm

npx nx apply tf-infra

bun

bunx nx apply tf-infra

interchangeably.

Getting Outputs

Retrieve output values from your Terraform configuration:

pnpm

pnpm nx output tf-infra

yarn

yarn nx output tf-infra

npm

npx nx output tf-infra

bun

bunx nx output tf-infra

Destroying Infrastructure

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

pnpm

pnpm nx destroy tf-infra

yarn

yarn nx destroy tf-infra

npm

npx nx destroy tf-infra

bun

bunx nx destroy tf-infra

Destructive Operation

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 bootstrap-destroy tf-infra

yarn

yarn nx bootstrap-destroy tf-infra

npm

npx nx bootstrap-destroy tf-infra

bun

bunx nx bootstrap-destroy tf-infra

This empties the state bucket before destroying it, and resolves the region from the AWS SDK credential chain, so it runs unattended in CI.

Destroy your infrastructure first

The state bucket holds the state for every environment, so run destroy for each environment before this. Once the bucket is gone, Terraform no longer knows about the resources it created.

More Information

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