cloudposse/atmos/atmos-aws-cloudformation

Atmos Native AWS CloudFormation Components

Use this skill for native components."aws/cloudformation" stacks. Atmos deploys them through the AWS SDK for Go v2, without an aws, cfn, sam, or Rain binary. This first aws/* component and its nested commands are experimental; the top-level aws group stays stable.

Related Skills

Component Shape

Define CloudFormation stacks under components.aws/cloudformation in stack manifests. Prefer the unquoted aws/cloudformation: key in YAML examples; a / does not require quoting:

components:
  aws/cloudformation:
    vpc:
      path: template.yaml                    # file reference, relative to the component's base path
      stack_name: "{{ .vars.stage }}-vpc"     # explicit; no legacy name-pattern interpolation
      parameters:
        CidrBlock: "10.0.0.0/16"
        AvailabilityZones:
          - us-east-1a
          - us-east-1b
        DbPassword: !secret DB_PASSWORD       # secrets flow into parameters, not env
      capabilities:
        - CAPABILITY_IAM
      tags:
        team: platform
      stack_policy:
        file: stack-policy.json              # or an inline `body:` (JSON string or YAML map)
      role_arn: "arn:aws:iam::123456789012:role/cfn-deploy"
      termination_protection: true
      timeout_in_minutes: 30
      settings:
        aws_cloudformation:
          region: us-east-2
      provision:
        backend:
          enabled: true
        targets:
          artifacts:
            kind: aws/s3
            bucket: acme-plat-cfn-artifacts
            region: us-east-2
          gitops:
            kind: git
            repository: acme/infra-gitops
            path: stacks/dev/vpc

CloudFormation components use the same stack sections as other component types — vars, env, auth, metadata, settings, dependencies, hooks, source/provision, inheritance, and overrides — plus CloudFormation-specific fields. generate: and plugins: are not supported: a generate: key on a component, under the aws/cloudformation: type-level section, or in CloudFormation overrides is a stack-processing error. Use an inline template: instead — Atmos renders it with Go templates (when templates.settings.enabled: true) and YAML functions, so per-stack template content needs no generated files.

Commands

All operation commands accept --all, --affected (with --base/--ref/--sha/--repo-path/ --clone-target-ref/--ssh-key/--ssh-key-password), --include-dependents (requires --affected), and --tags/--labels bulk selection, matching atmos describe affected semantics. --all/--affected are mutually exclusive with a positional component argument, and so is --tags/--labels-based selection. atmos aws cfn is a Cobra alias for atmos aws cloudformation that works with every verb.

Confirmation: direct apply previews the changeset before asking; deploy auto-approves. delete also asks; publish-only/external targets do not. See apply flow for cleanup and non-TTY behavior.

Output formats

Formats: json, yaml, hcl, env, dotenv, bash, csv, tsv, table, github; key modifiers: --flatten, --uppercase. A positional key selects one output. Masking reads deployed templates and fails closed if sensitivity metadata is unavailable; --mask=false disables it. Internal lookups keep real values. See output formats and masking for the full contract.

Changesets

Use changeset create, list, execute, and delete for explicit two-phase deployments. See changeset operations for confirmation and capability requirements.

Drift Detection

atmos aws cloudformation drift detect vpc -s dev [--fail-on-drift]
atmos aws cloudformation drift describe vpc -s dev

drift detect runs DetectStackDrift/polls DescribeStackDriftDetectionStatus; drift describe renders the results of the most recent detection (DescribeStackResourceDrifts). --fail-on-drift exits non-zero when drift is found, for CI gating — drift is not a hard failure by default. drift describe shows each MODIFIED resource's property differences (path, expected, actual, type). Drift summaries follow Native CI. Atmos Pro dashboard uploads through UploadInstanceStatus remain future work.

Delivery Targets (Backend Management)

By default apply/deploy deploy directly to the account/region resolved for the component (see Region Resolution). A component can declare additional named provision.targets, selected with --target: aws/s3 (publish-only upload, also used automatically to package any template over CloudFormation's 51,200-byte inline limit), git (GitOps commit instead of deploying), and aws/stackset (multi-account/region, see Stack Sets). "Backend" means the S3 artifact bucket a kind: aws/s3 target declares — CloudFormation's own stack state is service-managed. Manage it like atmos terraform backend:

atmos aws cloudformation backend create vpc -s dev

Set provision.backend.enabled: true to auto-provision the bucket on first use instead of running backend create explicitly. See references/delivery-targets.md for the full target-kind table, the backend verb group, auto-provisioning semantics, and today's packaging-scope limitation (local assets like Lambda zips aren't rewritten, only the template body is uploaded).

Source & Template Management

Point a component at a remote template through the top-level source: section instead of committing it to your infrastructure repository — the same JIT-vendoring mechanism other component types use: