Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (cim) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Cloud Infrastructure Manager (CIM)

CIM takes the pain out of Infrastructure as Code and CloudFormation!

The importance of IaC has increased, due to the rise in popularity of cloud functions, event driven architectures, and the number of AWS services offered.

Logic has slowly been pulled out of our applications and into cloud service providers. This is amazing and allows our applications to scale and be cost effective but it changes how they look and feel

Infrastructure as Code is just as important, or more important, than the code itself. Implementing IaC at the onset of a new project is a must. But don't worry, CIM is here to help.

CIM makes it easy to create, update, and delete stacks
CIM allows you to create nested stacks
CIM helps organize stack input parameters
CIM provides templates to help you get started
CIM has support for Lambda functions
CIM has an extensible Plugin framework

Easily create your stack, build and deploy your code, and view your logs.

Table of contents:

Usage
Setup
Commands
Config (_cim.yml)
Templates
Plugin Framework

Usage

# Install CIM
npm install cim -g

# See the available templates
cim templates

# Create your first stack using the lambda template
mkdir app
cd app
cim create --template=lambda-node

# Deploy your stack
cim stack-up

# Deploy your code
cim lambda-deploy

# View logs
cim lambda-logs --alias=hello --tail=true

# Delete you stack
cim stack-delete

Setup

Prerequisites

Install CIM

Use npm to install CIM globally.

npm install cim -g

Commands

create
templates
stack-up
stack-show
stack-delete
lambda-deploy
lambda-logs
help

create

Create a new CIM package based on a give template.

At minimum a CIM package contains the following files:

Usage

mkdir app
cd app
cim create --template=<template>

Where <template> is equal to one of the templates from cim templates.

For examples see the templates.

Options

--template: The name of a template.
- ex. --template=lambda-node
--dir: (optional) The directory where you wish the new package to be.
- ex. --dir=/app

templates

View all the available templates. Templates are used in the create command.

Usage

cim templates

stack-up

Create or update your stack. Sends a create or update command to CloudFormation using the properties defined in your _cim.yml.

Usage

cim stack-up {OPTIONS}

Options

--dir: (optional) The directory to run this command in. Defaults to the current directory.
- ex. --dir=/app
--recursive: (optional) Recursively search for nested stacks to create or update. Any nested directory with a valid _cim.yml file. Default is 'false'.
- ex. --recursive=true
--stage: (optional) Create or update the stack(s) using the give stage.
- ex. --stage=prod
--profile: (optional) Your AWS credentials profile.
- ex. --profile=prod_aws_account

stack-show

Show all the details about your CloudFormation stack. Helper method to see the status of your stack.

Usage

cim stack-show {OPTIONS}

Options

--dir: (optional) The directory to run this command in. Defaults to the current directory.
- ex. --dir=/app
--recursive: (optional) Recursively search for nested stacks to create or update. Any nested directory with a valid _cim.yml file. Default is 'false'.
- ex. --recursive=true
--stage: (optional) Create or update the stack(s) using the give stage.
- ex. --stage=prod
--profile: (optional) Your AWS credentials profile.
- ex. --profile=prod_aws_account

stack-delete

Delete your stack. Sends a delete command to CloudFormation using the properties defined in your _cim.yml.

Usage

cim stack-delete {OPTIONS}

Options

--dir: (optional) The directory to run this command in. Defaults to the current directory.
- ex. --dir=/app
--recursive: (optional) Recursively search for nested stacks to create or update. Any nested directory with a valid _cim.yml file. Default is 'false'.
- ex. --recursive=true
--stage: (optional) Create or update the stack(s) using the give stage.
- ex. --stage=prod
--profile: (optional) Your AWS credentials profile.
- ex. --profile=prod_aws_account

lambda-deploy

Deploy you Lambda functions.

Usage

cim lambda-deploy {OPTIONS}

Options

--dir: (optional) The directory to run this command in. Defaults to the current directory.
- ex. --dir=/app
--recursive: (optional) Recursively search for nested stacks to deploy. Any nested directory with a valid _cim.yml file. Default is 'false'.
- ex. --recursive=true
--alias: (optional) Restrict to a single Lambda function by its alias.
- ex. --alias=function1
--stage: (optional) Create or update the stack(s) using the give stage.
- ex. --stage=prod
--profile: (optional) Your AWS credentials profile.
- ex. --profile=prod_aws_account

lambda-logs

Show the CloudWatch Logs for a single Lambda function.

Usage

cim lambda-logs {OPTIONS}

Options

--dir: (optional) The directory to run this command in. Defaults to the current directory.
- ex. --dir=/app
--alias: Restrict to a single Lambda function by its alias.
- ex. --alias=function1
--tail: (optional) Tail the logs. Default is false.
- ex. --tail=true
--startTime: (optional) Start fetching logs from this time. Time in minutes. Ex. '30s' minutes ago. Default is '30s'.
- ex. --startTime=30s
--internal: (optional) Interval, in milliseconds, between calls to CloudWatch Logs when using 'tail'. Default is 5000.
- ex. --internal=5000
--filterPattern: (optional) CloudWatch Logs filter pattern.
- ex. --filterPattern=ERROR
--stage: (optional) Create or update the stack(s) using the give stage.
- ex. --stage=prod
--profile: (optional) Your AWS credentials profile.
- ex. --profile=prod_aws_account

help

Usage

View all the available commands.

cim help

View a single command.

cim <command> --help

_cim.yml

The _cim.yml file is where details about your stack are stored. Lets take a look at base template.

Basic

version: 0.1
stack:
  name: 'base'
  template:
    file: 'cloudformation.yml'
    bucket: 'base-templates'

The stack name will be used when creating your CloudFormation stack. Shen you view all your CloudFormation stacks through the AWS console, this will be the name.
A lot of the AWS resources created within this stack will also have this name as a prefix within their name.

The template defines the local CloudFormation file to use for this stack. When calling CloudFormation the CloudFormation file needs to be on S3. The S3 bucket is where CIM stores the CloudFormation file prior to calling CloudFormation.

Parent stacks

In most cases you will have multiple stacks, and these stacks will be nested. For example, lets say you have a base stack for your VPC and other shared resources, and then a stack for your api application. Your project structure might look like:

/iac
    /base
        - _cim.yml
        - cloudformation.yml
    /api-app
        - _cim.yml
        - cloudformation.yml

Through the use of the parents field you can reference and reuse items in a parent stack. In our api app example we reuse the parent stack name and template bucket.

version: 0.1
stack:
  name: '${stack.parents.base.stack.name}-api'
  template:
    file: 'cloudformation.yml'
    bucket: '${stack.parents.base.stack.template.bucket}'
  parents:
    base: '../base'

You can reference multiple parents by key.

Parameters

The parameters field is used to define the input parameter values sent to CloudFormation during a stack-up command.

Continuing our example above lets say we also want to pass in the base stack name as an input parameter for cross stack parameter referencing.

version: 0.1
stack:
  name: '${stack.parents.base.stack.name}-api'
  template:
    file: 'cloudformation.yml'
    bucket: '${stack.parents.base.stack.template.bucket}'
  parents:
    base: '../base'
  parameters:
    BaseStackName: '${stack.parents.base.stack.name}'

Capabilities

If you have IAM resources, you can specify either capability. If you have IAM resources with custom names, you must specify CAPABILITY_NAMED_IAM. If you don't specify this parameter, this action returns an InsufficientCapabilities error.

Valid Values: CAPABILITY_IAM | CAPABILITY_NAMED_IAM Continuing our example above lets say we also want to pass in the base stack name as an input parameter for cross stack parameter referencing.

version: 0.1
stack:
  name: '${stack.parents.base.stack.name}-api'
  template:
    file: 'cloudformation.yml'
    bucket: '${stack.parents.base.stack.template.bucket}'
  parents:
    base: '../base'
  parameters:
    BaseStackName: '${stack.parents.base.stack.name}'
  capabilities:
    - 'CAPABILITY_IAM'

Stage

The stage object is used to override any part of the configuration file what that --stage is used as a command line option. For example if we have the following dev stage:

version: 0.1
stack:
  name: 'base-prod'
  template:
    file: 'cloudformation.yml'
    bucket: 'base-templates'
  parameters:
    param1: 'prod-param'
stage:
  dev:
    stack:
      name: 'base-dev'
      parameters:
        param1: 'dev-param'

Now when we use the --stage=dev command line option, our stack name will be 'base-dev' and our param1 will be 'dev-param'. Any field can be overridden.

opt

You can reference any other field in the config file and use it in a variable.

version: 0.1
stack:
  name: 'base-prod'
  template:
    file: 'cloudformation.yml'
    bucket: 'base-templates'
  parameters:
    param1: '${opt.stack.name}'

env

You can reference any environment var in the config file and use it in a variable.

version: 0.1
stack:
  name: 'base-prod'
  template:
    file: 'cloudformation.yml'
    bucket: 'base-templates'
  parameters:
    param1: '${env.param1}'

Lambda

If you stack includes one or more lambda's you can add the lambda section to your _cim.yml to enable Lambda support (lambda-deploy, lambda-logs).

In this example we have two Lambda functions. The function_name will be an output param from our stack. The alias use used by the lambda-deploy and lambda-logs commands to specify a single function.

The deploy section which is broken up into two parts is used by the lambda-deploy command.

pre_deploy Install any dependencies, run the tests, and package the Lambda zip for deployment.
post_deploy Tear down any leftover artifacts from the pre_build phase.

The Lambda zip that is packaged in the pre_build phase must match the zip_file under each function. When a function is deployed it uses the zip_file as the deployment artifact.

lambda:
  functions:
    -
      alias: hello
      function_name: ${stack.outputs.LambdaFunction}
      zip_file: index.zip
    -
      alias: second
      function_name: ${stack.outputs.LambdaFunctionSecond}
      zip_file: index.zip
  deploy:
    phases:
      pre_deploy:
        commands:
          # Install all npm packages including dev packages.
          - npm install

          # Run the tests
          # - npm test

          # Remove all the npm packages.
          - rm -Rf node_modules

          # Only install the non-dev npm packages.  We don't want to bloat our Lambda with dev packages.
          - npm install --production

          # Zip the Lambda for upload to S3.
          - zip -r index.zip .
      post_deploy:
        commands:
          # Remove the zip file.
          - rm -Rf index.zip

          # Reinstall the dev npm packages.
          - npm install

Templates

The templates are using when creating a new package.

cim create --template=<template>

Name	Description
cloudformation	Our base setup.
lambda-node	A single Lambda function.
lambda-node-s3	A single Lambda function with an S3 event trigger.

Plugin Framework

Do you want to create additional CIM commands? Or do you want to create before and after hooks for any CIM command? Or do you just want to create a new template?

There are two ways to contribute to CIM:

Add a new Plugin and create a PR.
Create your own 3rd party CIM plugin. Here is an example. Install these plugins globally. CIM searches the global npm directory for packages starting with cim- or cim_.

Coming soon...

Add all lambda event triggers as templates
Add multiple CloudFormation scripts per package? Maybe...
KMS encryption/decryption for input parameters

cim

Package Exports

Readme

Cloud Infrastructure Manager (CIM)

Usage

Setup

Prerequisites

Install CIM

Commands

create

Usage

Options

templates

Usage

stack-up

Usage

Options

stack-show

Usage

Options

stack-delete

Usage

Options

lambda-deploy

Usage

Options

lambda-logs

Usage

Options

help

Usage

_cim.yml

Basic

Parent stacks

Parameters

Capabilities

Tags

Stage

opt

env

Lambda

Templates

Plugin Framework

Coming soon...