Skip to main content

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

Automatic Initialization​

Atmos automatically runs terraform init in these scenarios:

  1. Before terraform plan - Ensures the working directory is initialized
  2. Before terraform apply - Ensures providers and modules are available
  3. 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:

  1. Generate a backend.tf.json file with the appropriate backend configuration
  2. Initialize Terraform with this backend configuration
  3. 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

Native Terraform Flags​

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

  1. Direct flags - Pass Terraform flags directly if they don't conflict with Atmos flags
  2. 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