/ah

Simple, service-oriented management of AWS resources.

Primary LanguageShellEclipse Public License 1.0EPL-1.0

ah it's good

Deployment automation tool.

Install

Ah requires the following packages:

  1. GNU coreutils
  2. GNU make
  3. git
  4. aws command line tool
  5. ronn (gem install ronn)
  6. rs (sudo apt install rs)

For MacOS

brew install coreutils
brew install aws-cli
gem install ronn
# rs already installed
brew install gettext
brew link --force gettext # overwrites mac builtins
brew install json-table

To install in /usr/local do:

sudo make install

To install in a different location:

sudo make PREFIX=/foo/bar install

Getting Help

The ah manual contains complete descriptions of the various commands and features of the program:

man ah

Config

Global config for ah is stored at $HOME/.ah/config

Extensions

ah extensions should be installed to $HOME/.ah/extensions. A convenience function for installing ah extensions is provided. For example:

load_ah_extension git@github.com:yourorg/cool-ah-extensions 2.0

Getting Started

The following sections will take you thorough some basic setup and create a new ah application and environments.

Create the Master Bucket

The first thing to do after installing the program is to create a S3 bucket for ah to store things. You only need to do this once.

Note: you want to make sure this bucket is only accessible by users who will be authorized to manage and deploy ah applications.

After the bucket is created add an environment to your config file:

echo AH_BUCKET=your-bucket-name >> $HOME/.ah/config

Create a Default Org

"Orgs" contain basic settings that span multiple applications. They are used as templates to configure default values at the application and environment levels. You can create as many orgs as you like, but you need at least one.

ah putorg default

You will be asked a number of questions:

  • AWS region — the AWS region (eg. us-east-1).
  • SGs for default ingress rules — these security groups will be added as ingress rules allowing full access to instances in ASGs created by ah. Multiple SGs can be separated by spaces or commas, eg. sg-a0a1c9b7,sg-a0a1c9b8 or sg-a0a1c9b7 sg-a0a1c9b8.
  • Availability zones — availability zones in which ASGs created by ah will launch instances. Multiple AZs can be separated with spaces or commas, eg. a,b,e or a b e.

It's okay if you leave things blank or make a mistake, you can fix it later or override the org settings when you create applications and environments.

You can use ah getorg default to download the org settings, or ah orgs to see a list of org names.

Create an Application

Applications represent some service that will run on instances in AWS. An ah application must be associated with a git repository, and will contain settings that will be used as default values for environments that are created for it.

Prepare the Git Repo

First create the new application's project directory. We'll name this one hello-ah:

mkdir hello-ah && cd hello-ah

Here is a good start for a .gitignore file for ah application repos:

/.ah/env
/target/

Those two directories have special meaning to ah:

  • .ah — this is where ah will store application configuration info. There won't be anything secret in there.
  • target — this is where compiled artifacts will go if you will not be building your application on the instance. You can also put anything in here that you want to have shipped to instances but don't want to commit to your application's git repo.

And the project Makefile (every ah application must have a Makefile):

.PHONY: provision deploy

provision:
    echo "i am an instance, and i am being provisioned now"

deploy:
    echo "i am an instance, and i am being deployed to now"

This Makefile comprises the minimum viable ah application. Ah expects the following targets to be defined:

  • provision — used to configure newly launched instances (install software, configure operating system). This target is run on new instances launched in an ASG automatically by the ASGs launch configuration user data script.
  • deploy — used to prepare the application for service, start or restart it, and do any other things that might need to be done to get it going and fully operational. This target is run automatically (after the provision task) on new instances launched in an ASG. Also run when performing a "hot deploy" to an existing instance via ah-client deploy.

Now that we have a workable ah application let's commit our code to git:

git init && git add . && git commit -m "first commit ever"

Initialize the Ah Application

The init command configures some application defaults and allocates the AWS resources that are shared by all of the environments for this application:

ah init

Again, there will be questions. This time they are mostly related to tags that will be created on AWS resources associated with the application:

  • App name — recommend something alphanumeric, plus dashes and/or underscores. Resources will be tagged with AhApplication set to this.
  • Billing group — resources will be tagged with BillingGroup set to this.
  • Billing project — resources will be tagged with BillingProject set to this.

The application name is the only really important information, so make sure you at least fill that one in properly.

Push a Version to Ah S3 Bucket

In order to deploy this application to instances on AWS we must push the desired commit to ah's S3 bucket:

ah push

This will upload a tarball of HEAD — you can configure ah ASGs to deploy this SHA to instances later.

Note: you can use ah shas to see which commits have been pushed to S3.

Create an Environment