# 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

**File:** `atmos.yaml`

```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](/stacks/components/aws-cloudformation#caching-and-refresh).

Configure templates, parameters, sources, and delivery targets in
[stack manifests](/stacks/components/aws-cloudformation).

## 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)

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

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

:::warning 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](/cli/commands/doctor) to preview and apply the migration:

```shell
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](/stacks/components/aws-cloudformation#target-authentication)
can select a different identity for that destination; an explicit CLI identity
still takes precedence.

See the [`atmos aws cloudformation`](/cli/commands/aws/cloudformation)
command reference and the
[CloudFormation stack configuration](/stacks/components/aws-cloudformation) for
component-level fields.