Terraform Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Terraform Integration provides a suite of Nx executors and generators to manage infrastructure as code within an Nx workspace. It streamlines the lifecycle of Terraform projects, including initialization, planning, application, and destruction of resources, while supporting advanced features like workspace management and CI/CD automation.
This integration ensures that infrastructure changes are versioned and managed alongside application code. It leverages the Terraform CLI to execute commands and provides configuration options to handle backend states, variables, and provider versions.
Sources: packages/terraform/README.md, packages/terraform/package.json
Architecture and Core Components
The integration consists of a generator for project setup and multiple executors that wrap standard Terraform CLI commands. It uses the hcl2-json-parser dependency to interact with Terraform configurations.
Lifecycle Flow
The following diagram illustrates the typical workflow when using the Terraform integration:
The diagram shows the standard progression from initialization to destruction, along with maintenance tasks.
Sources: packages/terraform/README.md, packages/terraform/src/generators/init/init.impl.ts:40-115
Project Generation
The init generator sets up a new Terraform project within the Nx workspace. It validates that the Terraform CLI is installed before proceeding. If the CLI is missing, the generator throws an error.
Project Configuration
The generator adds a project configuration to the workspace with several pre-defined targets. Each target maps to a specific executor:
| Target | Executor | Default Options |
|---|---|---|
initialize | @nx-extend/terraform:init | ciMode: true, upgrade: false |
plan | @nx-extend/terraform:plan | planFile: 'defaultplan', ciMode: true |
apply | @nx-extend/terraform:apply | autoApproval: false, ciMode: true |
workspace | @nx-extend/terraform:workspace | workspace: 'default', action: 'select' |
providers | @nx-extend/terraform:providers | lock: true, ciMode: true |
Sources: packages/terraform/src/generators/init/init.impl.ts:36-115, packages/terraform/src/generators/init/schema.json
Configuration Options
The integration supports a wide range of configuration options passed via project.json or command-line arguments.
Initialization Options
The initialization executor (@nx-extend/terraform:init) handles backend setup and module installation.
upgrade: Forces the installation of the latest module and provider versions allowed by constraints.migrateState: Attempts to migrate existing state when reconfiguring a backend.lock: Enables or disables state locking during initialization. Disabling this is dangerous and only recommended for read-only access.backendConfig: An array of key-value pairs used to configure the Terraform backend (e.g., bucket names or prefixes).
Sources: packages/terraform/src/executors/init/schema.json:8-35, packages/terraform/README.md
Execution Options
Common options used during plan, apply, and test operations:
ciMode: When true, setsTF_IN_AUTOMATION=trueandTF_INPUT=0to prevent interactive prompts in CI environments.varFile: Specifies the path to a.tfvarsfile.varString: Passes inline variables directly to the command (e.g.,region=us-east-1).autoApproval: Skips the interactive approval step forapplyanddestroycommands.
Sources: packages/terraform/README.md, packages/terraform/src/generators/init/init.impl.ts:40-80
Workspace and Provider Management
The integration provides specific targets for managing environment-specific states and local provider caches.
Workspace Operations
The workspace executor supports select, new, delete, and list actions. This allows users to switch between different environments (e.g., staging vs production) using the same configuration.
Sources: packages/terraform/README.md, packages/terraform/src/generators/init/init.impl.ts:108-115
Provider Locking and Mirroring
The providers target manages the dependency lock file. It supports:
lock: Updates the dependency lock file for specific platforms.cacheDir: Sets theTF_PLUGIN_CACHE_DIRenvironment variable to speed up provider downloads.mirror: Mirrors providers to a local directory for offline use.
Sources: packages/terraform/README.md, packages/terraform/src/executors/init/schema.json:28-32
Integration Summary
Terraform Integration within Nx allows developers to manage cloud infrastructure using standard Terraform patterns while benefiting from Nx's task running and project graph capabilities. By automating initialization, variable injection, and CI/CD configurations, it reduces the manual overhead typically associated with infrastructure deployments.
Sources: packages/terraform/README.md, packages/terraform/src/generators/init/init.impl.ts