ufo 1.7.1 → 2.0.0

data/docs/_docs/ufo-destroy.md

@@ -5,13 +5,13 @@ title: ufo destroy
 Ufo provides a quick way to destroy an ECS service. In order to destroy an ECS service you must makes sure that the desired number of tasks is first set to 0. It is easy to forgot to do this and waste time. So as part of destroying the service ufo will scale the ECS service down to 0 automatically first and then destroy the service.  Ufo also prompts you before destroying the service.
 
 ```
-ufo destroy hi-web-stag
+ufo destroy hi-web
 ```
 
 If you would like to bypass the prompt you can use the `--sure` option.
 
 ```
-ufo destroy hi-web-stag --sure
+ufo destroy hi-web --sure
 ```
 
 <a id="prev" class="btn btn-basic" href="{% link _docs/ufo-scale.md %}">Back</a>

data/docs/_docs/ufo-env.md

@@ -0,0 +1,54 @@
+---
+title: UFO_ENV
+---
+
+Ufo's behavior is controlled by the `UFO_ENV` environment variable.  For example, the `UFO_ENV` variable is used to layer different ufo variable files together to make it easy to specify settings for different environments like production and staging.  This is covered thoroughly in the [Variables]({% link _docs/variables.md %}) section.  `UFO_ENV` defaults to `prod` when not set.
+
+### Setting UFO_ENV
+
+The `UFO_ENV` can be set easily in several ways:
+
+1. At the CLI command invocation - This takes the highest precedence.
+2. Exported as an environment variable to your shell - This takes the second highest precedence.
+3. As a `aws_profile_ufo_env_map` value in your `ufo/settings.yml` file - This takes the lowest precedence.
+
+### At the CLI Command
+
+```sh
+UFO_ENV=prod ufo ship hi-web --cluster prod
+```
+
+### As an environment variable
+
+```sh
+export UFO_ENV=prod
+ufo ship hi-web --cluster prod
+```
+
+Most people will set `UFO_ENV` in their `~/.profile`.
+
+### In ufo/settings.yml
+
+The most interesting way to set `UFO_ENV` is with the `aws_profile_ufo_env_map` in `ufo/settings.yml`.  Let's say you have a `~/.ufo/settings.yml` with the following:
+
+```yaml
+aws_profile_ufo_env_map:
+  default: dev
+  my-prod-profile: prod
+  my-stag-profile: stag
+```
+
+In this case, when you set `AWS_PROFILE` to switch AWS profiles, ufo picks this up and maps the `AWS_PROFILE` value to the specified `UFO_ENV` using the `aws_profile_ufo_env_map` lookup.  Example:
+
+```sh
+AWS_PROFILE=my-prod-profile => UFO_ENV=prod
+AWS_PROFILE=my-stag-profile => UFO_ENV=stag
+AWS_PROFILE=default => UFO_ENV=dev
+AWS_PROFILE=whatever => UFO_ENV=dev
+```
+
+Notice how `AWS_PROFILE=whatever` results in `UFO_ENV=dev`.  This is because the `default: dev` map is specially treated. If you set the `default` map, this becomes the default value when the profile map is not specified in the rest of `ufo/settings.yml`.  More info on settings is available at [settings]({% link _docs/settings.md %}).
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/settings.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/variables.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/ufo-init.md

@@ -11,7 +11,7 @@ Let's run the command in our newly clone project.
 ```sh
 git clone https://github.com/tongueroo/hi.git
 cd hi
-ufo init --app=hi --env stag --cluster=stag --image=tongueroo/hi
+ufo init --app=hi --env prod --cluster=prod --image=tongueroo/hi
 ```
 
 You should see output similiar to this:
@@ -25,8 +25,12 @@ ufo
 ├── output
 ├── settings.yml
 ├── task_definitions.rb
-└── templates
-    └── main.json.erb
+├── templates
+├   └── main.json.erb
+└── variables
+    ├── base.rb
+    ├── prod.rb
+    └── stag.rb
 ```
 
 The explanation of the folders and files were covered in detailed earlier at [Structure]({% link _docs/structure.md %}).

data/docs/_docs/ufo-scale.md

@@ -5,13 +5,13 @@ title: ufo scale
 Ufo provides a command to quickly scale up and down an ECS service. Here's an example of how you use it:
 
 ```sh
-ufo scale hi-web-stag 3
+ufo scale hi-web
 ```
 
 You should get output similiar to below:
 
 ```sh
-Scale hi-web-stag service in stag cluster to 3
+Scale hi-web service in stag cluster to 3
 ```
 
 While scaling via this method is quick and convenient the [ECS Service AutoScaling](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-auto-scaling.html) that is built into ECS is a much more powerful way to manage scaling your ECS service.

data/docs/_docs/ufo-ship.md

@@ -15,13 +15,13 @@ As you can see there are plenty of options for `ufo ship`.  Let's demonstrate us
 When you are deploying to a service with the word 'web' in it, ufo by convention assumes that this is a web service that uses a load balancer in front of it.  This is also covered a in the [Conventions]({% link _docs/conventions.md %}) page.  If you would you like to create a service with the word web without an load balancer associated with it you can use the `--no-target-group-prompt` option:
 
 ```sh
-ufo ship hi-web-stag --no-target-group-prompt
+ufo ship hi-web --no-target-group-prompt
 ```
 
 Or if you would like specify the target-group up front and not be bother with the prompted later you can use the `--target-group` option.
 
 ```sh
-ufo ship hi-web-stag --target-group=arn:aws:elasticloadbalancing:us-east-1:12345689:targetgroup/hi-web-prod/12345
+ufo ship hi-web --target-group=arn:aws:elasticloadbalancing:us-east-1:12345689:targetgroup/hi-web-prod/12345
 ```
 
 #### Deploying Existing Task Definition
@@ -29,7 +29,7 @@ ufo ship hi-web-stag --target-group=arn:aws:elasticloadbalancing:us-east-1:12345
 Let's say you already have built an registered a task definition by some other means and only want to use ufo to deploy that already registered task definition. You can do this by skipping the task build and register phase. It probably also makes sense to skip the docker phase in this case.
 
 ```sh
-ufo ship hi-web-stag --no-docker --no-tasks
+ufo ship hi-web --no-docker --no-tasks
 ```
 
 #### Waiting for Deployments to Complete
@@ -37,15 +37,15 @@ ufo ship hi-web-stag --no-docker --no-tasks
 By default when ufo updates the ECS service with the new task definition it does so asynchronuously. You then normally visit the ECS service console and then refresh until you see that the deployment is completed.  You can also have ufo poll and wait for the deployment to be done with the `--wait` option
 
 ```sh
-ufo ship hi-web-stag --wait
+ufo ship hi-web --wait
 ```
 
 You should see output similar to this:
 
 ```sh
-Shipping hi-web-stag...
-hi-web-stag service updated on stag cluster with task hi-web-stag
-Waiting for deployment of task definition hi-web-stag:8 to complete
+Shipping hi-web...
+hi-web service updated on cluster with task hi-web
+Waiting for deployment of task definition hi-web:8 to complete
 ......
 Time waiting for ECS deployment: 31s.
 Software shipped!
@@ -56,7 +56,7 @@ Software shipped!
 Since ufo builds the Docker image every time there's a deployment you will end up with a long list of docker images.  Ufo automatically cleans up older docker images at the end of the deploy process if you are using AWS ECR.  By default ufo keeps the most recent 30 Docker images. This can be adjust with the `--ecr-keep` option.
 
 ```sh
-docker ship hi-web-stag --ecr-keep 2
+docker ship hi-web --ecr-keep 2
 ```
 
 You should see something like this:

data/docs/_docs/ufo-ships.md

@@ -11,7 +11,7 @@ The `ufo ships` command allows you to deploy the *same* Docker image and task de
 Instead of using the [ufo ship]({% link _docs/ufo-ship.md %}) and build and deploying the code 3 times you can instead use `ufo ships`.  This will result in the *same* Docker image and *same* task definition being deployed to all 3 services.  Example usage:
 
 ```sh
-ufo ships hi-web-stag hi-worker-stag hi-clock-stag
+ufo ships hi-web hi-worker hi-clock
 ```
 
 ### Shell expansion
@@ -19,14 +19,14 @@ ufo ships hi-web-stag hi-worker-stag hi-clock-stag
 Since the ECS service names are provided as a list you can shorten the command by using bash shell expansion 😁
 
 ```sh
-ufo ships hi-{web,worker,clock}-stag
+ufo ships hi-{web,worker,clock}
 ```
 
 If you're new to shell expansion, run this to understand why above works just as well:
 
 ```sh
-$ echo hi-{web,worker,clock}-stag
-hi-web-stag hi-worker-stag hi-clock-stag
+$ echo hi-{web,worker,clock}
+hi-web hi-worker hi-clock
 ```
 
 ### Overriding convention

data/docs/_docs/ufo-tasks-build.md

@@ -56,49 +56,56 @@ Here's an example of each of them:
 **task_definitions.rb**:
 
 ```
-# common variables
-common = {
-  image: helper.full_image_name, # includes the git sha tongueroo/hi:ufo-[sha].
-  cpu: 128,
-  memory_reservation: 256,
-  environment: helper.env_file(".env")
-  # another example
-  # environment: helper.env_vars(%Q{
-  #   RAILS_ENV=production
-  #   SECRET_KEY_BASE=secret
-  # })
-}
-
-task_definition "hi-web-stag" do
+task_definition "hi-web" do
   source "main" # will use ufo/templates/main.json.erb
-  variables(common.dup.deep_merge(
+  variables(
     family: task_definition_name,
     name: "web",
     container_port: helper.dockerfile_port,
     command: ["bin/web"]
-  ))
+  )
 end
 
-task_definition "hi-worker-stag" do
+task_definition "hi-worker" do
   source "main" # will use ufo/templates/main.json.erb
-  variables(common.dup.deep_merge(
+  variables(
     family: task_definition_name,
     name: "worker",
     command: ["bin/worker"]
-  ))
+  )
 end
 
-task_definition "hi-clock-stag" do
+task_definition "hi-clock" do
   source "main" # will use ufo/templates/main.json.erb
-  variables(common.dup.deep_merge(
+  variables(
     family: task_definition_name,
     name: "clock",
     command: ["bin/clock"]
-  ))
+  )
 end
 ```
 
-Ufo uses the ERB template in `main.json.erb` and combines it with the variables defined in the task definition declarations in `task_definitions.rb` and generates the raw AWS formatted task definition in the `output` folder.  In this case there are 3 task_definitions so there will be 3 generated output files.
+The shared variables are set in the variables folder:
+
+**ufo/variables/base.rb**:
+
+```ruby
+@image = helper.full_image_name # includes the git sha tongueroo/hi:ufo-[sha].
+@cpu = 128
+@memory_reservation = 256
+@environment = helper.env_file(".env")
+```
+
+**ufo/variables/prod.rb**:
+
+```ruby
+@environment = helper.env_vars(%Q{
+  RAILS_ENV=production
+  SECRET_KEY_BASE=secret
+})
+```
+
+Ufo combines the `main.json.erb` template, `task_definitions.rb` definitions, and variables in the `ufo/variables` folder.  It then generates the raw AWS formatted task definition in the `output` folder.
 
 To build the task definitions:
 
@@ -108,13 +115,22 @@ ufo tasks build
 
 You should see output similar to below:
 
-<img src="/img/tutorials/ufo-tasks-build.png" class="doc-photo" />
+```sh
+$ ufo tasks build
+Building Task Definitions...
+Generating Task Definitions:
+  ufo/output/hi-web.json
+  ufo/output/hi-worker.json
+  ufo/output/hi-clock.json
+Task Definitions built in ufo/output.
+$
+```
 
-Let's take a look at one of the generated files: `ufo/output/hi-web-stag.json`.
+Let's take a look at one of the generated files: `ufo/output/hi-web.json`.
 
 ```json
 {
-  "family": "hi-web-stag",
+  "family": "hi-web",
   "containerDefinitions": [
     {
       "name": "web",

data/docs/_docs/ufo-tasks-register.md

@@ -11,9 +11,9 @@ ufo tasks register
 You should see something similiar to this:
 
 ```sh
-hi-clock-stag task definition registered.
-hi-web-stag task definition registered.
-hi-worker-stag task definition registered.
+hi-clock task definition registered.
+hi-web task definition registered.
+hi-worker task definition registered.
 ```
 
 You can verify that the task definitions have been registered properly by viewing the AWS ECS Console Task Definitions page.  You should see something similar to this:

data/docs/_docs/variables.md

@@ -0,0 +1,48 @@
+---
+title: Shared Variables
+---
+
+Often times, you end up using the set of common variables across your task definitions for a project.  Ufo supports a shared variables concept to help with this.  You specify variables files in the `ufo/variables` folder and they are made availale to your `ufo/task_definitions.rb` as well as your `ufo/templates` files.
+
+For example, given `config/variables/base.rb`:
+
+```
+@image = helper.full_image_name # includes the git sha tongueroo/hi:ufo-[sha].
+@cpu = 128
+@memory_reservation = 256
+@environment = helper.env_file(".env")
+```
+
+You can now use @image in your `ufo/templates/main.json.erb` without having to explicitly declaring them in the `ufo/task_definitions.rb` file.  Variables are automatically made available to all templates and the `task_definition.rb` file also.
+
+### Layering
+
+Shared variables also support a concept called layering.  The `config/variables/base.rb` file is treated specially and will always be evaluated.  Additionally, ufo will also evaluate the `config/variables/[UFO_ENV].rb` according to what UFO_ENV's value is. Thanks layering, you can easily override variables to suite different environments like production or staging. For example:
+
+`config/variables/base.rb`:
+
+```ruby
+@cpu = 128
+```
+
+When `ufo ship` is ran with `UFO_ENV=prod` he `config/variables/prod.rb` will be evaluated and layered on top of the variables defined in `base.rb:
+
+`config/variables/prod.rb`:
+
+```ruby
+@cpu = 256
+```
+
+When `ufo ship` is ran with `UFO_ENV=stag` he `config/variables/stag.rb` will be evaluated and layered on top of the variables defined in `base.rb:
+
+
+`config/variables/stag.rb`:
+
+```ruby
+@cpu = 192
+```
+
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/ufo-env.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/helpers.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_includes/commands.html

@@ -35,6 +35,7 @@ ufo destroy
         {
             "name": "<%= @name %>",
             "image": "<%= @image %>",
+            <% if @cpu %>
             "cpu": <%= @cpu %>,
             <% end %>
             "command": <%= @command.to_json %>,

data/docs/_includes/subnav.html

@@ -33,6 +33,8 @@
             </ul>
         </li>
         <li><a href="{% link _docs/settings.md %}">Settings</a></li>
+        <li><a href="{% link _docs/ufo-env.md %}">UFO_ENV</a></li>
+        <li><a href="{% link _docs/variables.md %}">Shared Variables</a></li>
         <li><a href="{% link _docs/helpers.md %}">Helpers</a></li>
         <li><a href="{% link _docs/conventions.md %}">Conventions</a></li>
         <li><a href="{% link _docs/run-in-pieces.md %}">Run In Pieces</a></li>

data/docs/bin/web

@@ -0,0 +1,4 @@
+#!/bin/bash -ex
+
+bundle exec jekyll clean
+exec bundle exec jekyll serve

data/docs/quick-start.md

@@ -8,14 +8,32 @@ In a hurry? No sweat! Here's a quick start to using ufo that takes only a few mi
 brew cask install boltopslabs/software/bolts
 git clone https:///github.com/tongueroo/hi.git
 cd hi
-ufo init --app=hi --env stag --cluster=stag --image=tongueroo/hi
-ufo ship hi-web-stag
+ufo init --app=hi --env prod --cluster=prod --image=tongueroo/hi
+ufo ship hi-web
 ```
 
 You should see something similar to this:
 
-<img src="/img/tutorials/ufo-init.png" class="doc-photo" />
-
+```
+$ ufo init --app=hi --env prod --cluster=prod --image=tongueroo/hi
+Setting up ufo project...
+created: ./bin/deploy
+created: ./Dockerfile
+created: ./ufo/settings.yml
+created: ./ufo/task_definitions.rb
+created: ./ufo/templates/main.json.erb
+created: ./ufo/variables/base.rb
+created: ./ufo/variables/prod.rb
+created: ./ufo/variables/stag.rb
+created: ./.env
+Starter ufo files created.
+$ ufo ship hi-web
+Building docker image with:
+  docker build -t tongueroo/hi:ufo-2017-09-10T15-00-19-c781aaf -f Dockerfile .
+....
+Software shipped!
+$
+```
 Congratulations! You have successfully deployed code to AWS ECS with ufo. It was really that simple 😁
 
 Note: This quick start does require that you have a docker working on your environment.  For docker installation instructions refer to to the official [docker installation guide](https://docs.docker.com/engine/installation/).

data/lib/starter_project/bin/deploy

@@ -4,4 +4,4 @@
 # be overridden.
 
 # Only build one docker image and deploys it to multiple ECS services
-ufo ships <%= @app %>-{web,clock,worker}-<%= @env %> --cluster <%= @cluster %>
+ufo ships <%= @app %>-{web,clock,worker} --cluster <%= @cluster %>

data/lib/starter_project/ufo/settings.yml

@@ -2,9 +2,17 @@
 image: <%= @image %>
 # clean_keep: 30
 # ecr_keep: 30
-service_cluster:
-  default: <%= @cluster %> # default cluster
-  # can override the default cluster for each service.  CLI overrides all of these settings.
-  <%= @app %>-web-<%= @env %>:
-  <%= @app %>-clock-<%= @env %>:
-  <%= @app %>-worker-<%= @env %>:
+
+# aws_profile_ufo_env_map:
+#   default: prod
+#   # More examples:
+#   aws_profile1: prod
+#   aws_profile2: stag
+#   aws_profile3: dev
+
+# ufo_env_cluster_map:
+#   default: prod
+#   # More examples:
+#   aws_profile1: prod
+#   aws_profile2: stag
+#   aws_profile3: dev