npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

sirocco

v0.7.4

Published

A node library to assist in deploying cloudformation stacks

Downloads

27

Readme

sirocco

A node command line utility and library to assist in deploying AWS CloudFormation stacks.

Deploying any non-trivial CloudFormation stack requires managing parameter values, stack names, tags, etc. When any of this is dynamic, like when deploying to multiple environments/stages, sticking these commands in package.json isn't very practical.

Sirocco manages one or more stacks across multiple environments, generating commands, parameter values, stack names, etc., based on a simple (and optional) configuration file.

The "Quick Start" below is meant as a quick reminder for when you already know how to use this package; to actually get started, take a look at Getting Started.

Requirements

This requires the AWS CLI be installed and executable from your path.

Currently, only YAML is supported from CloudFormation stack templates.

Quick Start

install

> npm install --save-dev sirocco

Basic CLI Usage

> sirocco (deploy|teardown) [DEPLOY_TYPE] [options]

Directory Layout

./
└── stacks/
    ├── queue/
    │   └── stack.yml
    ├── lambda/
    │   └── stack.yml
    └── test/
        └── stack.yml

Config

Specify optional config at .sirocco.js:

module.exports = {
    options: {
        /* command-line-ish options */
    },

    // The default set of stacks to deploy if none are specified with the --stacks option.
    defaultStacks: ["queue", "lambda"],

    // Base configuration shared by all deploy types and envs.
    global: {
        params: {
            suite: "Sirocco",
            app: "SiroccoDemo",
            isTest: false
        }
    },

    // A dictionary of known deploy types.
    deployTypes: {
        dev: {
            validEnvs: /dev-[a-z0-9-]+/,
            role: "NONPROD_ROLE",
            params: {
                nodeEnv: "development"
            }
        },
        prod: {
            role: "PROD_ROLE",
            validEnvs: /prod-[0-9]+/,
            params: {
                nodeEnv: "production"
            }
        }
    },

    envs: {
        "dev-test": {
            params: {
                isTest: true
            }
        }
    }
};

Async Configuration Module

If your config file exports a function, instead of an object, it will be invoked without any arguments and treated as an async function. This allows your config module to do asynchronous things like read from file before returning the actual sirocco config object.

Dynamic Configuration

Parameters and most of configuration options are resolved dynamically for each stack and environment, so a single configuration object can provide dynamic values based on the stack or environment name. The following shows some example of dynamic parameters:

module.exports = {
    global: {
        params: {
            constant: "value",

            foo: (stackName, envName, parameters) => {
                /* derive the value of the "foo" parameter for this stack/env */
            },

            bar:
                "The bar parameter value for stack {stack} in the {env} environment",

            baz: "Derived-From-Other-Params-{constant}",

            trot: () => "A parameter value with literal brackets in it: {foo}"
        }
    }
};

As shown, dynamic parameter values can either be functions (as in "foo" and "trot", above) or string templates (as in "bar" and "baz").

Functions

Functions are invoked with three parameters:

  • The name of the stack being targeted (see below)
  • The name of the environment
  • A dictionary of unresolved parameters.

Note that the first argument, the name of the stack, is the local name of the stack (i.e., the name of the stack's directory under stacks/), not the generated name of the cloudformation stack.

The third argument is a dictionary (a plain object) of the parameters for the stack, without resolving any of the parameter values. Thus, e.g., the "foo" property of this dictionary, in the above examples, would be the foo function itself, not the resulting value.

The dictionary is first populateed with two items: stack and env, which are the same as the values passed in for the first two arguments. However, you happen to have parameters named "stack" or "env", then these entries will be overwritten in the dictionary with the (unresolved) parameter values.

String Templates

String values are assumed to be string-templates which use curly braces to denote place holders to be replaced. These templates are resolved with the same dictionary that is passed as the third argument to function values (described above), which is the unresolved parameter values with the added default properties of stack and env.

If your parameter value has literal pairs of curly braces that you want to include in the value, you can escape them by doubling the braces. You can also make it unambiguous by defining the value as a function which returns the string value you want: returned value are never treated as string-templates.