Skip to main content

Configure Component Metadata

The metadata section configures how Atmos interprets and manages a component. Unlike other sections, metadata is only valid within component definitions (components.terraform.<name>.metadata), not at the global or component-type level.

Use Cases​

  • Component Mapping: Specify which Terraform root module a component uses.
  • Inheritance: Define which components a component inherits from.
  • Abstract Components: Mark components as templates that cannot be deployed directly.
  • Component Control: Enable, disable, or lock components.

Configuration Scope​

The metadata section is only valid inside component definitions:

components:
  terraform:
    vpc:
      metadata:
        component: vpc/network
        inherits:
          - vpc/defaults

It cannot be used at the global level or under terraform: / helmfile: / packer: defaults.

Metadata Fields​

component​

Specifies the path to the Terraform root module, relative to your components directory:

components:
  terraform:
    vpc-prod:
      metadata:
        component: vpc  # Uses components/terraform/vpc
      vars:
        environment: prod

This allows multiple stack components to share the same Terraform root module with different configurations.

name​

Provides a stable logical identity for the component, used to generate the backend workspace_key_prefix. This is especially important when using versioned component folders:

components:
  terraform:
    vpc:
      metadata:
        name: vpc              # Stable logical identity
        component: vpc/v2      # Physical version path

Why this matters: Without name, the workspace_key_prefix is auto-generated from component, which includes the version (vpc-v2). When you upgrade to vpc/v3, the workspace key prefix changes, creating a new state file and losing your existing infrastructure state.

With metadata.name: The workspace key prefix stays stable (vpc) across version upgrades, so your Terraform state path remains vpc/{workspace}/terraform.tfstate regardless of which version you're running.

See Workspace Key Management for more details.

inherits​

Defines a list of components from which this component inherits configuration:

components:
  terraform:
    vpc/defaults:
      metadata:
        type: abstract
      vars:
        enable_dns_hostnames: true
        enable_dns_support: true

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

Inheritance is processed in order, with later items and the component's own values taking precedence. For detailed inheritance behavior, see Inheritance.

type​

Marks a component as abstract or real (default):

components:
  terraform:
    vpc/base:
      metadata:
        type: abstract  # Cannot be deployed directly
      vars:
        enable_dns_hostnames: true

Abstract components:

  • Serve as templates for other components to inherit from
  • Cannot be deployed with atmos terraform apply
  • Do not appear in atmos describe stacks output by default
  • Are useful for DRY configuration patterns

enabled​

Controls whether a component is active:

components:
  terraform:
    monitoring:
      metadata:
        enabled: false  # Component is disabled
      vars:
        # ...

When enabled: false:

  • The component is skipped during atmos terraform apply
  • The component does not appear in active stack listings
  • Useful for conditionally disabling components per environment

locked​

Prevents modifications to a component:

components:
  terraform:
    core-network:
      metadata:
        locked: true  # Prevent changes
      vars:
        # ...

When locked: true:

  • Atmos will warn or prevent changes to the component
  • Useful for protecting critical infrastructure components

terraform_workspace​

Overrides the Terraform workspace name with a literal string value:

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

By default, Atmos calculates workspace names automatically based on the stack name. Use this field when you need explicit control over the workspace name.

For detailed information about how Atmos manages Terraform workspaces, see Workspaces.

terraform_workspace_pattern​

Overrides the Terraform workspace name using a pattern with context tokens:

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

Supported tokens:

  • {namespace} - The namespace from context variables
  • {tenant} - The tenant from context variables
  • {environment} - The environment from context variables
  • {region} - The region from context variables
  • {stage} - The stage from context variables
  • {attributes} - The attributes from context variables
  • {component} - The Atmos component name
  • {base-component} - The base component name (from metadata.component)

For detailed information about workspace patterns and examples, see Workspaces.

custom​

A user extension point for storing arbitrary metadata that Atmos preserves but does not interpret:

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

Use custom for:

  • Storing metadata for external tooling to consume (CI/CD pipelines, dashboards)
  • Adding labels or annotations readable via atmos describe stacks
  • Custom categorization that doesn't affect Atmos behavior
note

The custom section is inherited from base components when stacks.inherit.metadata is enabled (the default). Like other metadata fields, values from derived components override inherited values, and nested maps are deep-merged.

Examples​

Multiple Instances from One Module​

Deploy the same VPC module in different configurations:

stacks/orgs/acme/plat/prod/us-east-1.yaml

components:
  terraform:
    vpc-main:
      metadata:
        component: vpc
      vars:
        vpc_cidr: "10.0.0.0/16"
        name: main

    vpc-isolated:
      metadata:
        component: vpc
      vars:
        vpc_cidr: "10.1.0.0/16"
        name: isolated
        enable_internet_gateway: false

Both vpc-main and vpc-isolated use the same components/terraform/vpc root module but with different configurations.

Abstract Base with Concrete Implementations​

stacks/catalog/vpc/_defaults.yaml

components:
  terraform:
    vpc/defaults:
      metadata:
        type: abstract
        component: vpc
      vars:
        enable_dns_hostnames: true
        enable_dns_support: true
        enable_nat_gateway: true
        single_nat_gateway: false

stacks/orgs/acme/plat/prod/us-east-1.yaml

import:
  - catalog/vpc/_defaults

components:
  terraform:
    vpc:
      metadata:
        inherits:
          - vpc/defaults
      vars:
        vpc_cidr: "10.0.0.0/16"
        availability_zones:
          - us-east-1a
          - us-east-1b
          - us-east-1c

Environment-Specific Component Control​

stacks/orgs/acme/plat/dev/us-east-1.yaml

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

stacks/orgs/acme/plat/prod/us-east-1.yaml

components:
  terraform:
    expensive-feature:
      metadata:
        enabled: true   # Enabled in production
      vars:
        # ...

Multi-Level Inheritance​

stacks/catalog/components.yaml

components:
  terraform:
    # Level 1: Base defaults
    base/defaults:
      metadata:
        type: abstract
      vars:
        tags:
          ManagedBy: Atmos

    # Level 2: VPC defaults inheriting from base
    vpc/defaults:
      metadata:
        type: abstract
        component: vpc
        inherits:
          - base/defaults
      vars:
        enable_dns_hostnames: true

    # Level 3: Production VPC inheriting from vpc/defaults
    vpc/prod:
      metadata:
        type: abstract
        inherits:
          - vpc/defaults
      vars:
        enable_nat_gateway: true
        multi_az: true

Best Practices​

  1. Use Abstract Components: Create abstract base components for shared configuration to keep your stacks DRY.

  2. Meaningful Component Names: Use descriptive names that indicate the component's purpose and any specialization (e.g., vpc/prod, vpc/isolated).

  3. Document Inheritance: Keep inheritance chains shallow (2-3 levels) and well-documented for maintainability.

  4. Protect Critical Components: Use locked: true for infrastructure components that should not change without careful review.

  5. Use enabled for Environment Differences: Rather than duplicating component definitions, use enabled to control which components are active per environment.