Stax

About

Stax creates and manages CloudFormation stacks (aka stax) in AWS (Amazon Web Services). Several CloudFormation templates are provided with stax, take a look at them in the templates directory to modify and create your own.

As an illustration, with the proper configuration and templates, stax can create a set of entities in AWS like those shown in the diagram below.

Requirements

Stax requires Linux (tested on Debian GNU/Linux 7/8 and Ubuntu 14.04/15.04) and Apple OS X (tested on 10.09/10.10). You'll also need an account with Amazon Web Services.

Homebrew (Mac OS X only)

Install Homebrew for OS X, which '...installs the stuff you need that Apple didn’t'. Basically it's a *nix package manager like we have in Linux. It's easy to install via their setup script:

$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Visit their site to learn how to install it manually if you don't trust that line.

curl

Install curl if you don't already have it installed (OS X has it by default, and most Linux distros have it by default) on your client.

$ apt-get install curl   # Debian GNU/Linux, Ubuntu
$ yum install curl       # Red Hat Enterprise Linux (RHEL), CentOS, Amazon Linux

awscli

Install aws-cli (Universal Command Line Interface for Amazon Web Services) on your client.

NOTE: the version in the Debian repo is out of date, but we'll need the latest version, to get that we'll first need to install the Python package manager pip. These [install docs](http://www.cyberciti.biz/faq/debian-ubuntu-centos-rhel-linux-install-pipclient/] will help you get pip installed, once complete, go to the next step to install awscli.

$ pip install awscli  # Debian GNU/Linux, Ubuntu
$ brew install awscli     # Apple OS X ([via Homebrew](http://brew.sh/))
$ yum install awscli      # Red Hat Enterprise Linux (RHEL), CentOS, Amazon Linux

After installing the AWS CLI, you will need to configure it with your AWS access credentials, specifically an AWS API key and secret. You can generate these credentials from your IAM user page on the AWS Console. Choose your username, scroll down to Security Credentials > Access Keys (Acess Key ID and Secret Access Key), and click Create Keys if you haven't created them yet. Running stax requires many permissions in AWS, so be sure the IAM user you are running stax as has sufficient permissions, and in an admin group (called 'wheel' by default). If you already have this group, and your user is in that group, continue to 'aws configure' - otherwise follow the next steps to setup the 'wheel' group.

NOTE: if this is a new install (the AWS environment hasn't been used before) you'll need to create the wheel group, and add your user to that group for the user to have permissions to build on AWS.

• In the AWS Console, under the Services tab, choose IAM > Groups > Create New Group > Name it 'wheel' > Next Step > Create Group
• Now go into the group to define the 'Inline Policies'. Again, in the AWS Console, under the Services tab, choose IAM > Groups > Choose the new 'wheel' group > Scroll down to 'Inline Policies' and click on that > In that dropdown click 'click here' on the line that says "To create one, click here." - Now choose Custom Policy > Select > In 'Policy Name' call it 'wheel' then under Policy Document, enter the following:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "*",
      "Resource": "*"
    }
  ]
}

Click 'Apply Policy' - Now apply your user to that group, click Users > Click your new user > Click Add User to Groups > select the 'wheel' group > Click Add to Groups

Run the AWS configure utility to enter your keys and regions.

$ aws configure

You will be prompted to enter your access key and secret access key, copy this from the AWS Console you opened above. Next you will be prompted to enter your AWS region, currently we have stax setup to use us-east-1. Finally you will be prompted for the default output format, enter json. The AWS CLI will store your configuration in ~/.aws/credentials. If you need to change your configuration, you can either run aws configure again or edit this file directly.

Templates

Two templates are provided with stax to get you started, below are brief descriptions.

simple.json

The template template/simple.json stands up a simple AWS environment. Since it is simple to comprehend and spins up quickly, this template is intended as a sandbox to stand up and test new CloudFormation entities. For example, the implementation of CloudWatch Alarms was first tested using this template. The config/simple.json has minimal parameters and the default values are acceptable for all but the project/team/cost parameters.

• Project REQUIRED: Name for the project with which this application ecosystem is associated
• Product REQUIRED: Name for the end-user facing product service by this application ecosystem
• Group REQUIRED: Name of the group that created this stack
• Team REQUIRED: Name of the team that created this stack
• Environment REQUIRED: Type of environment, e. g., production, test, branch name
• KeepAlive REQUIRED: Tag to avoid the reaper, default is false
• InstanceType: AWS EC2 instance type for NAT instances, default is t2.micro
• Owner REQUIRED: Tag for owner of the stack, if set to @OWNER@ stax will substitute the current user id
• KeyName REQUIRED: AWS EC2 Key Pair to use when launching instances, if set to @KEY_NAME@ stax will use a key pair it creates
• SSHLocation: CIDR IP range to allow SSH access to bastion host, if set to @SSH_FROM@ stax will replace it with the CIDR IP of the host running stax, default is 0.0.0.0/0

vpc-default.json

The template template/vpc-default.json creates an environment useful for deploying microservices as docker containers in AWS. The following entities are created:

• 1 VPC (vpc-) Isolated Virtual Private Cloud network.
• 1 EC2 instance Bastion Host (bastion-) Provides SSH access to the VPC.
• 2 EC2 instances NAT boxes (nat1-, nat2-) Proxy network connections to and from the internal CoreOS hosts to the public internet. These instances log all traffic and monitor each other to ensure high availability.
• 1 Elastic Load Balancer Gateway ELB (gateway-elb-) Load balancer for traffic to the Gateway Cluster
• 1 Auto Scaling Group Gateway Cluster (gateway-) An auto scaling group with a default size of 2 of instances running CoreOS. The instances serve as the gateway/router to the internal service instances.
• 3 EC2 Instances Service Leaders (service-leader-N-) Three instances with CloudWatch Alarms for auto-recovery should they fail that serve as the cluster leaders for etcd and consul.
• 1 Auto Scaling Group Service Cluster (service-) An auto scaling group with a default size of zero on which, along with the service leaders, all services deployed to the VPC will run.

The text in parentheses is the first part of the name given to the entity, with the latter part being the CloudFormation stack name.

This template takes the following parameters, see config/vpc-default.json.example for the format.

• Project REQUIRED: Name for the project with which this application ecosystem is associated
• Product REQUIRED: Name for the end-user facing product service by this application ecosystem
• Group REQUIRED: Name of the group that created this stack
• Team REQUIRED: Name of the team that created this stack
• Environment REQUIRED: Type of environment, e. g., production, test, branch name
• KeepAlive REQUIRED: Tag to avoid the reaper, default is false
• Owner REQUIRED: Tag for owner of the stack, if set to @OWNER@ stax will substitute the current user id
• KeyName REQUIRED: AWS EC2 Key Pair to use when launching instances, if set to @KEY_NAME@ stax will use a key pair it creates
• ServiceELBSubdomainName: Route 53 subdomain, leave blank to not create one
• ServiceELBBaseDomainName: Route 53 base domain name, leave blank to not create one
• ServiceELBSSLCertName: IAM name of SSL existing certificate, leave blank to not use SSL
• DockerRegistryUser: Private Docker registry user name
• DockerRegistryPass: Private Docker registry password
• DockerRegistryEmail: Private Docker registry email address
• DockerRegistryUrl: Private Docker registry URL, defaults to https://index.docker.io/v1/
• ServiceClusterSize: Target size of Service Cluster auto scaling group, default is 0
• GatewayClusterSize: Target size of Gateway Cluster auto scaling group, default is 2
• BastionInstanceType: AWS EC2 instance type for bastion host, default is t2.micro
• NATInstanceType: AWS EC2 instance type for NAT instances, default is t2.micro
• DockerInstanceType: AWS EC2 instance type for CoreOS/Docker hosts, default is m3.medium
• CoreOSChannelAMI: CoreOS channel (stable, beta, alpha) to use for CoreOS instances, default is CoreOSStableAMI
• AdvertisedIPAddress: Which instance IP address to use for clustering, private or public, default is private, use public to cluster across unpaired VPCs
• AutoScaleCooldown: Auto scaling cooldown period, in seconds, after an auto scaling event, default is 300
• AllowSSHFrom: CIDR IP range to allow SSH access to bastion host, if set to @SSH_FROM@ stax will replace it with the CIDR IP of the host running stax
• AllowHTTPFrom: CIDR IP range from which to allow HTTP access to the Gat