CloudFormation Configuration

Configure the directory containing CloudFormation components in atmos.yaml. Define each component's template and deployment settings in its stack manifest.

Experimental

Configuration

atmos.yaml

components:
  aws/cloudformation:
    # Base path to native aws/cloudformation component directories (where local
    # templates live). Defaults to components/cloudformation.
    base_path: components/cloudformation
    source:
      ttl: 1h

Configuration Reference

base_path

Base directory for native aws/cloudformation components. A component's path: (and, when set, stack_policy.file:) resolve relative to its component directory under this base path. Defaults to components/cloudformation.

source.ttl

Default cache duration for remote CloudFormation sources, such as 1h, 7d, or 0s (refresh each invocation). Unset by default. A component's source.ttl overrides it. See source caching.

Configure templates, parameters, sources, and delivery targets in stack manifests.

Region Resolution

CloudFormation API calls need an AWS region. Atmos resolves it in this order, most specific wins:

1. The component's resolved region (including inherited defaults)
2. The active identity's region
3. The AWS SDK's default credential/region chain (AWS_REGION, shared config)

components:
  aws/cloudformation:
    vpc:
      region: us-west-2
      # ...

Region Inheritance

Set region directly at the scope where it should apply. From lowest to highest precedence:

1. Stack root: region
2. Component-type defaults: aws/cloudformation.region
3. Base components declared in metadata.inherits, in inheritance order
4. The concrete component: components.aws/cloudformation.<name>.region
5. The component's overrides.region

Imports merge these scopes using the usual Atmos import order. A region at the stack root applies only to native CloudFormation components; Terraform provider regions remain Terraform configuration.

region: us-east-1

aws/cloudformation:
  region: us-east-2

components:
  aws/cloudformation:
    defaults:
      metadata:
        type: abstract
      region: us-west-1
    app:
      metadata:
        inherits: [defaults]
      region: us-west-2
      stack_name: my-app
      path: template.yaml

The app component deploys in us-west-2. Without its own region, it inherits us-west-1 from defaults. Without that base default, it uses the type default us-east-2, then the stack default us-east-1. Remote output lookups use the same resolved region.

Deprecated region setting

The old settings.aws_cloudformation.region path still works but emits a deprecation warning. Move its value to region at the same scope. Atmos normalizes the legacy spelling before merging scopes, so a legacy component value still overrides a modern type default. When both spellings appear at the same scope, region wins.

Use Atmos Doctor to preview and apply the migration:

atmos doctor --only=cloudformation-region --fix --dry-run
atmos doctor --only=cloudformation-region --fix

Doctor preserves the declaration's scope and comments, creates a recovery backup, and verifies resolved regions across imports and inheritance. Conflicting declarations or changes in the resolved region require manual review.

Component Environment Variables

Set region to choose the component's region. Entries for AWS_REGION or AWS_DEFAULT_REGION in the component's env block do not select it. Atmos warns when those entries conflict with the resolved region.

Account Selection

The account is the active identity's account. A delivery target's auth block can select a different identity for that destination; an explicit CLI identity still takes precedence.

See the atmos aws cloudformation command reference and the CloudFormation stack configuration for component-level fields.