# CloudFormation Components

Define CloudFormation stacks in stack manifests when you want Atmos to
deploy them alongside Terraform, Helm, Kubernetes, Helmfile, Packer, and
Ansible components. A CloudFormation component describes which template to
deploy, which parameters and capabilities to pass, and how the stack should
behave for each environment — all deployed directly through the AWS SDK for
Go v2, with no `aws` CLI or `cfn`/`sam`/`Rain` binary dependency.

> ⚠️ Experimental

## Available Configuration Sections

CloudFormation components use the same stack sections as other Atmos
components, so the stack can inherit values, run hooks, use Auth, declare
dependencies, and be included in affected runs.

- **[`metadata`](/stacks/components/component-metadata)**
  Component behavior, inheritance, and base component selection.
- **[`vars`](/stacks/vars)**
  Variables available to stack template rendering.
- **[`env`](/stacks/env)**
  Environment variables applied before CloudFormation operations run.
- **[`settings`](/stacks/settings)**

  Integration metadata and legacy dependency settings, including
  `settings.aws_cloudformation.region` (see [Region Resolution](/cli/configuration/components/aws-cloudformation#region-resolution)).
- **[`hooks`](/stacks/hooks)**

  Lifecycle event handlers. Only `diff`/`plan`, `apply`/`deploy`, and
  `delete` fire `before`/`after` events (`before.aws/cloudformation.diff`,
  `after.aws/cloudformation.apply`, and so on) — every other verb, including
  `render`, `validate`, `output`, `fmt`, `tree`, `logs`, `watch`,
  `changeset *`, `drift *`, `get *`, `stackset *`, `list`, `backend *`, and
  `source *`, does not fire hook events.
- **`source`**

  JIT provisioning of a remote template before operations run — see
  [Source Provisioning](#source-provisioning) below.
- **`provision`**

  Delivery targets: the account/region direct-deploy default, `kind: aws/s3`
  (template packaging), or `kind: git` (a Git deployment repository) — all
  selectable via `apply --target`. A fourth kind, `kind: aws/stackset`, is
  _not_ selected through `apply --target`; it's used exclusively by the
  `stackset` verb group. See [Delivery Targets](#delivery-targets) below for
  the full picture, including `provision.backend.enabled` auto-provisioning.
- **`auth`**
  Component-level Atmos Auth providers, identities, and integrations.
- **[`dependencies`](/stacks/dependencies/components)**
  Cross-component ordering for 
  `--all`
   and 
  `--affected`
   runs.

CloudFormation components do **not** support a `generate:` section — there is
no codegen-artifact output the way Terraform generates backend/provider files.
They also do not support a `plugins:` section — there is no chart-style plugin
system, unlike native Helm.

## CloudFormation-Specific Sections

- **`template` / `path` (one required)**

  The CloudFormation template, provided one of two mutually exclusive ways:
  - `template` — an **inline** template body, either a literal string (a
    `|` block scalar, YAML or JSON) or a structured YAML map. Because it's
    inline stack config, it flows through Atmos's own `{{ }}` templating
    pipeline before being sent to CloudFormation — file-based templates
    (`path:`) do not get this.
  - `path` — a **file reference**: the path to a template file, relative to
    the component's base path.
  Setting both is an error.
- **`stack_name`**
  The explicit CloudFormation stack name. There is no legacy name-pattern interpolation — set the name you want directly (Go templates are supported, like any other stack field).
- **`parameters`**

  CloudFormation template parameters as a YAML map. Values are normalized at
  the API boundary: scalars are stringified, and list values are
  comma-joined to match CloudFormation's `List<Type>`/`CommaDelimitedList`
  wire format (the API only accepts strings). `UsePreviousValue` is not
  expressible — Atmos config is the source of truth for every parameter on
  every deploy, the same declarative stance the Terraform component takes
  toward variables.
- **`capabilities`**
  Acknowledged IAM capabilities, e.g. 
  `CAPABILITY_IAM`
  , 
  `CAPABILITY_NAMED_IAM`
  , 
  `CAPABILITY_AUTO_EXPAND`
  .
- **`tags`**
  A map of 
  `key: value`
   tags applied to the CloudFormation stack (not to be confused with Atmos's own component 
  `tags`
  /
  `--tags`
   selection, which is separate).
- **`stack_policy`**

  Protects specific resources from update during `UpdateStack`. Set
  `stack_policy.file` to a stack policy JSON document path, relative to the
  component's base path. Applied after a successful `apply`.
- **`role_arn`**
  IAM role ARN that CloudFormation assumes to deploy the stack.
- **`notification_arns`**
  SNS topic ARNs that CloudFormation publishes stack events to.
- **`disable_rollback`**
  Prevents automatic rollback on stack creation failure.
- **`termination_protection`**

  Prevents the stack from being deleted. `atmos aws cloudformation delete`
  respects this and fails with an actionable hint instead of silently
  disabling it — pass `--disable-termination-protection` to delete anyway.
  Setting this to `false` and re-applying does not disable protection: apply
  only ever turns protection on, never off.
- **`timeout_in_minutes`**
  Bounds how long stack creation may run before CloudFormation rolls back.

## Example

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

```yaml
components:
  "aws/cloudformation":
    vpc:
      path: template.yaml
      stack_name: "{{ .vars.stage }}-vpc"
      parameters:
        CidrBlock: "10.0.0.0/16"
        AvailabilityZones:
          - us-east-1a
          - us-east-1b
      capabilities:
        - CAPABILITY_IAM
      tags:
        team: platform
      stack_policy:
        file: stack-policy.json
      termination_protection: true
      timeout_in_minutes: 30
      dependencies:
        components:
          - vpc-flow-logs
```

Inline templates skip the on-disk file entirely and support two forms — a
literal string body, or a structured map:

**File:** `stacks/catalog/bucket.yaml`

```yaml
components:
  "aws/cloudformation":
    bucket-inline-string:
      stack_name: "{{ .vars.stage }}-bucket"
      template: |
        AWSTemplateFormatVersion: '2010-09-09'
        Resources:
          Bucket:
            Type: AWS::S3::Bucket
            Properties:
              BucketName: "{{ .vars.stage }}-bucket"

    bucket-inline-map:
      stack_name: "{{ .vars.stage }}-bucket-map"
      template:
        AWSTemplateFormatVersion: "2010-09-09"
        Resources:
          Bucket:
            Type: AWS::S3::Bucket
            Properties:
              BucketName: "{{ .vars.stage }}-bucket-map"
```

## Component Directory Structure

CloudFormation components are located under
`components."aws/cloudformation".base_path` from `atmos.yaml` (defaults to
`components/cloudformation`):

```text
components/cloudformation/
└── vpc/
    ├── template.yaml
    └── stack-policy.json
```

## Source Provisioning

Point a component at a remote template through the top-level `source:`
section — the same JIT vendoring used by other component types — instead of
committing the template to your infrastructure repository. Two shapes are
supported:

- **Directory/subdirectory source**

  Any go-getter URI (Git, HTTP archive, S3, OCI) pointing at a directory. The
  component directory (template, stack policy, and any local assets) is
  vendored, and `path:` resolves relative to it, exactly like other
  component types' `source:` behavior.
  ```yaml
  components:
    "aws/cloudformation":
      vpc:
        source:
          uri: github.com/acme/cfn-templates.git//vpc?ref={{ .Version }}
          version: 1.2.0
        path: template.yaml
  ```
- **Single-file source**

  When the `source.uri` resolves to exactly one file — a bare template URI,
  with no surrounding directory structure — Atmos fetches it directly as the
  component's `path:` file. A CloudFormation component is often exactly
  one file, and demanding a directory structure around it would be
  ceremony.
  ```yaml
  components:
    "aws/cloudformation":
      dns:
        source:
          uri: https://raw.githubusercontent.com/acme/cfn-templates/v1.2.0/dns.yaml
  ```
  `path:` does not need to be set in the single-file case — Atmos names
  the vendored file after the source URI's basename and uses it directly.

:::note Manifest-driven vendoring is not supported
`aws/cloudformation` components cannot be vendored through a `vendor.yaml`
manifest (`atmos vendor pull`) — only the `source:`-based JIT provisioning
described above, the same restriction native Helm and Kubernetes components
have. Use `source:` for every CloudFormation component that isn't authored
directly in your infrastructure repository.
:::

## Delivery Targets

By default, `apply`/`deploy` deploy directly to the account/region resolved
for the component (see
[Region Resolution](/cli/configuration/components/aws-cloudformation#region-resolution))
via `CreateChangeSet`/`ExecuteChangeSet` — this is the implicit behavior when
`--target` is omitted and no `provision.default` is set. A component can
declare additional named targets under `provision.targets`, selected with
`--target`:

- **`kind: aws/s3`**

  Uploads the template to S3 and stops — a publish-only target, useful for a
  review step or a template too large to pass inline. This same target is
  also used automatically to package (upload) any template that exceeds
  CloudFormation's 51,200-byte inline size limit, whichever target is
  selected for the deploy. `bucket` and `region` are both required: `region`
  builds the `https://` S3 URL passed as `CreateChangeSet`'s `TemplateURL`
  (AWS rejects a bare `s3://` URI there), so it can't be left to be inferred
  later.
  ```yaml
  components:
    "aws/cloudformation":
      vpc:
        provision:
          targets:
            packaged:
              kind: aws/s3
              bucket: my-cfn-artifacts
              prefix: templates
              region: us-east-1
  ```
  The bucket must exist before `apply`/`deploy` uploads to it — either
  provision it explicitly with
  [`atmos aws cloudformation backend create`](/cli/commands/aws/cloudformation/backend/create),
  or set `provision.backend.enabled: true` (a sibling of `targets`, not
  nested under a target) to have `apply`/`deploy` create it automatically
  the first time it's missing. Auto-provisioning only runs the existence
  check up front — it never reconciles a bucket that already exists, unlike
  `backend create`/`update` run explicitly, which always re-applies the
  secure defaults (versioning, encryption, public access blocking, tags).
  ```yaml
  components:
    "aws/cloudformation":
      vpc:
        provision:
          backend:
            enabled: true
          targets:
            packaged:
              kind: aws/s3
              bucket: my-cfn-artifacts
              region: us-east-1
  ```
- **`kind: git`**

  Commits the template YAML to a Git repository (declared in
  `git.repositories`) instead of deploying it — for example, a review or
  GitOps-style pipeline that applies from the committed template separately.
  Follows the same `provision.targets` shape used by native Helm and
  Kubernetes components.
- **`kind: aws/stackset`**

  Delivers to a multi-account/multi-region
  [CloudFormation StackSet](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/what-is-cfnstacksets.html)
  instead of a single-account/region stack. Unlike `kind: aws/s3` and
  `kind: git`, an `aws/stackset` target is **not** selected through
  `apply --target` — it is used exclusively by the
  [`atmos aws cloudformation stackset`](/cli/commands/aws/cloudformation/stackset)
  verb group, and only by `create`/`update`, which resolve it to learn the
  target accounts/regions/permission model. `delete` and `instances` act
  directly on `stack_name` (the StackSet's own name) and don't resolve or
  require a `provision.targets` entry.
  ```yaml
  components:
    "aws/cloudformation":
      vpc:
        provision:
          targets:
            multi-account:
              kind: aws/stackset
              accounts:
                - "111111111111"
                - "222222222222"
              regions:
                - us-east-1
                - us-west-2
              permission_model: SELF_MANAGED
              administration_role_arn: arn:aws:iam::111111111111:role/AWSCloudFormationStackSetAdministrationRole
              execution_role_name: AWSCloudFormationStackSetExecutionRole
  ```
  - **`accounts`**
    Target AWS account IDs for stack instances.
  - **`regions`**
    Target AWS regions for stack instances.
  - **`permission_model`**
    `SELF_MANAGED`
     (default) or 
    `SERVICE_MANAGED`
    .
  - **`administration_role_arn`**
    IAM role ARN CloudFormation assumes to create/manage the StackSet (self-managed permissions).
  - **`execution_role_name`**
    IAM role name CloudFormation assumes in each target account (self-managed permissions).
  `stackset create` creates the StackSet's initial stack instances only when
  both `accounts` and `regions` are set; `stackset update` updates the
  template/parameters/capabilities and propagates the change to every
  existing instance, without changing which accounts/regions have one.

## Related

- [`atmos aws cloudformation`](/cli/commands/aws/cloudformation) command reference
- [`atmos aws cloudformation stackset`](/cli/commands/aws/cloudformation/stackset) command reference
- [CloudFormation `atmos.yaml` configuration](/cli/configuration/components/aws-cloudformation)
- [Component dependencies](/stacks/dependencies/components)