Configuring Components in Stacks

Stacks are used to compose multiple components together and provide their configuration. The schema is the same for all stacks, but the configuration can be different. Use a combination of imports, inheritance, and catalogs for a template-free way to reuse configuration and override values when needed.

Component Schema

A Component consists of the infrastructure as code business logic (e.g. a Terraform "root" module) as well as the configuration of that component. The configuration of a component is stored in a Stack configuration.

To configure a Component in a Stack, you define the component in the components section of the Stack configuration.

Disambiguation

• Terraform Component is a 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)

Terraform Schema

The schema of an Atmos Terraform Component in an Atmos Stack is as follows:

components:
  terraform:
    # the slug of the component
    example:

      # configuration specific to atmos
      metadata:
        # Components can be of type "real" (default) or "abstract"
        type: real
        # This is the directory path of the component.
        # In this example, we're referencing a component in the `components/terraform/stable/example` folder.
        component: stable/example

        # We can leverage multiple inheritance to sequentially deep merge multiple configurations
        inherits:
          - example-defaults

        # Settings are where we store configuration related to integrations.
        # It's a freeform map; anything can be placed here.
        settings:
          spacelift: { }

      # Define the terraform variables, which will get deep-merged and exported to a `.tfvars` file by atmos.
      vars:
        enabled: true
        name: superduper
        nodes: 10

Terraform Attributes

vars (optional)

The vars section is a free-form map. Use component validation to enforce policies.

vars.namespace (optional)

This is an optional terraform-null-label convention.

The namespace of all stacks. Typically, there will be one namespace for the organization.

Example:

vars:
  namespace: acme

vars.tenant (optional)

This is an optional terraform-null-label convention.

In a multi-tenant configuration, the tenant represents a single tenant. By convention, we typically recommend that every tenant have its own Organizational Unit (OU).

Example:

vars:
  tenant: platform

vars.stage (optional)

This is an optional terraform-null-label convention.

The stage is where workloads run. See our glossary for disambiguation.

Example:

vars:
  # Production stage
  stage: prod

vars.environment (optional)

This is an optional terraform-null-label convention.

The environment is used for location where things run. See our glossary for disambiguation.

Example:

vars:
  # us-east-1
  environment: ue1

metadata (optional)

The metadata section extends functionality of the component.

settings

The settings block is a free-form map used to pass configuration information to integrations.

Helmfile Schema

The schema of an Atmos Helmfile Component in an Atmos Stack is as follows:

components:
  helmfile:
    # the slug of the component
    example:

      # configuration specific to atmos
      metadata:
        # Components can be of type "real" (default) or "abstract"
        type: real

        # This is the directory path of the component.
        # In this example, we're referencing a component in the `components/terraform/stable/example` folder.
        component: stable/example

        # We can leverage multiple inheritance to sequentially deep merge multiple configurations
        inherits:
          - example-defaults

      # Define the Helmfile variables, which will get deep-merged into the Helmfile configuration.
      vars:
        enabled: true
        release_name: my-release
        chart_version: "1.2.3"

Helmfile Attributes

vars (optional)

The vars section is a free-form map. Use component validation to enforce policies.

vars.namespace (optional)

This is an optional terraform-null-label convention.

The namespace of all stacks. Typically, there will be one namespace for the organization.

Example:

vars:
  namespace: acme

metadata (optional)

The metadata section extends functionality of the component.

settings

The settings block is a free-form map used to pass configuration information to integrations.

Types of Components

In Atmos, each component configuration defines its type through the metadata.type parameter. This defines how the component behaves—whether it can be used directly to provision resources or serves as a base configuration for other components.

The type of component is expressed in the metadata.type parameter of a given component configuration.

There are two types of components:

real

Think of a real component as one that can be deployed. It’s fully configured and ready to be provisioned, similar to a "concrete" class in programming. Once defined, you can use it to create resources or services directly in your infrastructure.

abstract

An abstract component is more like a blueprint. It can’t be deployed on its own. Instead, it’s a base configuration that needs to be extended or inherited by other components. This is similar to an "abstract base classes" in programming—it defines reusable configurations, but it’s not complete enough to be deployed directly.

Disabling Components with 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. Disabling a component does not cause deletion. It just signals that it's no longer managed by Atmos.

Note

This should not be confused with Cloud Posse's conventions and best practices of having modules and components define a Terraform input named enabled. This is a general convention and vars.enabled is not a special variable. Atmos does not treat it differently from any other variable.

Example:

# Disable a component in a specific environment
components:
  terraform:
    vpc:
      metadata:
        type: real
        enabled: false
      vars:
        name: primary-vpc

Using the metadata.enabled flag makes it easy to ensure that only the intended components are active in each environment.