atmos terraform init

Use this command to initialize the Terraform working directory for an Atmos component in a stack. This prepares the component for other Terraform operations.

atmos terraform init --help

Usage

Execute the terraform init command like this:

atmos terraform init <component> -s <stack> [options]

This command performs several initialization steps:

Downloads and installs provider plugins
Initializes the backend configuration
Downloads modules referenced in the configuration
Creates or updates the .terraform directory

Atmos Enhancements

Atmos enhances the init command with:

Cleans .terraform/environment file before running
Can add -reconfigure flag based on configuration
Supports passing varfile to init (OpenTofu feature) via --init-pass-vars flag
Can be skipped with --skip-init flag for other commands
Automatically runs before plan/apply/destroy commands unless skipped

tip

Atmos automatically runs terraform init before executing plan and apply commands, so you typically don't need to run this manually unless you want to reinitialize with different options.

Examples

Basic Initialization

Initialize a component in a stack:

atmos terraform init vpc -s dev

Reconfigure Backend

Force reconfiguration of the backend:

atmos terraform init vpc -s dev -reconfigure

Upgrade Providers

Upgrade provider plugins to the latest allowed versions:

atmos terraform init vpc -s dev -upgrade

Backend Migration

Migrate from one backend to another:

atmos terraform init vpc -s dev -migrate-state

Skip Backend Initialization

Initialize without configuring the backend (useful for syntax validation):

atmos terraform init vpc -s dev -backend=false

Graph-backed Bulk Init

Run init for multiple components through the Terraform dependency graph:

# Initialize every Terraform component, in dependency order
atmos terraform init --all -s dev

# Initialize only selected components
atmos terraform init --components eks/apps,eks/cluster,vpc -s dev

Unlike destroy, init has no destructive-ordering requirement, so it keeps the natural forward dependency order: prerequisites are initialized before the components that depend on them.

Independent init nodes can run concurrently when --max-concurrency is greater than 1. Concurrent init disables the shared provider plugin cache for worker subprocesses, since it isn't safe for concurrent terraform init runs.

atmos terraform init --all -s dev --max-concurrency 4

Use --failure-mode keep-going to continue independent graph branches after one component fails. The default is fail-fast.

Automatic Initialization

Atmos automatically runs terraform init in these scenarios:

Before terraform plan - Ensures the working directory is initialized
Before terraform apply - Ensures providers and modules are available
Before terraform deploy - Part of the deployment process

You can skip automatic initialization using the --skip-init flag:

atmos terraform plan vpc -s dev --skip-init

Backend Configuration

Atmos can automatically generate backend configuration files. When auto_generate_backend_file is enabled in your atmos.yaml:

components:
  terraform:
    auto_generate_backend_file: true

Atmos will:

Generate a backend.tf.json file with the appropriate backend configuration
Initialize Terraform with this backend configuration
Ensure state is stored in the correct location

Arguments

component (required): Atmos component name to initialize.

Flags

--stack / -s (required)

Atmos stack name where the component is defined.

--dry-run (optional)

Show what would be executed without actually running the command.

atmos terraform init vpc -s dev --dry-run

--skip-init (optional)

This flag doesn't apply to the init command itself, but when used with other commands, it skips the automatic terraform init.

atmos terraform plan vpc -s dev --skip-init

--init-pass-vars (optional)

Pass the generated varfile to terraform init using the --var-file flag. This is useful with OpenTofu which supports passing a varfile to init to dynamically configure backends.

atmos terraform init vpc -s dev --init-pass-vars

--all (optional)

Initialize all components in all stacks, in dependency order, through the Terraform dependency graph.

Environment variable: ATMOS_TERRAFORM_INIT_ALL

atmos terraform init --all -s dev

--affected (optional)

Initialize only the components affected by changes, in dependency order.

Environment variable: ATMOS_TERRAFORM_INIT_AFFECTED

atmos terraform init --affected

--max-concurrency (optional)

Maximum number of Terraform init components to execute concurrently when using --all, --affected, or --components. Defaults to 1 (sequential).

Environment variable: ATMOS_TERRAFORM_INIT_MAX_CONCURRENCY

atmos terraform init --all -s dev --max-concurrency 4

--failure-mode (optional)

Controls how the scheduler handles a failed component during multi-component init. Supported values:

fail-fast (default) — stop scheduling new components after the first failure
keep-going — continue independent graph branches, skipping only blocked dependents

Environment variable: ATMOS_TERRAFORM_INIT_FAILURE_MODE

atmos terraform init --all -s dev --failure-mode keep-going

--log-order (optional)

Controls how concurrent per-component logs are ordered when --max-concurrency is greater than 1.

Supported values:

stream (default) — print log lines as they arrive, interleaved across components
grouped — buffer each component's output and print it as a contiguous block after the component finishes

Environment variable: ATMOS_TERRAFORM_INIT_LOG_ORDER

atmos terraform init --all -s dev --max-concurrency 4 --log-order grouped

Native Terraform Flags

The atmos terraform init command supports all native terraform init flags. To pass native Terraform flags, you have two options:

Direct flags - Pass Terraform flags directly if they don't conflict with Atmos flags
Double-dash separator - Use -- to explicitly separate Atmos flags from Terraform flags

Using the Double-Dash Separator

The -- separator is a common Unix convention that indicates "end of options". Everything after -- is passed directly to Terraform without interpretation by Atmos. This is useful when:

You want to ensure a flag is passed to Terraform, not Atmos
You're using flags that might conflict with Atmos flags
You want to be explicit about which tool receives which flags

Example:

atmos terraform init vpc -s dev -- -backend-config="key=value" -upgrade

Native terraform init flags include:

-backend=false

Disable backend initialization.

atmos terraform init vpc -s dev -backend=false

-backend-config=PATH

Path to backend configuration file or key=value pairs.

atmos terraform init vpc -s dev -backend-config="key=value"

-force-copy

Suppress prompts about copying state data when initiating migration.

atmos terraform init vpc -s dev -force-copy

-from-module=SOURCE

Copy contents of module SOURCE into the current directory before initialization.

atmos terraform init vpc -s dev -from-module=git::https://example.com/module.git

-get=false

Disable downloading modules for this configuration.

atmos terraform init vpc -s dev -get=false

-input=false

Disable interactive prompts.

atmos terraform init vpc -s dev -input=false

-lock=false

Don't hold a state lock during backend migration.

atmos terraform init vpc -s dev -lock=false -force-copy

-lock-timeout=DURATION

Override the time Terraform will wait to acquire a state lock (default: 0s).

atmos terraform init vpc -s dev -lock-timeout=60s

-migrate-state

Reconfigure the backend and migrate any existing state.

atmos terraform init vpc -s dev -migrate-state

-no-color

Disable color codes in command output.

atmos terraform init vpc -s dev -no-color

-plugin-dir=PATH

Directory containing plugin binaries.

atmos terraform init vpc -s dev -plugin-dir=/usr/local/terraform/plugins

-reconfigure

Reconfigure the backend, ignoring any saved configuration.

atmos terraform init vpc -s dev -reconfigure

-upgrade

Upgrade modules and plugins as part of initialization.

atmos terraform init vpc -s dev -upgrade

Configuration

Configure default behavior for terraform init in your atmos.yaml:

components:
  terraform:
    # Run 'terraform init -reconfigure' by default
    init_run_reconfigure: true

    # Pass varfile to init (OpenTofu feature)
    init:
      pass_vars: true

    # Auto-generate backend configuration
    auto_generate_backend_file: true

These settings can also be controlled via environment variables:

export ATMOS_COMPONENTS_TERRAFORM_INIT_RUN_RECONFIGURE=true
export ATMOS_COMPONENTS_TERRAFORM_INIT_PASS_VARS=true
export ATMOS_COMPONENTS_TERRAFORM_AUTO_GENERATE_BACKEND_FILE=true

Common Use Cases

Switching Between Backends

When migrating from local to remote state:

# First, update your backend configuration in the component
# Then migrate the state
atmos terraform init vpc -s dev -migrate-state

Upgrading Provider Versions

After updating provider version constraints:

# Upgrade to latest allowed versions
atmos terraform init vpc -s dev -upgrade

# Or clean and reinitialize
atmos terraform clean vpc -s dev
atmos terraform init vpc -s dev

CI/CD Initialization

For CI/CD pipelines, disable interactive prompts:

atmos terraform init vpc -s dev -input=false -no-color

Debugging Initialization Issues

Enable detailed logging:

export TF_LOG=DEBUG
atmos terraform init vpc -s dev

atmos terraform plan - Generate execution plan
atmos terraform apply - Apply changes
atmos terraform clean - Clean terraform files
atmos terraform workspace - Manage workspaces

Usage​

Examples​

Basic Initialization​

Reconfigure Backend​

Upgrade Providers​

Backend Migration​

Skip Backend Initialization​

Graph-backed Bulk Init​

Automatic Initialization​

Backend Configuration​

Arguments​

Flags​

Native Terraform Flags​

Configuration​

Common Use Cases​

Switching Between Backends​

Upgrading Provider Versions​

CI/CD Initialization​

Debugging Initialization Issues​

Related Commands​