ufo 3.1.2 → 3.2.0

data/lib/ufo/help/ships.md

@@ -1,18 +1,44 @@
-Builds docker image, registers it and ships it to multiple services.  This deploys the same docker image to multiple ECS services.
+The `ufo ships` command allows you to deploy the *same* Docker image and task definition to multiple ECS services.  It is a common pattern to have the same code base running on different roles.  For example, say you have an application with 3 roles:
 
-Examples:
+1. web - serves web requests.
+2. worker - processes background jobs.
+3. clock - schedules background jobs.
 
-  ufo ships hi-web hi-clock hi-worker
+Instead of using the [ufo ship]({% link _reference/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:
 
-By convention the task definition and service names match for each of the services you ship. If you need to override to this convention then you can specify the task definition for each service with a special syntax.  In the special syntax the service and task definition is separated by a colon.  Example:
+    ufo ships hi-web hi-worker hi-clock
 
-  ufo ships hi-web-1:hi-web hi-clock-1 hi-worker-1
+## Shell expansion
 
-Here ufo will deploy to the hi-web-1 ECS Service using the hi-web task definition, but use the convention for the rest of the service.
+Since the ECS service names are provided as a list you can shorten the command by using bash shell expansion 😁
+
+    ufo ships hi-{web,worker,clock}
+
+If you're new to shell expansion, run this to understand why above works just as well:
+
+    $ echo hi-{web,worker,clock}
+    hi-web hi-worker hi-clock
+
+## Overriding convention
+
+As explained in detail in [Conventions]({% link _docs/conventions.md %}) the task definition and service name are the same by convention.  This convention also applies for each of the services being shipped in the list. The task definition and service names match for each of the services in the list.  If you would like to override the convention as part of the ships command then you use a special syntax. In the special syntax the service and task definition is separated by a colon.  Examples:
+
+    ufo ships hi-web-1:hi-web hi-clock-1 hi-worker-1
+    ufo ships hi-web-1:my-task hi-clock-1:another-task hi-worker-1:third-task
+
+## ufo ships Options
+
+The `ufo ships`, `ufo ship`, `ufo deploy` command support the same options. The options are presented here again for convenience:
+
+{% include ufo-ship-options.md %}
+
+Note: The `--task` option is not used with the `ufo ships` command.
+
+## ELB Target Group
 
 For each service being deployed to, ufo will create the ECS service if the service does not yet exist on the cluster.  The deploy process will prompt you for the ELB `--target-group` if you are deploying to a 'web' service that does not yet exist.  Ufo determines that it is a web service by the name of the service. If the service has 'web' in the name then it is considered a web service. If it is not a web service then the `--target-group` option gets ignored.
 
-The prommpt can be bypassed by specifying a valid `--target-group` option or specifying the `---no-target-group-prompt` option.  Examples:
+The prommt can be bypassed by specifying a valid `--target-group` option or specifying the `---no-target-group-prompt` option.  ## Examples
 
-  ufo ships hi-web hi-clock hi-worker --target-group arn:aws:elasticloadbalancing:us-east-1:123456789:targetgroup/hi-web/jsdlfjsdkd
-  ufo ships hi-web hi-clock hi-worker --no-target-group-prompt
+    ufo ships hi-web hi-clock hi-worker --target-group arn:aws:elasticloadbalancing:us-east-1:123456789:targetgroup/hi-web/jsdlfjsdkd
+    ufo ships hi-web hi-clock hi-worker --no-target-group-prompt

data/lib/ufo/help/task.md

@@ -1,4 +1,4 @@
-Examples:
+## Examples
 
 To run a one time task with ECS:
 

data/lib/ufo/help/tasks.md

@@ -1,4 +1,4 @@
-Examples:
+## Examples
 
   ufo tasks build
 

data/lib/ufo/help/tasks/build.md

@@ -1,7 +1,158 @@
-Examples:
+## Summarized Example
 
-  ufo tasks build
+    ufo tasks build
 
-Builds all the task defintiions.
+Builds all the task defintiions. Note all the existing ufo/output generated task defintions are wiped out.
+
+## Explanation
+
+The command `ufo tasks build` generates the task definitions locally and writes them to the `output/` folder.  There are 2 files that it uses in order to produce the raw AWS task definitions files.
+
+1. ufo/templates/main.json.erb
+2. ufo/task_definitions.rb
+
+Here's an example of each of them:
+
+**main.json.erb**:
+
+    {
+        "family": "<%= @family %>",
+        "containerDefinitions": [
+            {
+                "name": "<%= @name %>",
+                "image": "<%= @image %>",
+                "cpu": <%= @cpu %>,
+                <% if @memory %>
+                "memory": <%= @memory %>,
+                <% end %>
+                <% if @memory_reservation %>
+                "memoryReservation": <%= @memory_reservation %>,
+                <% end %>
+                <% if @container_port %>
+                "portMappings": [
+                    {
+                        "containerPort": "<%= @container_port %>",
+                        "protocol": "tcp"
+                    }
+                ],
+                <% end %>
+                "command": <%= @command.to_json %>,
+                <% if @environment %>
+                "environment": <%= @environment.to_json %>,
+                <% end %>
+                <% if @awslogs_group %>
+                "logConfiguration": {
+                    "logDriver": "awslogs",
+                    "options": {
+                        "awslogs-group": "<%= @awslogs_group %>",
+                        "awslogs-region": "<%= @awslogs_region || 'us-east-1' %>",
+                        "awslogs-stream-prefix": "<%= @awslogs_stream_prefix %>"
+                    }
+                },
+                <% end %>
+                "essential": true
+            }
+        ]
+    }
+
+**task_definitions.rb**:
+
+```ruby
+task_definition "hi-web" do
+  source "main" # will use ufo/templates/main.json.erb
+  variables(
+    family: task_definition_name,
+    name: "web",
+    container_port: helper.dockerfile_port,
+    command: ["bin/web"]
+  )
+end
+
+task_definition "hi-worker" do
+  source "main" # will use ufo/templates/main.json.erb
+  variables(
+    family: task_definition_name,
+    name: "worker",
+    command: ["bin/worker"]
+  )
+end
+
+task_definition "hi-clock" do
+  source "main" # will use ufo/templates/main.json.erb
+  variables(
+    family: task_definition_name,
+    name: "clock",
+    command: ["bin/clock"]
+  )
+end
+```
+
+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/production.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:
+
+    ufo tasks build
+
+You should see output similar to below:
+
+    $ 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.json`.
+
+    {
+      "family": "hi-web",
+      "containerDefinitions": [
+        {
+          "name": "web",
+          "image": "tongueroo/hi:ufo-2017-06-11T22-22-32-a18aa30",
+          "cpu": 128,
+          "memoryReservation": 256,
+          "portMappings": [
+            {
+              "containerPort": "3000",
+              "protocol": "tcp"
+            }
+          ],
+          "command": [
+            "bin/web"
+          ],
+          "environment": [
+            {
+              "name": "RAILS_ENV",
+              "value": "staging"
+            }
+          ],
+          "essential": true
+        }
+      ]
+    }
+
+If you need to modify the task definition template to suite your own needs it is super simple, just edit `main.json.erb`.  No need to dive deep into internal code that builds up the task definition with some internal structure.  It is all there for you to fully control.
 
-Note all the existing ufo/output generated task defintions are wiped out.

data/lib/ufo/help/tasks/register.md

@@ -1,5 +1,14 @@
-Examples:
+The `ufo tasks register` command registers all the generated task definitions in `output/` to AWS ECS. Let's run it:
 
-  ufo tasks register
+    ufo tasks register
+
+You should see something similiar to this:
+
+    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:
+
+<img src="/img/tutorials/ecs-console-task-definitions.png" class="doc-photo" />
 
-All the task defintiions in ufo/output registered.

data/lib/ufo/ship.rb

@@ -99,8 +99,6 @@ module Ufo
       # ELB to drain the register container otherwise. This might cut off some requests but
       # providing this as an option that can be turned of beause I've seen deploys go way too
       # slow.
-      puts "@options[:stop_old_tasks] #{@options[:stop_old_tasks].inspect}"
-      puts "old_tasks.size #{old_tasks.size}"
       old_tasks.each do |task|
         puts "stopping task.task_definition_arn #{task.task_definition_arn.inspect}"
         ecs.stop_task(cluster: @cluster, task: task.task_arn, reason: reason)
@@ -358,8 +356,8 @@ module Ufo
     end
 
     def ensure_cluster_exist
-      cluster_exist = ecs_clusters.first
-      unless cluster_exist
+      cluster = ecs_clusters.first
+      unless cluster && cluster.status == "ACTIVE"
         message = "#{@cluster} cluster created."
         if @options[:noop]
           message = "NOOP #{message}"

data/lib/ufo/tasks.rb

@@ -3,14 +3,14 @@ module Ufo
     autoload :Builder, 'ufo/tasks/builder'
     autoload :Register, 'ufo/tasks/register'
 
-    desc "build", "builds task definitions"
+    desc "build", "Build task definitions."
     long_desc Help.text("tasks:build")
     option :pretty, type: :boolean, default: true, desc: "Pretty format the json for the task definitions"
     def build
       Tasks::Builder.new(options).build
     end
 
-    desc "register", "register all built task definitions in ufo/output"
+    desc "register", "Register all built task definitions in `ufo/output` folder."
     long_desc Help.text("tasks:register")
     def register
       Tasks::Register.register(:all, options)

data/lib/ufo/version.rb

@@ -1,3 +1,3 @@
 module Ufo
-  VERSION = "3.1.2"
+  VERSION = "3.2.0"
 end

data/spec/lib/ship_spec.rb

@@ -59,7 +59,8 @@ describe Ufo::Ship do
   # ensure_cluster_exist calls this and this makes sure that the cluster 'exists'
   def ecs_describe_clusters
     describe_clusters = double("ecs-describe-clusters")
-    allow(describe_clusters).to receive(:clusters).and_return(["cluster1"])
+    cluster1 = OpenStruct.new(status: "ACTIVE")
+    allow(describe_clusters).to receive(:clusters).and_return([cluster1])
     describe_clusters
   end
 

data/ufo.gemspec

@@ -7,8 +7,7 @@ Gem::Specification.new do |spec|
   spec.version       = Ufo::VERSION
   spec.authors       = ["Tung Nguyen"]
   spec.email         = ["tongueroo@gmail.com"]
-  spec.description   = %q{Build Docker Containers and Ship Them to AWS ECS}
-  spec.summary       = %q{Build Docker Containers and Ship Them to AWS ECS}
+  spec.summary       = "Build Docker Containers and Ship Them to AWS ECS"
   spec.homepage      = "http://ufoships.com"
   spec.license       = "MIT"
 
@@ -24,11 +23,12 @@ Gem::Specification.new do |spec|
   spec.add_dependency "aws-sdk-ecr"
   spec.add_dependency "aws-sdk-ecs"
   spec.add_dependency "aws-sdk-elasticloadbalancingv2"
+  spec.add_dependency "cli_markdown"
   spec.add_dependency "colorize"
   spec.add_dependency "deep_merge"
   spec.add_dependency "plissken"
-  spec.add_dependency "thor"
   spec.add_dependency "render_me_pretty"
+  spec.add_dependency "thor"
 
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "byebug"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ufo
 version: !ruby/object:Gem::Version
-  version: 3.1.2
+  version: 3.2.0
 platform: ruby
 authors:
 - Tung Nguyen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-02-22 00:00:00.000000000 Z
+date: 2018-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-cloudwatchlogs
@@ -80,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: cli_markdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: colorize
   requirement: !ruby/object:Gem::Requirement
@@ -123,7 +137,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: thor
+  name: render_me_pretty
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -137,7 +151,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: render_me_pretty
+  name: thor
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -206,7 +220,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Build Docker Containers and Ship Them to AWS ECS
+description: 
 email:
 - tongueroo@gmail.com
 executables:
@@ -214,6 +228,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".circleci/bin/commit_docs.sh"
 - ".circleci/config.yml"
 - ".gitignore"
 - ".gitmodules"
@@ -234,7 +249,6 @@ files:
 - docs/_config.yml
 - docs/_docs/auto-completion.md
 - docs/_docs/automated-cleanup.md
-- docs/_docs/commands.md
 - docs/_docs/conventions.md
 - docs/_docs/helpers.md
 - docs/_docs/install.md
@@ -250,20 +264,7 @@ files:
 - docs/_docs/tutorial-ufo-ships.md
 - docs/_docs/tutorial-ufo-tasks-build.md
 - docs/_docs/tutorial.md
-- docs/_docs/ufo-deploy.md
-- docs/_docs/ufo-destroy.md
-- docs/_docs/ufo-docker-base.md
-- docs/_docs/ufo-docker-build.md
-- docs/_docs/ufo-docker-clean.md
-- docs/_docs/ufo-docker-name.md
-- docs/_docs/ufo-docker-push.md
 - docs/_docs/ufo-env.md
-- docs/_docs/ufo-help.md
-- docs/_docs/ufo-init.md
-- docs/_docs/ufo-scale.md
-- docs/_docs/ufo-ship.md
-- docs/_docs/ufo-ships.md
-- docs/_docs/ufo-tasks-build.md
 - docs/_docs/ufo-tasks-register.md
 - docs/_docs/variables.md
 - docs/_includes/about.html
@@ -290,12 +291,35 @@ files:
 - docs/_includes/modals.html
 - docs/_includes/nav.html
 - docs/_includes/quotes.html
+- docs/_includes/reference.md
 - docs/_includes/subnav.html
 - docs/_includes/summary.html
 - docs/_includes/ufo-ship-options.md
 - docs/_includes/uses.html
 - docs/_layouts/default.html
 - docs/_layouts/style.css
+- docs/_reference/ufo-completion.md
+- docs/_reference/ufo-completion_script.md
+- docs/_reference/ufo-deploy.md
+- docs/_reference/ufo-destroy.md
+- docs/_reference/ufo-docker-base.md
+- docs/_reference/ufo-docker-build.md
+- docs/_reference/ufo-docker-clean.md
+- docs/_reference/ufo-docker-help.md
+- docs/_reference/ufo-docker-name.md
+- docs/_reference/ufo-docker-push.md
+- docs/_reference/ufo-docker.md
+- docs/_reference/ufo-init.md
+- docs/_reference/ufo-scale.md
+- docs/_reference/ufo-ship.md
+- docs/_reference/ufo-ships.md
+- docs/_reference/ufo-task.md
+- docs/_reference/ufo-tasks-build.md
+- docs/_reference/ufo-tasks-help.md
+- docs/_reference/ufo-tasks-register.md
+- docs/_reference/ufo-tasks.md
+- docs/_reference/ufo-upgrade3.md
+- docs/_reference/ufo-version.md
 - docs/articles.md
 - docs/bin/web
 - docs/css/font-awesome/css/font-awesome.css
@@ -328,6 +352,7 @@ files:
 - docs/js/jquery.easing.min.js
 - docs/js/nav.js
 - docs/quick-start.md
+- docs/reference.md
 - docs/style.css
 - exe/ufo
 - lib/template/.env
@@ -346,7 +371,6 @@ files:
 - lib/ufo/completer.rb
 - lib/ufo/completer/script.rb
 - lib/ufo/completer/script.sh
-- lib/ufo/completion.rb
 - lib/ufo/core.rb
 - lib/ufo/default.rb
 - lib/ufo/default/settings.yml
@@ -394,7 +418,6 @@ files:
 - lib/ufo/sequence.rb
 - lib/ufo/setting.rb
 - lib/ufo/ship.rb
-- lib/ufo/sub.rb
 - lib/ufo/task.rb
 - lib/ufo/tasks.rb
 - lib/ufo/tasks/builder.rb