By Sebastian Stadil —

Using Atmos with Terraform & OpenTofu

Infrastructure as Code (IaC) tools like Terraform and its open-source fork OpenTofu are indispensable for modern cloud operations. However, as environments grow—across multiple accounts, regions, and teams—managing configurations effectively can become a major hurdle. How do you keep things DRY (Don't Repeat Yourself), consistent, and scalable? Enter orchestration tools. One such tool is Atmos by Cloud Posse.

What is Atmos?

Atmos is a command-line interface (CLI) tool and framework designed to enhance Terraform and OpenTofu by providing a structured approach to configuration management and workflow orchestration. It doesn't replace your IaC engine; it helps you manage it more effectively, especially at scale.

The core idea is to separate your configuration (the "what" and "where") from your IaC code (the "how"). Atmos uses YAML for its configurations and introduces a few key concepts:

  • Components: These are your reusable building blocks, typically corresponding to Terraform/OpenTofu root modules (e.g., a VPC, an EKS cluster, a database). They contain the actual HCL code.
  • Stacks: These are YAML files that define how components are deployed in a specific environment or context. A stack is like an architectural blueprint, specifying which components to use and what variables to pass to them for a given environment (e.g., dev-us-east-1, prod-eu-west-2).
  • Configuration Management: Atmos uses deep-merging, inheritance, and imports within its YAML stack configurations. This allows you to define base settings and override them for specific environments, significantly reducing duplication.

How Atmos Works with Terraform/OpenTofu

Atmos acts as a sophisticated wrapper around the native terraform or tofu CLI. When you run an Atmos command like atmos terraform plan <component> -s <stack>:

  1. Atmos reads the specified stack's YAML configuration.
  2. It deep-merges all relevant settings, including imported files and inherited values, to determine the final set of variables and backend configuration for the component.
  3. It then generates a varfile (e.g., .tfvars.json) and potentially a backend configuration file.
  4. Finally, Atmos executes the native Terraform/OpenTofu command (e.g., terraform plan -var-file=...), passing in the generated configurations.

This means your Terraform/OpenTofu root modules remain "vanilla" HCL, making them independently testable and reusable.

Key Benefits of Using Atmos

  • Simplified Configuration: YAML stacks with inheritance and imports help manage complex configurations.
  • Standardization: Enforces consistency in how infrastructure is defined and deployed.
  • Reusability: Components are reusable, and stack configurations can be layered.
  • Scalability: Designed to handle complex multi-account and multi-environment setups.

Getting Started: A Glimpse

An Atmos project typically involves an atmos.yaml CLI configuration file and directories for components and stacks.

Example atmos.yaml:

# atmos.yaml
components:
  terraform:
    base_path: "components/terraform" # Where your Terraform root modules live
    command: "tofu"                   # Or "terraform"

stacks:
  base_path: "stacks"                 # Where your stack YAML files live
  included_paths:
    - "orgs/**/*"                     # Pattern to find stack files
  name_pattern: "{tenant}-{environment}-{stage}" # How stacks are named

Example Stack File (stacks/orgs/my-tenant/dev-usea1.yaml):

import:
  - "catalog/terraform/vpc" # Import a predefined VPC component configuration
  - "catalog/terraform/eks"

vars: # Global variables for this stack
  aws_region: "us-east-1"
  environment: "dev"
  stage: "dev"
  tenant: "my-tenant"

components:
  terraform:
    vpc: # Configure the 'vpc' component
      vars:
        cidr_block: "10.1.0.0/16"
        enable_nat_gateway: false
    eks: # Configure the 'eks' component
      vars:
        instance_type: "t3.medium"
        min_size: 1

Summary of Core Atmos Concepts

Here's a quick reference for key Atmos terms:

Term

Definition

Atmos

A CLI tool and framework for orchestrating IaC tools, focusing on configuration and workflow.

Component

A reusable IaC building block (typically a Terraform root module).

Stack

A YAML manifest defining component configurations for a specific environment or purpose.

Vendoring

Replicating external dependencies (like Terraform modules) into your project for immutability.

Workflow

A sequence of Atmos and shell commands to automate multi-step operations.

The Bigger Picture: Framework Flexibility vs. Managed Platforms

Atmos offers a powerful and flexible framework, especially for teams deeply comfortable with building and managing their own IaC orchestration layer. It provides excellent structure for complex, CLI-driven Terraform/OpenTofu workflows, particularly when leveraging the broader Cloud Posse ecosystem of components.

However, this flexibility means your team is responsible for the end-to-end setup and maintenance of this ecosystem – from component design and testing to vendoring strategies, CI/CD pipeline integration, and ensuring consistent operational practices. While Atmos structures the "how," the operational overhead of managing these numerous moving parts remains.

For organizations seeking a more integrated and managed experience, especially around governance, role-based access control (RBAC), environment provisioning, cost visibility, and policy enforcement out-of-the-box, exploring comprehensive IaC platforms could be a valuable consideration. These platforms often aim to abstract away some of the underlying boilerplate and operational complexities, offering a different balance of control, convenience, and built-in enterprise features.

Conclusion

Atmos provides a robust, convention-over-configuration approach to taming Terraform and OpenTofu at scale. It's a strong contender if your organization is prepared to invest in its specific patterns and manage the surrounding tooling. As always, the best tool depends on your team's specific needs, existing expertise, and the level of operational management you're looking to undertake versus leveraging a more managed platform solution.