ufo 3.1.2 → 3.2.0

data/docs/_reference/ufo-docker-clean.md

@@ -0,0 +1,44 @@
+---
+title: ufo docker clean
+reference: true
+---
+
+## Usage
+
+    ufo docker clean IMAGE_NAME
+
+## Description
+
+Clean up old images.  Keeps a specified amount.
+
+Ufo comes with a handy command to clean up old images that ufo generates. Ufo only deletes images from the docker daemon and does not remove any images from any registry.  To use it you pass the base portion of the image name to the command.
+
+Say you currently have these images:
+
+    tongueroo/hi:ufo-2016-10-15T19-29-06-88071f5
+    tongueroo/hi:ufo-2016-10-16T19-29-06-88071f5
+    tongueroo/hi:ufo-2016-10-17T19-29-06-88071f5
+    tongueroo/hi:ufo-2016-10-18T19-29-06-88071f5
+
+To clean them up and keep the 3 more recent:
+
+    $ ufo docker clean tongueroo/hi
+    Cleaning up docker images...
+    Running: docker rmi tongueroo/hi:ufo-2016-10-15T19-29-06-88071f5
+
+This will remove tongueroo/hi:ufo-2016-10-15T19-29-06-88071f5.
+
+By default the clean command keeps the most 3 recent docker images. If you would like to override this setting you can use the `--keep` option. Example:
+
+    ufo docker clean tongueroo/hi --keep 5
+
+
+## Options
+
+```
+[--keep=N]                 
+                           # Default: 3
+[--tag-prefix=TAG_PREFIX]  
+                           # Default: ufo
+```
+

data/docs/_reference/ufo-docker-help.md

@@ -0,0 +1,15 @@
+---
+title: ufo docker help
+reference: true
+---
+
+## Usage
+
+    ufo docker help [COMMAND]
+
+## Description
+
+Describe subcommands or one specific subcommand
+
+
+

data/docs/_reference/ufo-docker-name.md

@@ -0,0 +1,37 @@
+---
+title: ufo docker name
+reference: true
+---
+
+## Usage
+
+    ufo docker name
+
+## Description
+
+Display the full docker image with tag that was last generated.
+
+It is sometimes handy to grab the name of the Docker image that was just generated.  Let's say ou needed the image name so you can feed it into another script that you have. The command `ufo docker name` returns the image of the most recently built Docker image.
+
+## Examples
+
+    ufo docker build # stores the docker image name in the .ufo/data folder
+    ufo docker name  # fetches image name from .ufo/data folder
+
+An example image name would look something like this: `tongueroo/hi:ufo-2018-02-15T19-29-06-88071f5`
+
+Note, the `.ufo/data` folder is an internal data folder and it's structure can change in future releases.
+
+If you want to generate a brand new name for whatever purpose, you can use the `--generate` flag.  The generate does not write to the `.ufo/data` folder.  It only generates a fresh name to stdout.  If you run it multiple times, it will generate new names.  You can notice this by seeing that the timestamp will always update:
+
+    ufo docker name --generate  # example: tongueroo/hi:ufo-2018-02-15T10-00-00-88071f5
+    ufo docker name --generate  # example: tongueroo/hi:ufo-2018-02-15T10-00-08-88071f5
+    ufo docker name --generate  # example: tongueroo/hi:ufo-2018-02-15T10-00-16-88071f5
+
+
+## Options
+
+```
+[--generate], [--no-generate]  # Generate a name without storing it
+```
+

data/docs/_reference/ufo-docker-push.md

@@ -0,0 +1,49 @@
+---
+title: ufo docker push
+reference: true
+---
+
+## Usage
+
+    ufo docker push IMAGE
+
+## Description
+
+Push the docker image.
+
+
+The `ufo docker push` command pushes the most recent Docker image built by `ufo docker build` to a registry.  This command pushes a docker image up to the registry.  By default it pushes the last image that was built with `ufo docker build`.  To see what the image name is you can run `ufo docker name`. Example:
+
+    ufo docker build # to build the image
+    ufo docker name  # to see the image name
+    ufo docker push  # push up the registry
+
+You'll see that `ufo docker push` simply shells out and calls `docker push`:
+
+    $ ufo docker push
+    => docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/hi:ufo-2018-02-13T10-51-44-e0cc7be
+    The push refers to a repository [123456789.dkr.ecr.us-east-1.amazonaws.com/hi]
+    399c739c257d: Layer already exists
+    ...
+    Pushed 123456789.dkr.ecr.us-east-1.amazonaws.com/hi:ufo-2018-02-13T10-51-44-e0cc7be docker image. Took 1s.
+    $
+
+You can also push up a custom image by specifying the image name as the first parameter.
+
+    ufo docker push my/image:tag
+
+You could also use the `--push` flag as part of the `ufo docker build` command to achieve the same thing as `ufo docker push`. The `ufo docker push` command might be more intutitive.
+
+    ufo docker build --push # same as above
+
+## Docker Authorization
+
+Note in order to push the image to a registry you will need to login into the registry.  If you are using DockerHub use the `docker login` command.  If you are using AWS ECR then, ufo will automatically try to authorize you and configure your `~/.docker/config.json`.  If can also use `aws ecr get-login` command.
+
+
+## Options
+
+```
+[--push], [--no-push]  
+```
+

data/docs/_reference/ufo-docker.md

@@ -0,0 +1,35 @@
+---
+title: ufo docker
+reference: true
+---
+
+## Usage
+
+    ufo docker SUBCOMMAND
+
+## Description
+
+docker subcommands
+
+## Examples
+
+    ufo docker build
+    ufo docker tag
+
+## Subcommands
+
+* [ufo docker base]({% link _reference/ufo-docker-base.md %}) - Build docker image from `Dockerfile.base` and update current `Dockerfile`.
+* [ufo docker build]({% link _reference/ufo-docker-build.md %}) - Build docker image.
+* [ufo docker clean]({% link _reference/ufo-docker-clean.md %}) - Clean up old images. Keeps a specified amount.
+* [ufo docker name]({% link _reference/ufo-docker-name.md %}) - Display the full docker image with tag that was last generated.
+* [ufo docker push]({% link _reference/ufo-docker-push.md %}) - Push the docker image.
+
+## Options
+
+```
+[--verbose], [--no-verbose]  
+[--mute], [--no-mute]        
+[--noop], [--no-noop]        
+[--cluster=CLUSTER]          # Cluster.  Overrides ufo/settings.yml.
+```
+

data/docs/_reference/ufo-init.md

@@ -0,0 +1,74 @@
+---
+title: ufo init
+reference: true
+---
+
+## Usage
+
+    ufo new --app=APP --image=IMAGE
+
+## Description
+
+Set up initial ufo files.
+
+The `ufo init` command provides a way to quickly setup a project to be ufo ready. It creates a ufo folder with all the starter supporting files in order to use ufo.  This page demonstrates how to use `ufo init`.  The command requires these options: `--app` and `--image`.
+
+## Examples
+
+For this example we will use [tongueroo/hi](https://github.com/tongueroo/hi) which is a small test sinatra app.  Let's run the command in our newly clone project.
+
+    $ git clone https://github.com/tongueroo/hi.git
+    $ cd hi
+    $ ufo init --app=hi --image=tongueroo/hi
+    Setting up ufo project...
+          create  .ufo/settings.yml
+          create  .ufo/task_definitions.rb
+          create  .ufo/templates/main.json.erb
+          create  .ufo/variables/base.rb
+          create  .ufo/variables/development.rb
+          create  .ufo/variables/production.rb
+          create  Dockerfile
+          create  bin/deploy
+          append  .gitignore
+    Starter ufo files created.
+
+## Options: app and image
+
+The `app` is that application name that you want to show up on the ECS dashboard.  It is encouraged to have the app name be a single word.
+
+The `image` is the base portion of image name that will be pushed to the docker registry, ie: DockerHub or AWS ECR.  The image should **not** include the tag since the tag is generated upon a `ufo ship`.  For example:
+
+    tongueroo/hi => tongueroo/hi:ufo-2018-02-08T21-04-02-3c86158
+
+The generated `tongueroo/hi:ufo-2018-02-08T21-04-02-3c86158` image name gets pushed to the docker registry.
+
+## Directory Structure
+
+The standard directory structure of the `.ufo` folder that was created looks like this:
+
+    ufo
+    ├── output
+    ├── settings.yml
+    ├── task_definitions.rb
+    ├── templates
+    ├   └── main.json.erb
+    └── variables
+        ├── base.rb
+        ├── production.rb
+        └── development.rb
+
+For a explanation of the folders and files refer to [Structure]({% link _docs/structure.md %}).
+
+
+## Options
+
+```
+[--force]                    # Bypass overwrite are you sure prompt for existing files.
+--image=IMAGE                # Docker image name without the tag. Example: tongueroo/hi. Configures ufo/settings.yml
+--app=APP                    # App name. Preferably one word. Used in the generated ufo/task_definitions.rb.
+[--verbose], [--no-verbose]  
+[--mute], [--no-mute]        
+[--noop], [--no-noop]        
+[--cluster=CLUSTER]          # Cluster.  Overrides ufo/settings.yml.
+```
+

data/docs/_reference/ufo-scale.md

@@ -0,0 +1,30 @@
+---
+title: ufo scale
+reference: true
+---
+
+## Usage
+
+    ufo scale SERVICE COUNT
+
+## Description
+
+Scale the ECS service.
+
+Ufo provides a command to scale up and down an ECS service quickly. It is a simple wrapper for `aws ecs update-service --service xxx ----desired-count xxx`.  Here's an example of how you use it:
+
+    $ ufo scale hi-web 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.
+
+
+## Options
+
+```
+[--verbose], [--no-verbose]  
+[--mute], [--no-mute]        
+[--noop], [--no-noop]        
+[--cluster=CLUSTER]          # Cluster.  Overrides ufo/settings.yml.
+```
+

data/docs/_reference/ufo-ship.md

@@ -0,0 +1,100 @@
+---
+title: ufo ship
+reference: true
+---
+
+## Usage
+
+    ufo ship SERVICE
+
+## Description
+
+Builds and ships container image to the ECS service.
+
+The main command you use when using ufo is: `ufo ship`.  This command:
+
+1. builds the docker image
+2. registers the generated ECS task definition
+3. deploys the definition to AWS ECS
+
+Basic usage is:
+
+    ufo ship hi-web
+
+The ECS service gets created if the service does not yet exist on the cluster.
+
+### Conventions
+
+By convention the task and service names match. If you need override to this convention then you can specific the task.  For example if you want to ship to the `hi-web-1` service and use the `hi-web` task, run:
+
+    ufo ship hi-web-1 --task hi-web
+
+## Options in Detail
+
+The command has a decent amount of options, you can see the options available with `ufo ship -h`.  The table below covers some of the options in detail:
+
+{% include ufo-ship-options.md %}
+
+As you can see there are plenty of options for `ufo ship`.  Let's demonstrate usage of them in a few examples.
+
+### Load Balancer Target Group
+
+When you are deploying to a service with the word 'web' in it, ufo 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.  The deploy will prompt you for the ELB `--target-group`  if the ECS does not yet exist.  For non-web container 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.
+
+    ufo ship hi-web --no-target-group-prompt
+
+Or if you would like to specify the target-group upfront and not be bother with the prompted later you can use the `--target-group` option.
+
+    ufo ship hi-web --target-group=arn:aws:elasticloadbalancing:us-east-1:12345689:targetgroup/hi-web/12345
+
+### Deploying Task Definition without Docker Build
+
+Let's you want skip the docker build phase and only want use ufo to deploy a task definition. You can do this with the `ufo deploy` command.  Refer to [ufo deploy](http://ufoships.com/reference/ufo-deploy/) for more info.
+
+### Waiting for Deployments to Complete
+
+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
+
+    ufo ship hi-web --wait
+
+You should see output similar to this:
+
+    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!
+
+### Cleaning up Docker Images Automatically
+
+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.
+
+    docker ship hi-web --ecr-keep 2
+
+You should see something like this:
+
+    Cleaning up docker images...
+    Running: docker rmi tongueroo/hi:ufo-2017-06-12T06-46-12-a18aa30
+
+If you are using DockerHub or another registry, ufo does not automatically clean up images.
+
+
+## Options
+
+```
+[--task=TASK]                                        # ECS task name, to override the task name convention.
+[--target-group=TARGET_GROUP]                        # ELB Target Group ARN.
+[--target-group-prompt], [--no-target-group-prompt]  # Enable Target Group ARN prompt
+                                                     # Default: true
+[--wait], [--no-wait]                                # Wait for deployment to complete
+[--pretty], [--no-pretty]                            # Pretty format the json for the task definitions
+                                                     # Default: true
+[--stop-old-tasks], [--no-stop-old-tasks]            # Stop old tasks after waiting for deploying to complete
+[--ecr-keep=N]                                       # ECR specific cleanup of old images.  Specifies how many images to keep.  Only runs if the images are ECR images. Defaults keeps all images.
+[--verbose], [--no-verbose]                          
+[--mute], [--no-mute]                                
+[--noop], [--no-noop]                                
+[--cluster=CLUSTER]                                  # Cluster.  Overrides ufo/settings.yml.
+```
+

data/docs/_reference/ufo-ships.md

@@ -0,0 +1,77 @@
+---
+title: ufo ships
+reference: true
+---
+
+## Usage
+
+    ufo ships [LIST_OF_SERVICES]
+
+## Description
+
+Builds and ships same container 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:
+
+1. web - serves web requests.
+2. worker - processes background jobs.
+3. clock - schedules background jobs.
+
+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:
+
+    ufo ships hi-web hi-worker hi-clock
+
+## Shell expansion
+
+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 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
+
+
+## Options
+
+```
+[--task=TASK]                                        # ECS task name, to override the task name convention.
+[--target-group=TARGET_GROUP]                        # ELB Target Group ARN.
+[--target-group-prompt], [--no-target-group-prompt]  # Enable Target Group ARN prompt
+                                                     # Default: true
+[--wait], [--no-wait]                                # Wait for deployment to complete
+[--pretty], [--no-pretty]                            # Pretty format the json for the task definitions
+                                                     # Default: true
+[--stop-old-tasks], [--no-stop-old-tasks]            # Stop old tasks after waiting for deploying to complete
+[--ecr-keep=N]                                       # ECR specific cleanup of old images.  Specifies how many images to keep.  Only runs if the images are ECR images. Defaults keeps all images.
+[--verbose], [--no-verbose]                          
+[--mute], [--no-mute]                                
+[--noop], [--no-noop]                                
+[--cluster=CLUSTER]                                  # Cluster.  Overrides ufo/settings.yml.
+```
+