Component Types Reference

This reference covers Atmos component types, directory layout conventions, abstract components, the complete metadata section, and inheritance chain mechanics.

Component Types

Terraform Components

The most common type. Each component is a Terraform root module that provisions infrastructure resources.

Directory structure:

components/terraform/<component-name>/
  main.tf           # Resources and module calls
  variables.tf      # Input variable declarations
  outputs.tf        # Output value declarations
  versions.tf       # Provider and Terraform version constraints
  providers.tf      # Provider configuration blocks (shell)
  backend.tf.json   # Generated by Atmos (add to .gitignore)
  providers_override.tf.json  # Generated by Atmos (add to .gitignore)

Stack configuration:

components:
  terraform:
    vpc:
      metadata:
        component: vpc        # Relative to components.terraform.base_path
      vars:
        cidr_block: "10.0.0.0/16"
      backend_type: s3
      backend:
        s3:
          bucket: my-tfstate-bucket
      providers:
        aws:
          region: us-east-1

Atmos generates backend.tf.json and providers_override.tf.json in the component directory before running Terraform commands. These generated files should be added to .gitignore.

Component Versioning

Keep multiple component versions side by side when a gradual migration is needed:

components/terraform/vpc/
  v1/
  v2/

Set metadata.name to preserve the workspace key while metadata.component selects the physical version:

components:
  terraform:
    vpc:
      metadata:
        name: vpc
        component: vpc/v2

Alternatively, use atmos vendor pull to pin a remote component version; see the atmos-vendoring skill.

Helmfile Components

Used for deploying Helm charts to Kubernetes clusters via helmfile.

Directory structure:

components/helmfile/<component-name>/
  helmfile.yaml

Stack configuration:

components:
  helmfile:
    nginx-ingress:
      vars:
        chart_version: "4.7.1"
        namespace: ingress-nginx

Packer Components

Used for building machine images (AMIs, VM images).

Directory structure:

components/packer/<component-name>/
  template.pkr.hcl

Stack configuration follows the same pattern as Terraform components, using components.packer in the stack manifest.

Metadata Section Complete Reference

The metadata section is only valid within component definitions (components.terraform.<name>.metadata). It cannot be used at global or component-type scope.

component

Type: string Default: The Atmos component name

Specifies the path to the Terraform root module relative to the components base path. When not set, Atmos uses the Atmos component name as the path.

components:
  terraform:
    # Atmos component name "vpc-prod" maps to components/terraform/vpc/
    vpc-prod:
      metadata:
        component: vpc

This field is what enables the multiple component instances pattern -- multiple Atmos components can reference the same Terraform root module.

inherits

Type: list of strings Default: empty

Defines the list of component names from which this component inherits configuration. Components are merged in list order; later entries override earlier entries.

components:
  terraform:
    rds:
      metadata:
        inherits:
          - base/defaults     # Merged first
          - base/production   # Merged second (overrides conflicts)

The base components must exist in the same resolved stack (either defined inline or imported). Inherited sections: vars, env, settings, hooks, backend, backend_type, providers, command.

type

Type: string (abstract | real) Default: real

Controls whether the component can be deployed:

• abstract: Cannot be provisioned. Used as a blueprint for inheritance. Does not appear in default atmos describe stacks output.
• real: Can be provisioned with atmos terraform apply.

components:
  terraform:
    vpc/defaults:
      metadata:
        type: abstract

name

Type: string Default: derived from component field

Provides a stable logical identity for the component. Used to generate the Terraform workspace key prefix. Critical for folder-based versioning:

components:
  terraform:
    vpc:
      metadata:
        name: vpc            # Workspace key prefix stays "vpc"
        component: vpc/v2    # Physical path can change between versions

Without metadata.name, upgrading from vpc/v1 to vpc/v2 would change the workspace key prefix, potentially orphaning existing state files.

enabled

Type: boolean Default: true

Controls whether a component is active. Disabled components are skipped during apply and do not appear in active listings:

components:
  terraform:
    expensive-feature:
      metadata:
        enabled: false      # Disabled in dev to save costs

locked

Type: boolean Default: false

Prevents modifications to a component. Atmos warns or prevents changes:

components:
  terraform:
    core-network:
      metadata:
        locked: true

terraform_workspace

Type: string Default: computed from stack name

Overrides the Terraform workspace name with a literal string:

components:
  terraform:
    vpc:
      metadata:
        terraform_workspace: "custom-workspace-name"

terraform_workspace_pattern

Type: string Default: none

Overrides the workspace name using a pattern with context tokens:

components:
  terraform:
    vpc:
      metadata:
        terraform_workspace_pattern: "{tenant}-{environment}-{stage}"

Supported tokens: {namespace}, {tenant}, {environment}, {region}, {stage}, {attributes}, {component}, {base-component}.

custom

Type: map (any) Default: empty

User-defined metadata. Atmos preserves it but does not interpret it. Useful for external tooling integration:

components:
  terraform:
    vpc:
      metadata:
        custom:
          owner: platform-team
          cost_center: "12345"
          tier: critical
          sla: "99.99%"

The custom section is inherited from base components via deep-merge.

Inheritance Chain Mechanics

Resolution Order

For a component with inheritance, Atmos resolves configuration in this order:

1. Start with the global-scope vars, env, settings from all imports.
2. Apply component-type scope (terraform.vars, etc.).
3. For each component in the inherits list (in order): a. Resolve that base component's full configuration (including its own inheritance chain, recursively). b. Deep-merge it on top of the accumulated result.
4. Deep-merge the component's own inline configuration on top.
5. Apply overrides sections (global, then type-specific).

Circular Inheritance Detection

Atmos detects circular inheritance chains and reports an error. For example, if component A inherits from B, and B inherits from A, Atmos will halt with an error message identifying the cycle.

Inheritance Depth

While there is no hard limit on inheritance depth, best practice is to keep chains to 2-3 levels for maintainability. Deeply nested chains become difficult to debug and understand.

What Is Inherited

Section	Inherited?
vars	Yes (deep-merged)
env	Yes (deep-merged)
settings	Yes (deep-merged)
hooks	Yes (deep-merged)
backend	Yes (deep-merged)
backend_type	Yes (overridden)
providers	Yes (deep-merged)
command	Yes (overridden)
metadata	No (except custom when configured)
auth	Component-specific

Describing Inheritance

Use atmos describe component to see the fully resolved configuration and understand what was inherited:

atmos describe component vpc -s plat-ue2-prod

The output shows the final merged result of all inheritance, imports, and overrides.