Atmos Components

Atmos Component Architecture

Components are the building blocks of infrastructure in Atmos. Each component is an opinionated, reusable unit of infrastructure-as-code -- typically a Terraform root module -- that solves a specific problem. Atmos separates the component implementation (code) from its configuration (stack manifests), enabling one implementation to be deployed many times with different settings.

What Components Are

In Atmos, a component consists of two parts:

1. Implementation -- The infrastructure code itself (a Terraform root module, Helmfile, or Packer template) stored in the components/ directory.
2. Configuration -- The settings that customize how the component is deployed, defined in stack manifests under the components section.

This separation is fundamental: you write the Terraform module once, then configure it differently for each environment, region, and account through stack YAML files.

Component Types

Atmos natively supports three component types:

Terraform is by far the most common type. Custom commands can extend Atmos to support any tooling.

Directory Structure

Components are stored in your project's components/ directory, organized by type:

components/
  terraform/
    vpc/
      main.tf
      variables.tf
      outputs.tf
      versions.tf
    eks/
      cluster/
        main.tf
        variables.tf
        outputs.tf
    s3-bucket/
      main.tf
      variables.tf
      outputs.tf
    iam-role/
      main.tf
      variables.tf
      outputs.tf
  helmfile/
    nginx-ingress/
      helmfile.yaml
    cert-manager/
      helmfile.yaml
  packer/
    ubuntu-base/
      template.pkr.hcl

The base path for Terraform components is configured in atmos.yaml:

components:
  terraform:
    base_path: "components/terraform"

Nested directories are supported. A component at components/terraform/eks/cluster/ is referenced as eks/cluster in stack configurations.

Component Configuration in Stacks

Components are configured in the components section of stack manifests:

components:
  terraform:
    vpc:
      metadata:
        component: vpc           # Points to components/terraform/vpc/
      vars:
        cidr_block: "10.0.0.0/16"
        availability_zones:
          - us-east-1a
          - us-east-1b
      settings:
        validation:
          check-cidr:
            schema_type: jsonschema
            schema_path: schemas/vpc.json

    eks-cluster:
      metadata:
        component: eks/cluster   # Points to components/terraform/eks/cluster/
      vars:
        cluster_name: prod-eks
        kubernetes_version: "1.28"

Each component configuration can include these sections:

Dependencies

Use dependencies.components for component ordering and affected/dependent analysis:

components:
  terraform:
    app:
      dependencies:
        components:
          - component: vpc
          - component: database
            stack: plat-ue2-prod
          - kind: file
            path: configs/app.yaml
          - kind: folder
            path: src/lambda

Use dependencies.tools for runtime CLIs at global, component-type, or per-component scope; Atmos auto-installs and injects them, so do not add a separate install step.

Do not add new settings.depends_on examples. If a repository already uses that legacy field, recommend migrating it to dependencies.components.

Source Provisioning and Workdirs

Components can declare source in stack config for just-in-time provisioning from Git, OCI, S3, HTTP, or local paths. Treat source provisioning as part of component configuration: it controls how the component implementation is fetched, while vars, env, backend, and other sections control how that implementation is run.

Use component source provisioning when different stacks need different remote component versions, or when the repository should not commit the fetched implementation. When source provisioning is used, prefer provision.workdir.enabled: true so each component-stack instance gets an isolated execution directory.

components:
  terraform:
    vpc:
      source: "github.com/cloudposse-terraform-components/aws-vpc.git?ref=1.450.0"
      provision:
        workdir:
          enabled: true

Atmos provisions sources automatically before Terraform commands when needed. Use explicit source commands when an agent needs to inspect, refresh, or clean the fetched implementation:

atmos terraform source pull vpc --stack dev
atmos terraform source describe vpc --stack dev
atmos terraform source list --stack dev
atmos terraform source delete vpc --stack dev
atmos list sources

For protected sources, route identity and provider details to atmos-auth. For checked-in copies of remote components, route to atmos-vendoring; vendoring and source provisioning are alternatives for obtaining component implementation code.

Abstract vs Real Components

Abstract Components

Mark a component as metadata.type: abstract to create a blueprint that cannot be deployed directly:

components:
  terraform:
    vpc/defaults:
      metadata:
        type: abstract
        component: vpc
      vars:
        enabled: true
        nat_gateway_enabled: true
        max_subnet_count: 3
        vpc_flow_logs_enabled: true

Abstract components:

• Cannot be provisioned with atmos terraform apply (Atmos returns an error).
• Do not appear in atmos describe stacks output by default.
• Serve as base configurations for real components to inherit from.

Real Components (Default)

If metadata.type is not specified, the component is real and can be deployed:

components:
  terraform:
    vpc:
      metadata:
        inherits:
          - vpc/defaults
      vars:
        vpc_cidr: "10.0.0.0/16"

Component Inheritance

Single Inheritance

Use metadata.inherits to inherit configuration from a base component:

components:
  terraform:
    vpc/defaults:
      metadata:
        type: abstract
        component: vpc
      vars:
        enabled: true
        nat_gateway_enabled: true

    vpc:
      metadata:
        inherits:
          - vpc/defaults
      vars:
        nat_gateway_enabled: false   # Override inherited value

The derived component receives all vars, env, settings, hooks, backend, providers, and command from the base, then its own values are deep-merged on top.

Multiple Inheritance

A component can inherit from multiple bases. Entries are processed in order with later entries having higher precedence:

components:
  terraform:
    rds:
      metadata:
        component: rds
        inherits:
          - base/defaults       # Applied first
          - base/logging        # Applied second
          - base/production     # Applied last (highest base precedence)
      vars:
        name: my-database       # Inline has highest precedence

This enables composing "traits" -- reusable abstract components that represent independent configuration concerns (logging, security, sizing, environment settings).