Migrating from rain¶

cfnrain starts from Rain v1.24.4 plus 22 later commits. Templates, config files, environment variables and the artifact bucket work as before. Most migrations only change the name of the binary.

Steps¶

1. Install cfnrain.

2. Replace rain with cfnrain in your scripts and CI workflows. Or link the old name, so the scripts do not change. In GitHub Actions, replace the install step. See GitHub Actions.

3. If an IAM role trust policy limits the session name, allow cfnrain-*. See Role session name.

4. Remove the Rain binary or the Homebrew formula when you no longer need it.

What stays the same¶

What changed¶

Binary and module name¶

The command is cfnrain. The Go module is github.com/awesome-foundation/cfnrain. go install uses the new path:

go install github.com/awesome-foundation/cfnrain/cmd/cfnrain@latest

cfnrain --version prints cfnrain v<version> <os>/<arch>. Scripts that parse the version output need an update.

GitHub Actions¶

allixsenos/install-rain installs Rain, and it is deprecated. Replace it with install-cfnrain:

# Before
- uses: allixsenos/install-rain@v1

# After
- uses: awesome-foundation/install-cfnrain@v1
  with:
    rain-alias: true

rain-alias: true also puts rain on the PATH, so steps that call rain work without changes. When your steps call cfnrain, remove the input.

User agent¶

AWS sees the user agent cfnrain/<version>, not Rain/<version>. If you filter CloudTrail events or write IAM conditions on the user agent, update them.

Role session name¶

When cfnrain assumes a role from your AWS profile, the role session name is cfnrain-<version>, not Rain-<version>. If a role trust policy only allows session names that match Rain-*, add cfnrain-*:

"Condition": {
  "StringLike": {
    "sts:RoleSessionName": ["Rain-*", "cfnrain-*"]
  }
}

No analytics metadata¶

Rain added a Metadata.AWSToolsMetrics.Rain block to every packaged template. cfnrain does not. The --no-analytics flag is still accepted, and has no effect. If you compare packaged templates from Rain and cfnrain, expect this block to be the difference.

Documentation¶

The Rain documentation at aws-cloudformation.github.io/rain is frozen. This site replaces it. Some things in the old documentation are wrong:

• On deploy, -x is --no-exec, not --experimental. See Experimental features.
• The Modules section does not need --experimental. Only !Rain::Module and bucket metadata do.
• !Rain::S3 takes Format: URI, not Uri. See S3 and S3Http.
• The ForEach placeholders are $Identifier and $Index. There is no $MapValue. See ForEach.
• !Rain::Module does not need a ModuleExtension resource or Metadata.Extends.
• Packaged resources get no SourceMap metadata.
• !Rain::S3 has no VersionProperty option.
• diff, merge and tree do not read Pkl files.

For behavior that is still wrong in the code, see Known issues.