repository·main·Indexed 21 days ago
https://github.com/aws-cloudformation/rainA command line tool for working with AWS CloudFormation templates and stacks. Rain provides interactive deployments, template formatting, generative AI-powered template building, and experimental features like Cloud Control API (CCAPI) deployments and deployment failure prediction via the `rain forecast` command. Note: This project is deprecated and no longer actively maintained.
Because CCAPI deployments do not use CloudFormation stacks, Rain maintains a local state file in the rain-artifacts bucket to track resources. This allows for features like drift detection and manual state remediation.
The state file is a YAML file mirroring your CloudFormation template with an added State section:
State:
LastWriteTime: ...
ResourceModels:
MyResource:
Identifier:
Model:
...Drift detection compares the actual properties of the deployed AWS resources against the properties stored in the Rain state file. When you run rain cc deploy, Rain also checks for drift and allows you to resolve it before proceeding with updates. This is useful for remediating complex drift situations or unexpected deployment failures.
Rain modules provide multi-file support for CloudFormation, allowing you to compose templates from reusable components. Modules are defined in a Modules section and can be local files or HTTPS URLs.
Parameters, Resources, Conditions, and Outputs. They can be nested, though circular dependencies are prohibited.Properties. The Overrides attribute allows you to modify the internal structure of a module (e.g., changing a resource's metadata) if you know its internal logical IDs.Constants section in both modules and parent templates. Constants are processed before modules and can be referenced using Const::name in !Sub strings or !Ref Const::name for objects.ForEach attribute in the Modules configuration, which uses $Identifier and $Index variables to iterate over a list.!GetAtt <ModuleName>.<OutputName> or !Ref <ModuleName>.IfParam or IfNotParam in the Metadata section to show or hide resources based on whether a specific parameter is set in the parent template.Note: To use modules, you must use the --experimental flag with rain pkg.
# Example of importing a module with Overrides and Outputs
Modules:
Content:
Source: ./module.yaml
Properties:
Name: foo
Overrides:
Bucket:
Metadata:
OverrideMe: def
Outputs:
TheArn:
Value: !GetAtt Content.BucketArnIf you have a collection of modules bundled in a zip file, you can reference them using a Packages section in your template. This allows you to manage multiple modules under a single alias.
Packages section using a local path or URL.$ prefix followed by the package alias.Packages:
abc:
Source: ./package.zip
def:
Source: https://example.com/packages/package.zip
Modules:
Foo:
Source: $abc/foo.yaml
Bar:
Source: $def/a/b/bar.yamlThe rain cc command allows you to interact with templates using the AWS Cloud Control API instead of the standard CloudFormation API.
Warning: This feature is experimental and likely to be unstable. You must pass the --experimental (or -x) flag to use any cc subcommands.
When using rain pkg, you can use special directives within your CloudFormation templates to dynamically inject content:
!Rain::Embed <path>: Embeds the file contents at <path> as a string.!Rain::Include <path>: Reads the file at <path> as YAML/JSON and inserts the resulting object into the template.!Rain::Env <name>: Reads the environment variable <name> and inserts its value as a string.!Rain::S3Http <path>: Uploads <path> (zipping if it's a directory) to S3 and embeds the S3 HTTP URL as a string.!Rain::S3 <path>: Uploads <path> (zipping if it's a directory) to S3 and embeds the S3 URI as a string.!Rain::S3 <object>: Uploads an object to S3 with advanced configuration. Use this to return an object containing metadata instead of just a string. Supported properties:Path: File or directory to upload.Zip: true|false (forces zipping even if it's a single file).BucketProperty: <bucket> (name of the property in the resulting object for the bucket).KeyProperty: <key> (name of the property in the resulting object for the key).Format: Uri|Http (defaults to Uri). Note: Do not use Format if BucketProperty or KeyProperty are provided.!Rain::Module <url>: (Experimental) Supplies a URL to a rain module. The module must contain a resource named ModuleExtension with a Metadata entry Extends specifying the type to extend. Requires the --experimental flag.The rain stackset command serves as a parent command for manipulating AWS CloudFormation StackSets. It does not perform any actions on its own; you must append a specific sub-command to perform a task.
Available sub-commands include:
rain stackset deploy: Deploy a CloudFormation stack set from a local template.rain stackset ls: List CloudFormation stack sets in a given region.rain stackset rm: Delete a CloudFormation stack set and/or its instances.You can define reusable values in a top-level Rain section within your template. This allows you to centralize strings or objects and reference them throughout your resources, reducing duplication and making templates easier to maintain.
!Rain::Constant directive to inject a constant value directly into a property.!Sub strings: Use the ${Rain::ConstantName} pseudo-parameter syntax to embed constants within a !Sub function. This works for both simple strings and constants that themselves contain other constants.Rain section is a build-time construct. When you run rain pkg, the Rain section is removed, and all references are replaced with their actual values, resulting in a standard CloudFormation template.Defining constants in a Rain block and using them via both !Rain::Constant and !Sub:
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"The rain cc deploy command allows you to create or update resources directly using the Cloud Control API from a local template file.
Warning: This feature is marked as Experimental. You must explicitly acknowledge this by passing the --experimental or -x flag. Because it is experimental, the behavior may be unstable.
To use this command, provide the path to your template file and a name for the deployment.
rain cc deploy <template> <name>
# Example usage with experimental flag:
rain cc deploy my-template.yaml my-stack-name -xUse the rain module publish command to upload a directory containing Rain modules to an AWS CodeArtifact repository. This allows you to share and version your modules centrally.
To publish a module, specify the module name and use flags to define the version, the local path of the module files, and the target AWS CodeArtifact repository and domain.
rain module publish <name> [flags]The rain watch command provides a real-time, updating view of a CloudFormation stack's status. This is particularly useful for monitoring the progress of a deployment that was initiated outside of Rain (e.g., via the AWS CLI or Console) to see updates as they happen.
rain watch <stack>Use the rain stackset deploy command to create or update a CloudFormation stack set from a local template file.
Key Behaviors:
rain uses the template filename (minus its extension).rain assumes you want to add a new instance to an existing stack set.rain will package it first.rain attempts to create an S3 bucket for packaged artifacts using the format rain-artifacts-<AWS account id>-<AWS region> unless a specific bucket is provided via --s3-bucket.rain stackset deploy <template> [stackset] [flags]