# 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

**File:** `atmos.yaml`

```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):
  ```yaml
  stacks:
    inherit:
      metadata: true
  ```
  **Example - Disable metadata inheritance** (backwards compatibility):
  ```yaml
  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](/design-patterns/version-management/folder-based-versioning), metadata inheritance allows you to define the component version once in a base component:

**File:** `stacks/catalog/vpc/_defaults.yaml`

```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"
```

**File:** `stacks/orgs/acme/plat/prod/us-east-1.yaml`

```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:

**File:** `stacks/catalog/critical-infrastructure.yaml`

```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:

**File:** `atmos.yaml`

```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.

## Related

- [Inheritance](/howto/inheritance)
- [Component Metadata](/stacks/components/component-metadata)
- [Versioned Components](/design-patterns/version-management/folder-based-versioning)
- [Stack Configuration](/cli/configuration/stacks)