Home

Awesome

Unit tests Mentioned in Awesome CloudFormation

Rain

Rain is what happens when you have a lot of CloudFormation

Rain is also a command line tool for working with AWS CloudFormation templates and stacks.

Make it Rain

Discord

Join us on Discord to discuss rain and all things CloudFormation! Connect and interact with CloudFormation developers and experts, find channels to discuss rain, the CloudFormation registry, StackSets, cfn-lint, Guard and more:

Join our Discord

Key features

Note that in order to use experimental commands, you have to add --experimental or -x as an argument.

Getting started

If you have homebrew installed, brew install rain

Or you can download the appropriate binary for your system from the releases page.

Or if you're a Gopher, you can go install github.com/aws-cloudformation/rain/cmd/rain@latest

Usage:
  rain [command]

Stack commands:
  cat         Get the CloudFormation template from a running stack
  cc          Interact with templates using Cloud Control API instead of CloudFormation
  deploy      Deploy a CloudFormation stack or changeset from a local template
  logs        Show the event log for the named stack
  ls          List running CloudFormation stacks or changesets
  rm          Delete a CloudFormation stack or changeset
  stackset    This command manipulates stack sets.
  watch       Display an updating view of a CloudFormation stack

Template commands:
  bootstrap   Creates the artifacts bucket
  build       Create CloudFormation templates
  diff        Compare CloudFormation templates
  fmt         Format CloudFormation templates
  forecast    Predict deployment failures
  merge       Merge two or more CloudFormation templates
  module      Interact with Rain modules in CodeArtifact
  pkg         Package local artifacts into a template
  tree        Find dependencies of Resources and Outputs in a local template

Other Commands:
  console     Login to the AWS console
  help        Help about any command
  info        Show your current configuration

You can find shell completion scripts in docs/bash_completion.sh and docs/zsh_completion.sh.

Contributing

Rain is written in Go and uses the AWS SDK for Go v2.

To contribute a change to Rain, fork this repository, make your changes, and submit a Pull Request.

Go Generate

The README.md, documentation in docs/, the auto completion scripts and a copy of the cloudformation specification in cft/spec/cfn.go are generated through go generate.

License

Rain is licensed under the Apache 2.0 License.

Example Usage

Packaging

The rain pkg command can be used as a replacement for the aws cloudformation package CLI command. When packaging a template, rain looks for specific directives to appear in resources.

Embed

The !Rain::Embed directive simply inserts the contents of a file into the template as a string.

The template:

Resources:
  Test:
    Type: AWS::CloudFormation::WaitConditionHandle
    Metadata:
      Comment: !Rain::Embed embed.txt

The contents of embed.txt, which is in the same directory as the template:

This is a test

The resulting packaged template:

Resources:
  Test:
    Type: AWS::CloudFormation::WaitConditionHandle
    Metadata:
      Comment: This is a test

Include

The !Rain::Include directive parses a YAML or JSON file and inserts the object into the template.

The template:

Resources:
  Test:
    !Rain::Include include-file.yaml

The file to be included:

Type: AWS::S3::Bucket
Properties:
  BucketName: test

The resulting packaged template:

Resources:
  Test:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: test

Env

The !Rain::Env directive reads environment variables and inserts them into the template as strings.

The template:

Resources:
  Test:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Rain::Env BUCKET_NAME

The resulting packaged template, if you have exported an environment variable named BUCKET_NAME with value abc:

Resources:
  Test:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: abc

S3Http

The !Rain::S3Http directive uploads a file or directory to S3 and inserts the HTTPS URL into the template as a string.

The template:

Resources:
  Test:
    Type: A::B::C
    Properties:
      TheS3URL: !Rain::S3Http s3http.txt

If you have a file called s3http.txt in the same directory as the template, rain will use your current default profile to upload the file to the artifact bucket that rain creates as a part of bootstrapping. If the path provided is a directory and not a file, the directory will be zipped first.

Resources:
  Test:
    Type: A::B::C
    Properties:
      TheS3URL: https://rain-artifacts-012345678912-us-east-1.s3.us-east-1.amazonaws.com/a84b588aa54068ed4b027b6e06e5e0bb283f83cf0d5a6720002d36af2225dfc3

S3

The !Rain::S3 directive is basically the same as S3Http, but it inserts the S3 URI instead of an HTTPS URL.

The template:

Resources:
  Test:
    Type: A::B::C
    Properties:
      TheS3URI: !Rain::S3 s3.txt

If you have a file called s3.txt in the same directory as the template, rain will use your current default profile to upload the file to the artifact bucket that rain creates as a part of bootstrapping. If the path provided is a directory and not a file, the directory will be zipped first.

Resources:
  Test:
    Type: A::B::C
    Properties:
      TheS3URI: s3://rain-artifacts-755952356119-us-east-1/a84b588aa54068ed4b027b6e06e5e0bb283f83cf0d5a6720002d36af2225dfc3 

If instead of providing a path to a file, you supply an object with properties, you can exercise more control over how the object is uploaded to S3. The following example is a common pattern for uploading Lambda function code. The optional Run property is a local script that you want Rain to run before uploading the content at Path.

Resources:
  MyFunction:
    Type: AWS::Lambda::Function
    Properties:
      Code: !Rain::S3 
        Path: lambda-dist
        Zip: true
        BucketProperty: S3Bucket
        KeyProperty: S3Key
        Run: buildscript.sh

The packaged template:

Resources:
  MyFunction:
    Type: AWS::Lambda::Function
    Properties:
      Code:
        S3Bucket: rain-artifacts-012345678912-us-east-1
        S3Key: 1b4844dacc843f09941c11c94f80981d3be8ae7578952c71e875ef7add37b1a7

Metadata commands

You can add a metadata section to an AWS::S3::Bucket resource to take additional actions during deployment, such as running pre and post build scripts, uploading content to the bucket after stack deployment completes, and emptying the contents of the bucket when the stack is deleted.

Resources:
  Bucket:
    Type: AWS::S3::Bucket
    Metadata:
      Rain:
        EmptyOnDelete: true
        Content: site/dist
        Version: 2
        DistributionLogicalId: SiteDistribution
        RunBefore: 
          Command: buildsite.sh
          Args:
          - ALiteralArgument
        RunAfter:
          Command: buildsite.sh
          Args:
            - Rain::OutputValue AStackOutputKey

EmptyOnDelete: If true, the bucket's contents, including all versions, will be deleted so that the bucket itself can be deleted. This can be useful for development environments, but be careful about using it in production!

Version: Rain doesn't do anything with this, but incrementing the number can force the stack to deploy if there have been no infrastructure changes to the stack.

RunBefore: Rain will run this command before the stack deploys. Useful to run your website build script before bothering to deploy, to make sure it builds successfully.

RunAfter: Rain will run this command after deployment, and it is capable of doing stack output lookups to provide arguments to the script. This is useful if you deployed a resource like an API Gateway and need to know the stage URL to plug in to your website configuration. Use Rain::OutputValue OutputKey to pass one of the arguments to the script.

DistributionLogicalId: Supply the logical id of a CloudFront distribution to invalidate all files in it after the content upload completes.

See test/webapp/README.md for a complete example of using these commands with Rain modules.

Module

The !Rain::Module directive is an experimental feature that allows you to create local modules of reuseable code that can be inserted into templates. Rain modules are basically just CloudFormation templates, with a Parameters section that corresponds to the Properties that a consumer will set when using the module. Rain modules are very flexible, since you can override any of the resource properties from the parent template.

In order to use this feature, you have to acknowledge that it's experimental by adding a flag on the command line:

rain pkg -x my-template.yaml

Keep in mind that with new versions of rain, this functionality could change, so use caution if you decide to use this feature for production applications. The rain pkg command does not actually deploy any resources if the template does not upload any objects to S3, so you always have a chance to review the packaged template. It's recommended to run linters and scanners on the packaged template, rather than a pre-processed template that makes use of these advanced directives.

A sample module:

Description: This module creates a compliant bucket, along with a second bucket to store access logs

Parameters:
  LogBucketName:
    Type: String

Resources:
  Bucket:
    Type: AWS::S3::Bucket
    Properties:
      LoggingConfiguration:
        DestinationBucketName: !Ref LogBucket
      BucketEncryption:
        ServerSideEncryptionConfiguration:
          - ServerSideEncryptionByDefault:
             SSEAlgorithm: AES256
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true
      Tags:
        - Key: test-tag
          Value: test-value1
  
  LogBucket:
    Type: AWS::S3::Bucket
    DeletionPolicy: Retain
    Properties:
      BucketName: !Ref LogBucketName
      BucketEncryption:
        ServerSideEncryptionConfiguration:
          - ServerSideEncryptionByDefault:
              SSEAlgorithm: AES256
      VersioningConfiguration:
        Status: Enabled
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true

Note that we defined a single parameter to the module called LogBucketName. In the module, we create an additional bucket to hold logs, and we apply the name to that bucket. In the template that uses the module, we specify that name as a property. This shows how we have extended the basic behavior of a bucket to add something new.

A template that uses the module (in this example we reference a local module, but it's also possible to reference a URL):

Resources:
  ModuleExample:
    Type: !Rain::Module "./bucket-module.yaml"
    Properties:
      LogBucketName: test-module-log-bucket
    Overrides:
      Bucket:
        UpdateReplacePolicy: Delete
        Properties:
          VersioningConfiguration:
            Status: Enabled
          Tags:
            - Key: test-tag
              Value: test-value2

Note that in addition to supplying the expected LogBucketName property, we have also decided to override a few of the properties on the underlying AWS::S3::Bucket resource, which shows the flexibility of the inheritance model.

The resulting template after running rain pkg:

Resources:
  ModuleExampleBucket:
    Type: AWS::S3::Bucket
    Properties:
      LoggingConfiguration:
        DestinationBucketName: !Ref ModuleExampleLogBucket
      BucketEncryption:
        ServerSideEncryptionConfiguration:
          - ServerSideEncryptionByDefault:
              SSEAlgorithm: AES256
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true
      Tags:
        - Key: test-tag
          Value: test-value2
      VersioningConfiguration:
        Status: Enabled

  ModuleExampleLogBucket:
    DeletionPolicy: Retain
    Type: AWS::S3::Bucket
    Properties:
      BucketName: test-module-log-bucket
      BucketEncryption:
        ServerSideEncryptionConfiguration:
          - ServerSideEncryptionByDefault:
              SSEAlgorithm: AES256
      VersioningConfiguration:
        Status: Enabled
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true

Publish modules to CodeArtifact

Rain integrates with AWS CodeArtifact to enable an experience similar to npm publish and install. A directory that includes Rain module YAML files can be packaged up with rain module publish, and then the directory can be installed by developers with rain module install.

Module packaging

You can reference a collection of Rain modules with an alias inside of the parent template. Add a Rain section to the template to configure the package alias. There's nothing special about a package, it's just an alias to a directory or a zip file. A zip file can also have a sha256 hash associated with it to verify the contents.

Rain:
  Packages:
    aws:
      Location: https://github.com/aws-cloudformation/rain/modules
    xyz:
      Location: ./my-modules
    abc:
      Location: https://github.com/aws-cloudformation/rain/releases/tag/m0.1.0/modules.zip
      Hash: https://github.com/aws-cloudformation/rain/releases/tag/m0.1.0/modules.sha256

Resources:
  Foo:
    Type: !Rain::Module aws/foo.yaml

  Bar:
    Type: !Rain::Module xyz/bar.yaml

  Baz:
    Type: $abc/baz.yaml
    # Shorthand for !Rain::Module abc/baz.yaml

A module package is published and released from this repository separately from the Rain binary release. This allows the package to be referenced by version numbers using tags, such as m0.1.0 as shown in the example above. The major version number will be incremented if any breaking changes are introduced to the modules. The available modules in the release package are listed below.

Treat these modules as samples to be used as a proof-of-concept for building your own module packages.

simple-vpc.yaml

A VPC with just two availability zones. This module is useful for POCs and simple projects.

encrypted-bucket.yaml

A simple bucket with encryption enabled and public access blocked

compliant-bucket.yaml

A bucket, plus extra buckets for access logs and replication and a bucket policy that should pass most typical compliance checks.

bucket-policy.yaml

A bucket policy that denies requests not made with TLS.

load-balancer.yaml

An ELBv2 load balancer

static-site.yaml

An S3 bucket and a CloudFront distribution to host content for a web site

cognito.yaml

A Cognito User Pool and associated resources

rest-api.yaml

An API Gateway REST API

api-resource.yaml

A Lambda function and associated API Gateway resources

IfParam and IfNotParam

Inside a module, you can add a Metadata attribute to show or hide resources, depending on whether the parent template sets a parameter value. This is similar to the Conditional section in a template, but somewhat simpler, and it only works in modules.

Resources:
  Bucket:
    Type: AWS::S3::Bucket
    Metadata:
      Rain:
        IfParam: Foo

If the parent template does not set a value for the Foo property, the module will omit the resource. The opposite is true for IfNotParam.

IfParam can be useful to make flexible modules that can optionally do things like configure permissions for related resources, like allowing access to a bucket or table.

IfNotParam is useful if you have pre-created a resource and you don't want the module to create it for you.

Gantt Chart

Output a chart to an HTML file that you can view with a browser to look at how long stack operations take for each resource.

rain log --chart CDKToolkit > ~/Desktop/chart.html

<img src="./docs/chart.png" />

Pkl

You can now write CloudFormation templates in Apple's new configuration language, Pkl. Rain commands that accept input as JSON or YAML now also accept files with the .pkl extension. We host a Pkl package in a separate repo that is generated based on the CloudFormation registry. This package has classes that can be imported for each registry resource type, in addition to higher level patterns. This allows you to write a type-safe template and create your own client-side modules, in a way that is similar to CDK, but with declarative code.

Example Pkl template:

amends "package://github.com/aws-cloudformation/cloudformation-pkl/releases/download/cloudformation@0.1.1/cloudformation@0.1.1#/template.pkl"
import "package://github.com/aws-cloudformation/cloudformation-pkl/releases/download/cloudformation@0.1.1/cloudformation@0.1.1#/cloudformation.pkl" as cfn
import "package://github.com/aws-cloudformation/cloudformation-pkl/releases/download/cloudformation@0.1.1/cloudformation@0.1.1#/aws/s3/bucket.pkl" as bucket

Description = "Create a bucket"

Parameters {
    ["Name"] {
        Type = "String"
        Default = "baz"
    }
}

Resources {
    ["MyBucket"] = new bucket.Bucket {
        BucketName = cfn.Ref("Name")
    }
}

Constants

You can put constants into the Rain section in the template and then refer to those constants later in the template. Constants can be strings or entire objects (but only strings can be used later in Sub functions). Use the !Rain::Constant directive to refer to a constant in the template. For strings, you can add constants to !Sub strings with the ${Rain::ConstantName} pseudo-parameter. Constants can contain previosuly declared constants in Sub strings using the same format. The Rain section gets removed during packaging.

Parameters:
  Prefix:
    Type: String

Rain:
  Constants:
    Test1: ezbeard-rain-test-constants
    Test2: !Sub ${Prefix}-${Rain::Test1}-SubTest

Resources:
  Bucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Rain::Constant Test1

  Bucket2:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Rain::Constant Test2

  Bucket3:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Sub "pre-${Prefix}-${Rain::Test1}-suffix" 

Run rain pkg on that template to produce the following output:

Parameters:
  Prefix:
    Type: String

Resources:
  Bucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: ezbeard-rain-test-constants

  Bucket2:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Sub ${Prefix}-ezbeard-rain-test-constants-SubTest

  Bucket3:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Sub pre-${Prefix}-ezbeard-rain-test-constants-suffix

Other CloudFormation tools

Are we missing an excellent tool? Let us know via a GitHub issue.