Home

Deployer

1. What is Deployer?

2. Getting Started

   a. Installing Deployer

   b. Creating a configuration file

   c. Running Deployer Commands

What is Deployer?

Deployer a command line tool used to create | update | delete CloudFormation Stacks. Built in python, Deployer is easy to install and easy to get started with.

Getting Started

Installing Deployer

Deployer can easily be installed using pip!

1. Download the lastest release.

2. Pip install the tar!

   pip install deployer.tar.gz

3. Verify Deployer installed properly!

   deployer --version

Alternatively, you can install Deployer using Docker.

---

Creating a configuration file

Deployer uses configuration files to keep track of environment information. This includes launch information, lambda locations, tags, and stack parameters.

For an basic configuration example, let's create a config file to deploy AWS Labs' SNS Topic Stack, a basic stack that sets up an SNS Topic with a subscription. We'll store SNSTopic.json as ./cloudformation/top.json.

Top Level Objects

In a Deployer configuration file, there are two main high level objects: Stacks, an object representing a CloudFormation Stack and global, an object that loads common configurations that are passed to all stacks in the file.

Global Configuration

There are a few global configurations we need to make to setup our config file. Notably our region, release, sync information, and template location.

global:
  region: us-east-1
  release: 'develop'
  sync_dirs: [ cloudformation ]
  sync_base: ./
  sync_dest_bucket: ex-cloudtools-us-east-1
  template_bucket: ex-cloudtools-us-east-1
  tags:
    Project: DeployerExample

Then, we can add a tag for good measure.

Properties

region: AWS Region that Deployer will operate in.

release: Used for organizing and deploying different project versions.

sync_dirs: Directories that are uploaded to S3 to be used in the deployment process.

sync_base: The working directory of Deployer.

sync_dest_bucket: The S3 bucket to upload our sync_dirs to.

template_bucket: The S3 bucket to deploy our stacks from.

tags: Dictionary of tags to be applied all stacks in the configuration file.

You will have to specify your own sync_dest_bucket and template_bucket that you have read/write access to.

Basic Stack Properties

For every stack, we have to give it a name to use with Deployer and a stack_name. To launch the stack, we will also have to specify the template to launch. In stack objects, we can also add/overrwrite values in the global configuration. For example, we could also specify additional sync_dirs if necessary.

In this example, we'll use SnsExample for both names.

...

SnsExample:
  stack_name: SnsExample
  template: cloudformation/top.json 

Parameters

Parameters can be set either globally or within a specified stack. Any parameters that are not used by the CloudFormation template, are ignored by Deployer.

In our example scenario, our stack has two parameters: SubscriptionEndPoint and SubscriptionProtocol. Both of which will be exclusive to our stack.

...

SnsExample:
  ...
  parameters:
    SubscriptionEndPoint: example@rightbrainnetworks.com
    SubscriptionProtocol: email

Finished Configuration File

Now that we have our configuration file complete, we can move on to deploying our stack.

global:
  region: us-east-1
  release: 'develop'
  sync_dirs: [ cloudformation ]
  sync_base: ./
  sync_dest_bucket: ex-cloudtools-us-east-1
  template_bucket: ex-cloudtools-us-east-1
  tags:
    Project: DeployerExample
 
SnsExample:
  stack_name: SnsExample
  template: cloudformation/top.json 
  parameters:
    SubscriptionEndPoint: example@rightbrainnetworks.com
    SubscriptionProtocol: email

See more on configuration.

---

Running Deployer Commands

Deployer commands requrire a config file, a stack, and an action with optional arguements, such as profile, and flags, such as -y to sync.

deployer -c CONFIG_FILE -s STACK -x ACTION [-p PROFILE] [-y]

Creating a stack

To create a stack, run Deployer with the create action:

deployer -c CONFIG_FILE -s STACK -x create [-p PROFILE] [-y]

Be sure to include the sync flag (-y) so that your cloudformation files are in your cloud tools bucket.

Updating a stack

To update a stack, run Deployer with the update action:

deployer -c CONFIG_FILE -s STACK -x update [-p PROFILE] [-y]

Be sure to include the sync flag (-y) so that your latest cloudformation files are in your cloud tools bucket.

Deleting a stack

To delete a stack, run Deployer with the delete action:

deployer -c CONFIG_FILE -s STACK -x delete [-p PROFILE]

See more on Deployer actions and flags