# Jack and the Elastic Beanstalk
[](http://www.readmeci.com/tongueroo/jack)
[](https://circleci.com/gh/tongueroo/jack)
[](https://codeclimate.com/github/tongueroo/jack)
[](https://codeclimate.com/github/tongueroo/jack)
Jack is a wrapper tool around the [aws eb cli3](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli3.html) tool use for managing AWS Elastic Beanstalk, EB, environments. It allows you to create environments using the saved template configuration file generated by `eb config save`. Jack moves the config file to the jack/cfg folder of your project and manages the the config files from there.
Jack provides a `jack config apply` command to update the EB environment. Before uploading the new configuration to EB jack first downloads the current configuration and then does a diff on the changes that are about to be applied. This gives a very helpful preview of exactly what you are intending to change. This particularly helpful when changes are made through the EB GUI and are out of sync with what is stored in the `jack/cfg` files. The demo video is available [here](https://www.youtube.com/watch?v=t7EcAOf8h1o).
This blog post also provides a good introduction and shows some useful examples of what you can do with the jack tool: [Jack and the Elastic Beanstalk — Tool to Manage AWS Elastic Beanstalk Environments](https://medium.com/@tongueroo/jack-and-the-elastic-beanstalk-easily-manage-aws-environments-3ab496f08ad2#.o7w3x0yd9).
For things that this tool does not cover like deploying code, it is recommended that you use use the underlying aws `eb` tool directly. `eb deploy` provides a good deploy command already. This tool has been tested with `EB CLI 3.8.3 (Python 2.7.1)`.
## Use Cases
* Downloading EB config to codified the EB infrastructure that has been built.
* Allowing safe applying of new configs since the preview feature allows you to inspect the changes before actually applying the configuration.
* Moving EB enviroments from one EB application to another EB application. EB provides a way to clone environments within an application but not to another entire application. This is useful if you want to "rename" the EB application.
## Installation
```
$ gem install jack-eb
```
Note that the gem is called jack-eb but the actual command that is installed is called `jack`.
### Setup
If the version of `eb` that you are using is not working with jack, here is a way to install the specific version jack has been tested with.
cd ~/ && wget https://pypi.python.org/packages/source/a/awsebcli/awsebcli-3.8.3.tar.gz
tar -zxvf awsebcli-3.8.3.tar.gz
cd awsebcli-3.8.3
sudo python setup.py install
More detail instructions are on [AWS EB Documentation](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli3-getting-set-up.html).
I typically install the `eb` cli tool with homebrew.
brew update
brew install awsebcli
You will also need to set up your environment with your aws access keys since the tool also uses the aws-sdk. Add the following to your ~/.profile, replacing xxx with your actually credentials. Do not forgot to source the ~/.profile or open up a new terminal.
export AWS_ACCESS_KEY_ID=xxx
export AWS_SECRET_ACCESS_KEY=xxx
## Usage
### Conventions
Before using the tool, it is good to know that jack follows a convention for the environment and application name. This is done in order to keep the jack commands simple and short. The convention is:
environment_name: [app]-[role]-[env]
application_name: [app]
A concrete example is helpful:
environment_name: hi-web-prod
application_name: hi
The example above means the EB application name will be `hi` and the environment name will be `hi-web-prod`. By convention, the first word, separated by a '-', of the environment name is the application name.
This convention can be overridden easily via by creating a `~/.jack/settings.yml` or `jack/settings.yml` within the project and defining your own regular expression with the `conventions.app_name_pattern` key. The regexp is a ruby regexp and must have 1 capture group. The capture group is used to determine the application name. Here is an example:
```yaml
create:
keyname: default
platform: "64bit Amazon Linux 2016.09 v2.2.0 running Docker 1.11.2"
conventions:
app_name_pattern: !ruby/regexp /\w+-(\w+)-\w+/
```
In the example above, the capture group is the second word and this will result in:
environment_name: prod-hi-web
application_name: hi
The default setting is located at [lib/jack/default/settings.yml](https://github.com/tongueroo/jack/blob/master/lib/jack/default/settings.yml).
You can also override the application name convention from the cli with the `--app` flag. Examples are provided below.
### Creating Environments
If you do not yet have EB environment simply create an EB environment with jack and then you can download the initial EB config file it afterwards. To create a EB environment using jack without an initial config file.
```bash
$ git clone https://github.com/tongueroo/sinatra
$ cd sinatra
$ jack create hi-web-stag-1
```
The big benefit of using jack though is the ability to create EB environments based on previously saved configuration files. So now you can download the configuration file from the newly created hi-web-stag-1 environment and version control them.
```bash
$ jack config get hi-web-stag-1
```
This above saves the configuration file at `jack/cfg/hi-web-stag-1.cfg.yml`. Here is an [example](https://gist.github.com/tongueroo/5791a4575a71cb664d48e4e8b29791b3) of what the config file.
If you would like to save the config file under a different path, you can use the `-c` option.
```bash
$ jack config get hi-web-stag-1 -c my-config
```
This saves the config file to `jack/cfg/my-config.cfg.yml` looks like.
You can then create different environments using any of the saved config files.
```bash
$ jack create -c my-config hi-web-stag-2 # creates environment using jack/cfg/myconfig.cfg.yml
```
If the project is brand new and has never had `eb init` ran on it before like a project that has been newly git cloned. Then calling any of the jack commands will automatically call `eb init` in the project. `eb init` requires the platform flag in order to avoid prompting. The default platform is "64bit Amazon Linux 2016.09 v2.2.0 running Docker 1.11.2". But you can override that by creating an `~/.jack/settings.yml` or `jack/settings.yml` within the project folder and setting the `create.platform` key.
Here's an [example](https://gist.github.com/tongueroo/086e3c11c4d00d5c39b6). The options from each file is merged and combined together in following order: project folder, user home, [default](lib/jack/default/settings.yml) that is packaged with this gem. So the project `jack/settings.yml` options have higher precedence than `~/.jack/settings.yml`.
### More Configuration Examples
Configuration templates hold all the options and settings that we can set for an EB environment. Elastic Beanstalk surfaces a portion of settings available from the underlying AWS Resources. These settings include ELB behavior, VPC, LaunchConfiguration, Autoscaling settings, hard drive size, environment variables, etc. Here is an [example](https://gist.github.com/tongueroo/5791a4575a71cb664d48e4e8b29791b3).
#### Get Elastic Beanstalk Configuration
To download the Elastic Beanstalk configuration:
```
$ jack config get hi-web-prod-1
$ jack config get hi-web-prod-1 --app customappname
```
This will save the config to `jack/cfg/hi-web-prod-1.cfg.yml`.
#### Apply Elastic Beanstalk Configuration
To apply a template configuration.
```
$ jack config apply hi-web-prod-1
$ jack config apply hi-web-prod-1 --app customappname
```
This will save the config to `jack/cfg/hi-web-prod-1.cfg.yml`.
You will notice that the `eb config apply` command prompts you with the diff and asks for confirmation before applying. You can bypass the prompt with the `--sure` option.
#### Diff Config - Comparing your local config to the live environment config
You can use the diff command directly to compare your local config to what configs the environment is actually using is useful. To see the diff.
```
$ jack config diff hi-web-prod-1
```
A note about the configs. They are formatted so that the keys are sorted. This has been done so the diffs are actually useful. It is also recommended you install colordiff so you can see the diff output colorized. You can also specify your own diff viewer via the `JACK_DIFF` environment variable.
To use a your own diff viewer, add this to your `~/.profile`:
```
$ export JACK_DIFF=colordiff
```
### More Help
You can get help information from the CLI. Examples:
$ jack help
$ jack create help
$ jack config get help
$ jack config apply help
$ jack config sort help