Skip to main content

!unset

Purpose

Use the !unset function to delete or remove keys from Atmos stack configurations during inheritance and merging. This allows you to explicitly remove values that were defined in parent configurations or imports.

Usage​

The !unset function is a YAML explicit type that marks a key for deletion from the configuration. Unlike setting a value to null (which keeps the key with a null value), !unset completely removes the key from the configuration.

Examples​

Basic Usage​

stacks/base.yaml
components:
  terraform:
    vpc:
      vars:
        enable_nat_gateway: true
        enable_vpn_gateway: true
        availability_zones: ["us-east-1a", "us-east-1b", "us-east-1c"]
stacks/dev.yaml
import:
  - base

components:
  terraform:
    vpc:
      vars:
        # Remove VPN gateway for dev environment
        enable_vpn_gateway: !unset

        # Override NAT gateway setting
        enable_nat_gateway: false

After processing, the dev stack will have:

  • enable_nat_gateway: false (overridden)
  • No enable_vpn_gateway key (removed by !unset)
  • availability_zones inherited from base

Removing Nested Values​

stacks/config.yaml
components:
  terraform:
    app:
      vars:
        config:
          database:
            host: "prod.db.example.com"
            port: 5432
            ssl_mode: "require"
            backup_enabled: true
stacks/override.yaml
import:
  - config

components:
  terraform:
    app:
      vars:
        config:
          database:
            # Remove backup configuration for this environment
            backup_enabled: !unset

            # Keep other database settings
            host: "dev.db.example.com"

Working with Lists​

When used in arrays, !unset removes the item from the list:

stacks/example.yaml
components:
  terraform:
    security:
      vars:
        allowed_ports:
          - 80
          - 443
          - !unset  # This item will be removed from the list
          - 8080

The resulting allowed_ports will be [80, 443, 8080].

Use Cases​

1. Environment-Specific Configuration​

Remove production-only settings from development environments:

# base.yaml - Contains all possible settings
monitoring:
  alerts:
    pagerduty: enabled
    email: enabled
    sms: enabled

# dev.yaml - Remove production alerting
monitoring:
  alerts:
    pagerduty: !unset  # Don't need PagerDuty in dev
    sms: !unset        # Don't need SMS alerts in dev
    email: enabled     # Keep email notifications

2. Feature Flags​

Remove feature flags that aren't applicable to certain deployments:

# defaults.yaml
features:
  experimental_feature: true
  beta_feature: true
  legacy_support: true

# modern-stack.yaml
features:
  legacy_support: !unset  # Remove legacy support entirely

3. Security Configuration​

Remove sensitive configurations from non-production environments:

# prod.yaml
security:
  vault_integration: true
  audit_logging: true
  compliance_mode: "strict"

# staging.yaml
import:
  - prod

security:
  compliance_mode: !unset  # Not needed in staging
  audit_logging: false      # Override to false

How It Works​

The !unset function operates at two levels:

  1. During YAML parsing: When the YAML is initially parsed, keys marked with !unset are identified
  2. During merging: When configurations are merged (through imports or inheritance), keys marked with !unset are removed from the target configuration

This ensures that the key is completely absent from the final configuration, not just set to null or an empty value.

Comparison with Other Approaches​

ApproachResultUse Case
key: !unsetKey is completely removedWhen you want the key to not exist
key: nullKey exists with null valueWhen you want to explicitly set null
key: ""Key exists with empty stringWhen you want an empty value
Omitting the keyKey is inherited if defined in parentNormal inheritance behavior

Important Notes​

  • !unset only affects the specific key it's assigned to
  • It works with all Atmos configuration sections: vars, settings, env, metadata, etc.
  • The function is processed after template rendering but before final merging
  • You cannot "unset" a key that doesn't exist (no error is thrown, it's simply ignored)
  • Works with all merge strategies (replace, append, merge)