ufo ship


ufo ship SERVICE


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.


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:

Option Description
--task By convention ufo uses the same name for both the ECS service and task definition. You can override this convention with this option. The conventions are covered on the Conventions page.
--target-group The ELB target group to use for the ECS service. This is respected if the ECS service is being created the first time. If the ECS service already exists, this option gets ignored.
--target-group-prompt This boolean option allows you to bypass setting the ELB target group if desired.
--wait This boolean option determines if ufo blocks and waits until the service has been deployed before continuing.
--pretty This boolean option determines ufo generates the task definitions in output in a pretty human readable format.
--stop-old-tasks This boolean option determines if ufo will call ecs stop-task on the old tasks after deployment. Sometimes old tasks hang around for a little bit with ECS this forces them along a little quicker.
--ecr-keep This integer option determines how many old docker images to keep around. Ufo will automatically delete and clean up docker images at the end of this process. The default is reasonable large at 30.
--cluster This decides what cluster to use. This can also be set in ufo/settings.yml covered in Settings. The cli option takes highest precedence.

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 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 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.


[--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.

Edit this page

See a typo or an error? You can improve this page. This website is available on GitHub and contributions are encouraged and welcomed. We love pull requests from you!