Skip to main content

Inheritance Behavior

The stacks.inherit section controls what sections are inherited when components use metadata.inherits. By default, metadata inheritance is enabled, allowing governance policies and component configurations to be defined once and inherited by all instances.

Configuration​

atmos.yaml

stacks:
  inherit:
    metadata: true  # Enable metadata inheritance (default)

Configuration Reference​

metadata

When true (default), the metadata section is inherited from base components along with vars, settings, env, backend, and providers.

Environment variable: ATMOS_STACKS_INHERIT_METADATA

Default: true

Exceptions: The following metadata fields are NOT inherited:

  • metadata.inherits - Defines the inheritance relationship itself
  • metadata.type - Component type is per-component and not inherited

Example - Enable metadata inheritance (default):

stacks:
  inherit:
    metadata: true

Example - Disable metadata inheritance (backwards compatibility):

stacks:
  inherit:
    metadata: false

When disabled, only vars, settings, env, backend, and providers are inherited. The metadata section must be defined explicitly in each component.

Use Cases​

Version Management​

When using versioned component folders, metadata inheritance allows you to define the component version once in a base component:

stacks/catalog/vpc/_defaults.yaml

components:
  terraform:
    vpc/defaults:
      metadata:
        type: abstract
        name: vpc              # Stable logical identity
        component: vpc/v2      # Pin to version
        locked: true
        terraform_workspace_pattern: "{tenant}-{environment}-{stage}"
        description: "Virtual Private Cloud network configuration"
        owner: "platform-team"

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

components:
  terraform:
    vpc/primary:
      metadata:
        inherits: [vpc/defaults]
        # All metadata fields inherited - including component version
      vars:
        vpc_cidr: "10.0.0.0/16"

    vpc/secondary:
      metadata:
        inherits: [vpc/defaults]
        # All metadata fields inherited - including component version
      vars:
        vpc_cidr: "10.1.0.0/16"

The benefit: When upgrading to vpc/v3, change metadata.component once in vpc/defaults, and all instances (vpc/primary, vpc/secondary) inherit the new version automatically. No need to update each instance individually.

Governance Policies​

Inherit governance settings (locking, workspace patterns, ownership) from base components:

stacks/catalog/critical-infrastructure.yaml

components:
  terraform:
    critical/defaults:
      metadata:
        type: abstract
        locked: true
        terraform_workspace_pattern: "{tenant}-{environment}-{stage}"
        description: "Critical infrastructure - requires approval for changes"
        owner: "platform-team"

All components inheriting from critical/defaults automatically get the governance settings.

Backwards Compatibility​

If metadata inheritance causes issues with existing configurations, disable it:

atmos.yaml

stacks:
  inherit:
    metadata: false  # Disable metadata inheritance

When disabled, components behave as they did before this feature - only vars, settings, env, backend, and providers are inherited.