iidy (Is it done yet?) -- a CloudFormation CLI tool

iidy improves the developer experience with CloudFormation and CloudFormation templates.

• It provides immediate, readable feedback about what CloudFormation is doing and any errors it encounters.
• It is simple to learn, understand, and use. There are fewer moving parts and its commands map directly to CloudFormation's.
• It has simple, reliable support for AWS profiles.
• It supports the full range of CloudFormation operations, including changesets without requiring any code beyond what is required to create a stack.
• It does some template validation, guards against common issues, and will be extended over time to validate our best practices and security policies.
• It provides seamless integration with AWS Parameter Store.
• It includes an optional YAML pre-processor which allows CloudFormation templates to be abstracted and simplified in ways not possible with vanilla CloudFormation templates. The pre-processor language supports importing data from a variety of external sources and this allows a better separation of concerns than is possible with stock CloudFormation without resorting to Lambda-backed custom resources. See the pre-processor documentation below for more details.
• It has bash command completion support.

Table of Contents

• Pronunciation
• Demo
• Installation
  • Binary Install for macOS via Homebrew
  • Binary Installation on Other Platforms
  • Installation from Source
  • Docker Image
• Usage
  • Help
  • The Args File
    • Required Properties
    • Optional Properties
    • Example
    • Importing Data
    • Implicit Variables
    • Defining Variables
  • AWS IAM Settings
  • Environment Variables
• Examples
• Development
• License
• Releasing
• Converting Existing CloudFormation Stacks to iidy
• Custom Resource Templates
• Using Parameter Store
• Working with Non-CloudFormation YAML
• Working with StackSets
• YAML Processing
• Extracting Data From Templates

Pronunciation

iidy is pronounced "eye-dee", like the audience's response to Cab Calloway in Minnie the Moocher.

Demo

Installation

iidy is distributed as a self-contained executable (via pkg).

Binary Install for macOS via Homebrew

Use Unbounce's custom Homebrew Tap to install iidy. This is the preferred method for macOS.

brew tap unbounce/homebrew-taps
brew update
brew install iidy

Binary Installation on Other Platforms

# Grab the appropriate binary from the releases page.
wget https://github.com/unbounce/iidy/releases/download/v1.6.7/iidy-linux-amd64.zip
# or wget https://github.com/unbounce/iidy/releases/download/v1.6.7/iidy-macos-amd64.zip
unzip iidy*.zip
chmod +x iidy
mv iidy /usr/local/bin/ # or somewhere more appropriate

Installation from Source

Counter-intuitively, this requires more disk space than the binary install. You need Node 7+ and npm 4+ installed.

git clone [email protected]:unbounce/iidy.git
cd iidy
npm install && npm run build # to compile our source first
ln -s $(pwd)/bin/iidy /usr/local/bin/
# or npm install -g .

Usage

Help

$ iidy help
iidy - CloudFormation with Confidence                    An acronym for "Is it done yet?"

Commands:
  iidy create-stack     <argsfile>                            create a cfn stack based on stack-args.yaml
  iidy update-stack     <argsfile>                            update a cfn stack based on stack-args.yaml
  iidy create-or-update <argsfile>                            create or update a cfn stack based on stack-args.yaml
  iidy estimate-cost    <argsfile>                            estimate aws costs based on stack-args.yaml

  iidy create-changeset           <argsfile> [changesetName]  create a cfn changeset based on stack-args.yaml
  iidy exec-changeset             <argsfile> <changesetName>  execute a cfn changeset based on stack-args.yaml

  iidy describe-stack      <stackname>                        describe a stack
  iidy watch-stack         <stackname>                        watch a stack that is already being created or updated
  iidy describe-stack-drift <stackname>                       describe stack drift
  iidy delete-stack        <stackname>                        delete a stack (after confirmation)
  iidy get-stack-template  <stackname>                        download the template of a live stack
  iidy get-stack-instances <stackname>                        list the ec2 instances of a live stack
  iidy list-stacks                                            list all stacks within a region

  iidy param                                                  sub commands for working with AWS SSM Parameter Store

  iidy template-approval                                      sub commands for template approval

  iidy render <template>                                      pre-process and render yaml template
  iidy get-import <import>                                    retrieve and print an $import value directly
  iidy demo   <demoscript>                                    run a demo script
  iidy lint-template   <argsfile>                             lint a CloudFormation template
  iidy convert-stack-to-iidy <stackname> <outputDir>          create an iidy project directory from an existing CFN stack
  iidy init-stack-args                                        initialize stack-args.yaml and cfn-template.yaml

  iidy completion                                             generate bash completion script. To use: "source <(iidy completion)"

AWS Options:
  --client-request-token  a unique, case-sensitive string of up to 64 ASCII characters used to ensure idempotent retries.         [string] [default: null]
  --region                AWS region. Can also be set via --environment & stack-args.yaml:Region.                                 [string] [default: null]
  --profile               AWS profile. Can also be set via --environment & stack-args.yaml:Profile. Use --profile=no-profile to override values in
                          stack-args.yaml and use AWS_* env vars.                                                                 [string] [default: null]
  --assume-role-arn       AWS role. Can also be set via --environment & stack-args.yaml:AssumeRoleArn. This is mutually exclusive with --profile. Use
                          --assume-role-arn=no-role to override values in stack-args.yaml and use AWS_* env vars.                 [string] [default: null]

Options:
  --environment, -e  used to load environment based settings: AWS Profile, Region, etc.                                  [string] [default: "development"]
  --debug            log debug information to stderr.                                                                           [boolean] [default: false]
  --log-full-error   log full error information to stderr.                                                                      [boolean] [default: false]
  -v, --version      show version information                                                                                                    [boolean]
  -h, --help         show help                                                                                                                   [boolean]

Status Codes:
  Success (0)       Command successfully completed
  Error (1)         An error was encountered while executing command
  Cancelled (130)   User responded 'No' to iidy prompt or interrupt (CTRL-C) was received

The Args File

Metadata for a CloudFormation stack is kept in a file called the "argsfile" (typically called stack-args.yaml). This file is a parameter for commands like iidy create-or-update or iidy create-changeset and is the main source of data for creating or updating a CloudFormation stack.

Required Properties

Optional Properties

Example

StackName: my-stack

Template: cfn-template.yaml

Tags:
  project: iidy-docs

Parameters:
  Param1: value1
  Param2: value2

Capabilities:
  - CAPABILITY_IAM
  - CAPABILITY_NAMED_IAM

TimeoutInMinutes: 10

OnFailure: DELETE

StackPolicy: policy.json

CommandsBefore:
  # a list of shell commands to run prior the cfn stack operation
  # /bin/bash is used if found.
  # handlebars templates in the command strings are preprocessed prior to execution.

  # E.g.
  - make build

Importing Data

Data can be imported into the stack args file using the $imports: block.

iidy imports can be accessed using the !$ YAML tag or using Handlebars templating. !$ will insert the data assigned to that variable. Handlebars templated strings can be used to interpolate values into a string.

iidy parses .yaml or .json imports and makes them available as a map. It uses either the file extension or the mime-type of remote files to detect these file types.

$imports:
  params: ssm-path:/my-services/config

Parameters:
  Timeout: $! params.Timeout

Tags:
  StackName: 'my-service'

Implicit Variables

Some data is automatically set by iidy.

StackName: 'my-service-{{ iidy.environment }}'

Defining Variables

Local variables with file can be specified using the $defs block.

$defs:
  serviceName: my-service

StackName: '{{ serviceName }}-{{ iidy.environment }}'

AWS IAM Settings

iidy supports loading AWS IAM credentials/profiles from a) the cli options shown above, b) Region and Profile or AssumeRoleArn settings in stack-args.yaml, or c) the standard AWS environment variables. You will also need the correct level of IAM permissions for iidy to perform CloudFormation API calls. This information can be provided in a number of different ways (ordered from highest to lowest precedence):

• CLI options (see above)
• AWS_REGION and AWS_PROFILE environment variables
• standard AWS environment variables
• Region and Profile or AssumeRoleArn in args file

These credentials are used to interact with the CloudFormation API and to perform and AWS-related imports.

If your profile requires an MFA token, iidy will prompt for it.

? MFA token for arn:aws:iam::001234567890:mfa/example.user: ____

If you've assumed a profile prior to running iidy and want to it to ignore what's specified as Profile in stack-args.yaml and instead use AWS_* environment variables, set the CLI option --profile no-profile.

Environment Variables

Any parameter used by iidy can be set using IIDY_{{argname}}. An example of this would be changing the default environment from development to production.

export IIDY_ENVIRONMENT=production

Examples

See the examples/ directory.

Development

iidy is coded in Typescript and compiles to ES2015 JavaScript using commonjs modules (what Node uses). See the Makefile and the script commands in package.json for details about the build process.

Please format all files with tsfmt and remove extra whitespace before submitting a PR.

Releasing

• Run npm version minor|patch
• Run git push --tags
• Run make prepare_releaseto generate the release artifacts for upload
• Create a GitHub release following the template of previous releases
• Update the homebrew forumula (double check the sha)

Global Configuration

Some iidy features can be configured globally via SSM Parameter Store configurations.

Note that SSM Parameter Store values are isolated to the AWS Account and Region they are set in.

License

MIT.