Skip to main content

Configuring Components in Stacks

Components are the building blocks of your infrastructure, defined in the components section of stack manifests. Each component represents infrastructure-as-code (Terraform, Helmfile, or Packer) combined with its configuration. This page covers how to configure components in stacks and the common attributes available across all component types.

Supported Component Types​

Component Schema​

A component consists of infrastructure-as-code business logic (e.g., a Terraform root module) combined with its configuration in a stack manifest.

Disambiguation

  • Terraform Component is simply a Terraform Root Module that consists of the resources defined in the .tf files in a working directory (e.g. components/terraform/infra/vpc)

  • Component Configuration provides configuration (variables and other settings) for a type of component (e.g. a Terraform component) and is defined in one or more YAML stack config files (which are called Atmos stacks)

Common Configuration Sections​

All component types support these configuration sections:

vars
Variables passed to the component. Use component validation to enforce policies.
env
Environment variables set during execution.
settings
Integrations and custom metadata.
metadata
Component behavior and inheritance. See Metadata Attributes below.
command
Override the default executable.
hooks
Lifecycle event handlers.

Basic Component Structure​

Components are defined in stack manifests under the components section, organized by type:

components:
  terraform:
    vpc:
      vars:
        vpc_cidr: "10.0.0.0/16"

  helmfile:
    nginx:
      vars:
        replicas: 3

  packer:
    ami-builder:
      vars:
        base_ami: ami-12345678

Metadata Attributes​

The metadata section controls component behavior, inheritance, and type.

Component Types (metadata.type)​

The metadata.type parameter defines how a component behaves—whether it can be deployed directly or serves as a base configuration:

real
A real component is fully configured and ready to be provisioned. Think of it as a "concrete" class that can create resources directly in your infrastructure. This is the default type.
abstract
An abstract component is a blueprint that can't be deployed on its own. It defines reusable configurations that must be inherited by other components, similar to an abstract base class in programming.

Disabling Components (metadata.enabled)​

The metadata.enabled parameter controls whether a component is included in deployment. By default, components are enabled. Setting metadata.enabled to false skips the component entirely—no workspace is created, and no Terraform commands are executed.

info

Disabling a component does not cause deletion. It signals that the component is no longer managed by Atmos.

components:
  terraform:
    vpc:
      metadata:
        type: real
        enabled: false
      vars:
        name: primary-vpc

Locking Components (metadata.locked)​

The metadata.locked parameter prevents changes to a component while still allowing read operations. When locked, operations that would modify infrastructure (like terraform apply) are blocked, while read-only operations (like terraform plan) remain available.

components:
  terraform:
    rds:
      metadata:
        locked: true
      vars:
        name: production-database
info

Locking a component does not affect the Terraform state. It's intended to communicate intention and prevent accidental changes to sensitive infrastructure.

Component Versioning (metadata.component)​

The metadata.component parameter specifies which component implementation to use. This is how you manage component versions in Atmos—by pointing to different component folders.

By default, if metadata.component is not specified, Atmos uses the component's name as the path. You can explicitly reference different versions or implementations:

All environments point to the same component folder, with versions rolled out through release controls in your deployment pipeline:

# All environments use components/terraform/vpc/
components:
  terraform:
    vpc:
      vars:
        name: my-vpc
Version Management Patterns

The metadata.component parameter is the foundation of Version Management Patterns in Atmos. See Version Management Patterns to learn how to choose and implement the right versioning strategy.

Type-Specific Configuration​

Each component type has additional configuration options:

Terraform-Specific​

  • backend / backend_type - State storage configuration
  • remote_state_backend / remote_state_backend_type - Remote state access
  • providers - Provider configuration
  • terraform_workspace / terraform_workspace_pattern - Workspace settings

See Terraform Components for details.

Helmfile-Specific​

Helmfile components use the standard sections listed above. Helmfile-specific configuration is typically passed through vars.

See Helmfile Components for details.

Packer-Specific​

Packer components use the standard sections listed above. Packer-specific configuration is typically passed through vars.

See Packer Components for details.

Component-Type Defaults​

You can define default settings for all components of a type at the root level:

# Defaults for all Terraform components in this stack
terraform:
  vars:
    terraform_version: "1.5"
  env:
    TF_IN_AUTOMATION: "true"
  backend_type: s3
  backend:
    s3:
      bucket: my-terraform-state

# Defaults for all Helmfile components
helmfile:
  vars:
    timeout: 600
  env:
    HELM_CACHE_HOME: /tmp/helm-cache

# Individual components inherit and can override these defaults
components:
  terraform:
    vpc:
      vars:
        vpc_cidr: "10.0.0.0/16"

Component Directory Structure​

Atmos looks for component implementations in directories configured in atmos.yaml:

# atmos.yaml
components:
  terraform:
    base_path: components/terraform
  helmfile:
    base_path: components/helmfile
  packer:
    base_path: components/packer

Your project structure would look like:

├── atmos.yaml
├── components/
│   ├── terraform/
│   │   ├── vpc/
│   │   │   ├── main.tf
│   │   │   ├── variables.tf
│   │   │   └── outputs.tf
│   │   └── eks/
│   ├── helmfile/
│   │   └── nginx/
│   │       └── helmfile.yaml
│   └── packer/
│       └── ami-builder/
│           └── template.pkr.hcl
└── stacks/

Best Practices​

  1. Use Abstract Components: Create abstract base components in catalogs with common settings, then inherit from them in stack-specific components.

  2. Use Type Defaults: Define common settings at the component-type level to keep individual component configurations focused on unique values.

  3. Organize by Purpose: Group components logically in your directory structure (e.g., networking/, databases/, monitoring/).

  4. Share with Catalogs: Create reusable component configurations in stacks/catalog/ that can be imported across environments.

  5. Lock Critical Infrastructure: Use metadata.locked to protect production databases and other sensitive components from accidental changes.