# Migrating from Rain Move the CloudFormation stacks you deploy with Rain to Atmos. Your templates, parameter files, and deployed stacks stay where they are. This guide maps every Rain directive, config file, and command to its Atmos-native equivalent, so you end up with Atmos conventions rather than a Rain emulation. :::tip Using an AI Coding Assistant? Install the `atmos-migration` skill so Claude Code, Cursor, GitHub Copilot, and other AI coding assistants can apply this guide directly to your repository: ```shell atmos ai skill install atmos-migration ``` See [AI Agent Skills](/ai/skills) for details. ::: > ⚠️ Experimental ## Why Migrate from Rain [Rain was archived in July 2026](https://github.com/aws-cloudformation/rain). The existing releases still run, but nothing ships after them. If Rain is how your team deploys CloudFormation, the question is what replaces it, and Atmos answers it with a native `aws/cloudformation` component type. Atmos talks to the CloudFormation API through the AWS SDK, so there is no Rain, `aws`, or `sam` binary involved, and your stacks become components in the same stack manifests, inheritance, and CI workflows the rest of your infrastructure uses. The migration is parity, not compatibility. Rain preprocessed templates and resolved `!Rain::` directives before deployment. Atmos sends a file template to CloudFormation exactly as written and offers a native way to accomplish what each directive did. Templates that are plain CloudFormation need no changes at all. ## Key Differences at a Glance | Concern | Rain | Atmos | |---|---|---| | Stack name | Command argument | `stack_name` on the component | | Parameters | `--params`, `--config`, `RAIN_VAR_*` | `parameters:` map, or `!include` of your existing parameter file | | Tags | `--tags`, `--config`, `RAIN_DEFAULT_TAG_*` | `tags:` map, or `tags: !labels` to carry Atmos labels onto the stack | | Region and credentials | `--region`, `--profile` | `settings.aws_cloudformation.region` and [Atmos Auth](/stacks/auth) or the SDK credential chain | | Template directives | `!Rain::Env`, `!Rain::Include`, `!Rain::Embed`, `!Rain::S3` | YAML functions inside an included template, hooks for uploads | | Artifact bucket | `rain-artifacts--`, created on first deploy | A `kind: aws/s3` provision target, created by `backend create` or automatically with `provision.backend.enabled: true` | | Asset packaging | `rain pkg` rewrites the template | `archive` and `publish` hook steps upload assets; the template references them through parameters | | Environments | One invocation per environment | One stack manifest per environment, sharing a catalog through imports and inheritance | | Stack outputs | Console or `aws cloudformation describe-stacks` | `atmos aws cloudformation output`, plus `!aws.cloudformation.output` from other components | | Drift | Not a Rain feature | `drift detect` and `drift describe` | ## Directory Structure Comparison ### Before (Rain) ```text . ├── templates/ │ ├── app.yaml # !Rain::Env, !Rain::Embed, !Rain::Include, !Rain::S3 │ └── fragments/tags.yaml ├── src/handler.py # embedded by !Rain::Embed ├── dist/worker/ # uploaded by !Rain::S3 ├── templates/network.yaml # a second stack the app reads an output from ├── params/ │ ├── dev.yaml # {Parameters: {...}, Tags: {...}} per environment │ └── staging.yaml └── deploy.sh # loops environments, hand-orders network before app, # copies the network output into the app parameters ``` ### After (Atmos) ```text . ├── atmos.yaml ├── components/cloudformation/app/ │ ├── template.yaml # plain CloudFormation │ ├── fragments/tags.yaml │ └── src/ │ ├── handler.py # inlined through !include │ └── worker/ # archived and published by the hook ├── components/cloudformation/network/template.yaml ├── params/ # unchanged; read with !include │ ├── dev.yaml │ └── staging.yaml └── stacks/ ├── catalog/ │ ├── network.yaml # abstract base: template, stack name pattern │ └── app.yaml # abstract base: parameters, dependency on network, packaging hook ├── mixins/region/us-east-1.yaml └── deploy/ ├── dev.yaml # imports the bases and the mixin; includes params/dev.yaml └── staging.yaml ``` Nothing forces this layout. Point `components."aws/cloudformation".base_path` at wherever your templates already live and keep the parameter files where they are. ## Concept Mapping ### Rain Directives Rain resolved these directives by rewriting the template before it reached CloudFormation. Atmos never rewrites a file template, so a template that still contains a directive fails locally, before any AWS call, with the replacement named for each directive: ```text Error: aws/cloudformation template contains Rain directives, which Atmos does not preprocess components/cloudformation/app/template.yaml uses Rain directives (Constant, Env, Embed, S3). 💡 Replace !Rain::Env with `!env NAME` in the component's parameters:, or inside the template when it is included with template: !include template.yaml | eval 💡 Migration guide: https://atmos.tools/migration/rain ``` | Directive | What Rain did | Atmos-native replacement | |---|---|---| | `!Rain::Env NAME` | Inserted an environment variable | A CloudFormation parameter fed by `!env NAME` in `parameters:`, or `!env NAME` inside the template when it is included with `\| eval` | | `!Rain::Constant NAME`, `${Rain::NAME}` | Inserted a value from the template's `Rain: Constants:` section | A CloudFormation parameter fed from stack `vars:`, or `{{ .vars.name }}` in an inline template | | `!Rain::Include file.yaml` | Merged a YAML or JSON fragment | `!include file.yaml` inside the template, included with `\| eval` | | `!Rain::Embed file` | Inlined a file as a string | `!include file` inside the template, included with `\| eval`; a non-YAML file loads as a string | | `!Rain::S3 path`, `!Rain::S3Http path` | Uploaded a file or directory and inserted its S3 URI or URL | `archive` and `publish` hook steps upload the asset; the template reads the bucket and key from parameters | | `!Rain::Module` | Client-side template composition (experimental in Rain) | No equivalent. Expand modules in your build step, or use AWS CDK, and point `path` at the output | Two of these replacements rely on the `| eval` option of [`!include`](/functions/yaml/include). An included file is data by default, so its YAML functions are not evaluated. Adding `| eval` turns that on for the included template, and CloudFormation's own short-form intrinsics (`!Ref`, `!Sub`, `!GetAtt`) are preserved either way. #### Environment Values and Constants ### Before (Rain) ```yaml Rain: Constants: MarkerPrefix: /acme/app Resources: Marker: Type: AWS::SSM::Parameter Properties: Name: !Sub "${Rain::MarkerPrefix}/${Stage}/owner" Type: String Value: !Rain::Env DEPLOY_OWNER ``` ### After (Atmos) ```yaml # components/cloudformation/app/template.yaml — plain CloudFormation Parameters: Stage: Type: String MarkerPrefix: Type: String DeployOwner: Type: String Resources: Marker: Type: AWS::SSM::Parameter Properties: Name: !Sub "${MarkerPrefix}/${Stage}/owner" Type: String Value: !Ref DeployOwner ``` ```yaml # stacks/deploy/dev.yaml — the values come from stack configuration parameters: Stage: "{{ .vars.stage }}" MarkerPrefix: /acme/app DeployOwner: !env DEPLOY_OWNER ``` Turning a directive into a CloudFormation parameter keeps the template plain, which is the most portable outcome. An unset variable without a default resolves to an empty string and logs a warning, so give `!env` a default (`!env DEPLOY_OWNER platform`) when an empty value would be a mistake. #### Included Fragments and Embedded Files When you would rather keep the directives' shape, include the template into `template:` with `| eval` and use Atmos functions in the same places Rain used directives: ### Before (Rain) ```yaml Resources: Bucket: Type: AWS::S3::Bucket Properties: Tags: !Rain::Include fragments/tags.yaml Function: Type: AWS::Lambda::Function Properties: Role: !GetAtt Role.Arn Code: ZipFile: !Rain::Embed ../src/handler.py ``` ### After (Atmos) ```yaml # stacks/catalog/app.yaml components: "aws/cloudformation": app: template: !include ../../components/cloudformation/app/template.yaml | eval ``` ```yaml # components/cloudformation/app/template.yaml Resources: Bucket: Type: AWS::S3::Bucket Properties: Tags: !include ./fragments/tags.yaml Function: Type: AWS::Lambda::Function Properties: Role: !GetAtt Role.Arn Code: ZipFile: !include ./src/handler.py ``` A nested `!include` inside the template resolves `./` and `../` relative to the template file, exactly where Rain's `!Rain::Embed ../src/handler.py` looked; bare paths resolve relative to `base_path`. #### Uploaded Assets `!Rain::S3` uploaded a file or directory during deployment and wrote the location into the template. Atmos keeps uploads out of the template and in a hook, because YAML functions only read values and never change infrastructure. The hook runs before `apply` and before `changeset create`, and the template reads the bucket and key through parameters: ### Before (Rain) ```yaml Resources: Worker: Type: AWS::Lambda::Function Properties: Code: !Rain::S3 Path: ../dist/worker BucketProperty: S3Bucket KeyProperty: S3Key Zip: true ``` ### After (Atmos) ```yaml # stacks/catalog/app.yaml components: "aws/cloudformation": app: path: template.yaml vars: stage: dev release: v1 # Change this value for each release. parameters: WorkerBucket: "acme-plat-cfn-artifacts-{{ .vars.stage }}" WorkerKey: "lambda/worker-{{ .vars.release }}.zip" provision: targets: artifacts: kind: aws/s3 bucket: "acme-plat-cfn-artifacts-{{ .vars.stage }}" region: us-east-1 hooks: package-worker: events: - before.aws/cloudformation.apply - before.aws/cloudformation.changeset-create kind: steps with: - name: archive type: archive source: src/worker/ destination: .build/worker.zip mtime: epoch - name: publish type: publish source: .build/worker.zip destination: "lambda/worker-{{ .vars.release }}.zip" target: artifacts ``` ```yaml # components/cloudformation/app/template.yaml Resources: Worker: Type: AWS::Lambda::Function Properties: Code: S3Bucket: !Ref WorkerBucket S3Key: !Ref WorkerKey ``` The key carries a `release` variable (set it per deployment, for example from a git tag or `!env RELEASE`), because CloudFormation only updates a Lambda function when the `S3Key` value changes; uploading new code under the same key leaves the function untouched. The `publish` step skips uploads whose content has not changed, so repeated deployments of the same release report `0 uploaded, 1 unchanged`. See [asset packaging hooks](/stacks/components/aws-cloudformation#asset-packaging-hooks) for the full pattern. ### Parameter Files and Rain Config Files An AWS CLI parameter array is accepted as-is, and the `Parameters` and `Tags` sections of a Rain config file are selected with a YQ expression: **File:** `stacks/deploy/dev.yaml` ```yaml components: "aws/cloudformation": app: parameters: !include ../../params/dev.json ``` **File:** `stacks/deploy/staging.yaml` ```yaml components: "aws/cloudformation": app: parameters: !include ../../params/rain-config.yaml .Parameters tags: !include ../../params/rain-config.yaml .Tags ``` Including a whole Rain config file as `parameters` is an error, because `Parameters` and `Tags` would be read as two parameters with map values. Values Rain took from `RAIN_VAR_*` and `RAIN_DEFAULT_TAG_*` environment variables belong in the catalog as `parameters` and `tags`, where every environment inherits them. ### Tags Stack tags are a map. An AWS CLI tags file is a list of `Key`/`Value` objects and is rejected rather than silently dropped. Reshape it with a YQ expression, or carry your Atmos `metadata.labels` onto the stack explicitly: ```yaml tags: !include '../../params/tags.json ".[] as $t ireduce ({}; .[$t.Key] = $t.Value)"' # or tags: !labels ``` Atmos labels and tags select components in Atmos commands; they never become CloudFormation tags unless you write `tags: !labels`. ### The Artifact Bucket Rain created `rain-artifacts--` the first time a deployment needed it. Atmos uses the `kind: aws/s3` provision target you declare, and creates it in one of two explicit ways: ```shell atmos aws cloudformation backend create app -s dev ``` or, for the same create-on-demand behavior Rain had, with `provision.backend.enabled: true` on the component, which makes `apply` and `deploy` create a missing bucket. Preview commands never create it; they fail with a hint naming the command that will. Templates over the 51,200-byte inline limit are uploaded to this bucket automatically on every command that submits a template. ## CLI Command Comparison | Rain | Atmos | Notes | |---|---|---| | `rain deploy