ufo 3.5.7 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a92a1e685c66f63854b015ea62abb3be7f54c3af1b2cf68ca9505b414fe8978c
-  data.tar.gz: 125983ffbc6084d126f05a684763b1ceeab38730eb2ea8cb778e662dbe9db7b7
+  metadata.gz: 46e9fa39991b473e75366ff36d1242c58f1047235b104adf162391cc474e62ed
+  data.tar.gz: b25f887523643b7a3d0989c252c5d2aa6331ecc115d4ca40867b152c146d278e
 SHA512:
-  metadata.gz: 912de3bf9af0666505868a5d7d3f12b42834a1a6116cf5175e37f6d169d9e67a2a2a264f42aebee194680522f76737f286751412d693e4825a9c53b50ffd1e23
-  data.tar.gz: 14118ce031dccaf4488c4762b582f53ad7d6cf8c304ddff81b1f2305e3bce88f83ba4c55085306e1366c9cef5e21b3d982d2a9dad969269b0f01695aae456b98
+  metadata.gz: 6073c2fe4317cde44b9e79591d40d4146ecf1c647d5e6510b6ba05a63edf0c1b73add68c7210df8820fdb6ccabf33fa4bf17ffc20ec818d0a47bc10d2b38cf41
+  data.tar.gz: db44342f65e164817149609fac6316d8e9262e79a7f3d80c4152c322ebb03dd2b1818dce3deef059aa6b1045c23efcf6965a53860043f3a142a76faa3eaecf37

data/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to this project will be documented in this file.
 This project *tries* to adhere to [Semantic Versioning](http://semver.org/), even before v1.0.
 
+## [4.0.0-prelease]
+- Major architecture changes
+- Fuller CLI Toolkit Commands
+- Load Balancer Support
+- Updated Tutorial Guide
+- Security Groups
+- Improved Fargate Support
+- Extra Env Support
+- CloudFormation Implementation
+- Upgrade Guide
+- ECS service created by CloudFormation now
+- ELB support: both application and network ELBs
+- Route53 support: associates ELB with DNS record
+- UFO_ENV_EXTRA concept introduced
+- Many additional CLI commands:
+- ufo apps
+- ufo cancel
+- ufo current
+- ufo network
+- ufo ps
+- ufo releases
+- ufo resources
+- ufo rollback
+
 ## [3.5.7]
 - display aws ecs run-task command
 - fix ufo init in help menu

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    ufo (3.5.5)
+    ufo (4.0.0)
+      aws-sdk-cloudformation
       aws-sdk-cloudwatchlogs
       aws-sdk-ec2
       aws-sdk-ecr
@@ -12,6 +13,7 @@ PATH
       memoist
       plissken
       render_me_pretty
+      text-table
       thor
 
 GEM
@@ -22,29 +24,32 @@ GEM
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
-    aws-eventstream (1.0.0)
-    aws-partitions (1.87.0)
-    aws-sdk-cloudwatchlogs (1.3.0)
+    aws-eventstream (1.0.1)
+    aws-partitions (1.95.0)
+    aws-sdk-cloudformation (1.6.0)
       aws-sdk-core (~> 3)
       aws-sigv4 (~> 1.0)
-    aws-sdk-core (3.21.2)
+    aws-sdk-cloudwatchlogs (1.4.0)
+      aws-sdk-core (~> 3)
+      aws-sigv4 (~> 1.0)
+    aws-sdk-core (3.22.1)
       aws-eventstream (~> 1.0)
       aws-partitions (~> 1.0)
       aws-sigv4 (~> 1.0)
       jmespath (~> 1.0)
-    aws-sdk-ec2 (1.34.0)
+    aws-sdk-ec2 (1.37.0)
       aws-sdk-core (~> 3)
       aws-sigv4 (~> 1.0)
-    aws-sdk-ecr (1.3.0)
+    aws-sdk-ecr (1.4.0)
       aws-sdk-core (~> 3)
       aws-sigv4 (~> 1.0)
-    aws-sdk-ecs (1.13.0)
+    aws-sdk-ecs (1.15.0)
       aws-sdk-core (~> 3)
       aws-sigv4 (~> 1.0)
-    aws-sdk-elasticloadbalancingv2 (1.9.0)
+    aws-sdk-elasticloadbalancingv2 (1.11.0)
       aws-sdk-core (~> 3)
       aws-sigv4 (~> 1.0)
-    aws-sigv4 (1.0.2)
+    aws-sigv4 (1.0.3)
     byebug (10.0.2)
     cli_markdown (0.1.0)
     codeclimate-test-reporter (1.0.8)
@@ -84,6 +89,7 @@ GEM
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.2)
+    text-table (1.2.4)
     thor (0.20.0)
     thread_safe (0.3.6)
     tilt (2.0.8)

data/README.md

@@ -8,7 +8,7 @@
 [![Join the chat at https://gitter.im/tongueroo/ufo](https://badges.gitter.im/tongueroo/ufo.svg)](https://gitter.im/tongueroo/ufo?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 [![Support](https://img.shields.io/badge/get-support-blue.svg)](https://boltops.com?utm_source=badge&utm_medium=badge&utm_campaign=ufo)
 
-Ufo is an tool that eases the building and deployment of docker images to [AWS ECS](https://aws.amazon.com/ecs/).  The main command is `ufo ship`.  Here's summary of what it does:
+Ufo is a tool that eases the building and deployment of Docker images to [AWS ECS](https://aws.amazon.com/ecs/).  The main command is `ufo ship`.  Here's summary of what it does:
 
 1. Builds a docker image. 
 2. Generates and registers the ECS template definition. 
@@ -20,30 +20,29 @@ See [ufoships.com](http://ufoships.com) for full documentation.
 
 ## Important
 
-If you are on version 2, you can run `ufo upgrade3` within your project to upgrade it to version 3.  Refer to the [CHANGELOG](CHANGELOG.md).
+If you are on version 3, you can run `ufo upgrade v3to4` within your project to upgrade it to version 4.  Refer to the [CHANGELOG](CHANGELOG.md).
 
 ## Installation
 
-```sh
-gem install ufo
-```
+    gem install ufo
 
 Full installation instructions are at [Install Ufo](http://ufoships.com/docs/install/).
 
 ## Quick Start
 
-To quickly demonstrate how simple it is to use ufo we will use an example app from [tongueroo/hi](https://github.com/tongueroo/ufo).  The app is a barebones sinatra app.  Here are the steps:
+To quickly demonstrate how simple it is to use ufo we will use an example app from [tongueroo/demo-ufo](https://github.com/tongueroo/demo-ufo).  The app is a barebones sinatra app.  Here are the steps:
 
-```sh
-gem install ufo
-git clone https:///github.com/tongueroo/hi.git
-cd hi
-ufo init --app=hi --image=tongueroo/hi
-ufo ship hi-web
-```
+    gem install ufo
+    git clone https:///github.com/tongueroo/demo-ufo.git demo
+    cd demo
+    ufo init --app=demo --image=tongueroo/demo-ufo
+    ufo ship demo-web
 
 Congratulations, you have successfully used ufo to deploy to an ECS service.
 
+## Load Balancer Support
+
+Ufo can also create a load balancer as part of creating the ECS service if you wish. Underneath the hood, ufo uses CloudFormation to create the load balancer.  More information can be found at the [load balancer support docs](http://ufoships.com/docs/load-balancer/).
 
 ## Articles
 

data/docs/_config.yml

@@ -2,7 +2,7 @@
 title: Ufo
 email: tongueroo@gmail.com
 url: http://ufoships.com
-description: "Easy Way to Build and Ship Docker Images to AWS ECS"
+description: "AWS ECS Deployment Tool"
 keywords: "AWS EC2 Container Service, AWS ECS, UFO, Deploy to ECS, ufo ship"
 skills: ""
 meta_author: Tung Nguyen

data/docs/_docs/auto-completion.md

@@ -15,8 +15,8 @@ Auto Completion examples:
 ```
 ufo [TAB]
 ufo ship [TAB]
-ufo ship hi-web [TAB]
-ufo ship hi-web --[TAB]
+ufo ship demo-web [TAB]
+ufo ship demo-web --[TAB]
 ufo ship --[TAB]
 ufo docker [TAB]
 ufo docker build [TAB]
@@ -24,6 +24,6 @@ ufo tasks [TAB]
 ufo tasks build [TAB]
 ```
 
-<a id="prev" class="btn btn-basic" href="{% link _docs/conventions.md %}">Back</a>
-<a id="next" class="btn btn-primary" href="{% link _docs/run-in-pieces.md %}">Next Step</a>
+<a id="prev" class="btn btn-basic" href="{% link _docs/automated-cleanup.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link articles.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/automated-cleanup.md

@@ -11,5 +11,5 @@ ecr_keep: 30
 Automated Docker images clean up only works if you are using ECR registry.
 
 <a id="prev" class="btn btn-basic" href="{% link _docs/migrations.md %}">Back</a>
-<a id="next" class="btn btn-primary" href="{% link _docs/next-steps.md %}">Next Step</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/auto-completion.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/conventions.md

@@ -13,7 +13,7 @@ By default, the ECS cluster value is the same as UFO_ENV's value.  So if `UFO_EN
 Ufo assumes a convention that service\_name and the task\_name are the same. If you would like to override this convention, then you can specify the task name.
 
 ```
-ufo ship hi-web --task my-task
+ufo ship demo-web --task my-task
 ```
 
 This means that in the task_definition.rb you will also define it with `my-task`.  For example:
@@ -29,20 +29,20 @@ end
 
 ```
 
-## Web Role Convention
+## Web Service Load Balancer Convention
 
-By convention, if the service has a container named "web", you'll get prompted to create an ELB and specify a target group ARN.  If you would like to name a service with the word "web" in it without having to use an ELB target group then you can use the `--no-target-group-prompt`.  Example:
+By convention, if the service has a container named "web", ufo will automatically create an ELB.  If you would like to name a service with the word "web" without an ELB, specify `--elb false`.  Example:
 
 ```sh
-ufo ship hi-web --no-target-group-prompt
+ufo ship demo-web --elb false
 ```
 
-You can also bypass the prompt by specifying the target group ARN as part of the command upfront. The ELB and target group must already exist.  The ELB target group only gets associated when the service gets created for the first time.  If the service already exists then the `--target-group` parameter just gets ignored and the ECS task simply gets updated.  Example:
+You can also use an existing ELB by specifying the target group arn as the value of the `--elb` option. Example:
 
 ```bash
-ufo ship hi-web --target-group=arn:aws:elasticloadbalancing:us-east-1:12345689:targetgroup/hi-web/12345
+ufo ship demo-web --elb arn:aws:elasticloadbalancing:us-east-1:12345689:targetgroup/demo-web/12345
 ```
 
 <a id="prev" class="btn btn-basic" href="{% link _docs/helpers.md %}">Back</a>
-<a id="next" class="btn btn-primary" href="{% link _docs/auto-completion.md %}">Next Step</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/fargate.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/customize-cloudformation.md

@@ -0,0 +1,36 @@
+---
+title: Customize CloudFormation
+---
+
+Under the hood, ufo creates most of the required resources with a CloudFormation stack.  This includes the ELB, Target Group, Listener, Security Groups, ECS Service, and Route 53 records.  You might need to customize these resources.  Here are the ways to customize the resources that ufo creates.
+
+1. Settings - This is done with the `.ufo/settings/cfn/default.yml` file. This is the main and recommended way to customize.
+2. Override cfn template - You can specify your own template to use.  You save this template at `.ufo/settings/cfn/stack.yml`. Use this approach as a last resort only when necessary.
+
+## Settings
+
+The recommended approach to customize the CloudFormation resources is by adding properties to `.ufo/settings/cfn/default.yml`.
+
+{% include cfn-customize.md %}
+
+## Override Cfn Template
+
+You can override the source template that ufo uses by creating your own and saving it at `.ufo/settings/cfn/stack.yml` in your project. It is recommended that you copy the source code and work from there [cfn/stack.yml](https://github.com/tongueroo/ufo/blob/master/lib/cfn/stack.yml).  Use this approach as a last resort only when absolutely necessary as it'll likely break with a future version of ufo.
+
+## CloudFormation Stack Name
+
+The CloudFormation stack name is based on the cluster, service name and UFO_ENV_EXTRA.  A few examples help demonstrate:
+
+Command | Stack Name
+--- | ---
+ufo ship demo-web | development-demo-web
+ufo ship demo-web -\-cluster dev | dev-demo-web
+UFO_ENV_EXTRA=2 ufo ship demo-web -\-cluster dev | development-demo-web-2
+
+## CloudFormation Stack Source Code
+
+The CloudFormation stack is currently generated from a template. The source code for this template is located at [cfn/stack.yml](https://github.com/tongueroo/ufo/blob/master/lib/cfn/stack.yml).  This implementation might change in the future.
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/why-cloudformation.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/stuck-cloudformation.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/faq.md

@@ -7,10 +7,12 @@ title: FAQ
 Yes, Fargate is supported.  To use ufo with Fargate, you will need to adjust the template in `.ufo/templates` to a structure supported by Fargate.  There are 2 key items to adjust:
 
 1. The task definition JSON. Notably, the JSON structure has the `requiresCompatibilities`, `networkMode`, and `executionRoleArn` attributes. The `cpu` and `memory` attributes also move outside of the `containerDefinitions` level to the top-level attributes. For details on how to adjust the task definition refer to [Task Definitions]({% link _docs/tutorial-ufo-tasks-build.md %}).
-2. The params that get sent to the `create_service` or  `run_task` API methods. For details on how to adjust the params refer to [Params]({% link _docs/params.md %})
+2. The params that get sent to the `run_task` API methods. For details on how to adjust the params refer to [Params]({% link _docs/params.md %})
 
 If it's a brand new project, you can use `ufo init` with the `--launch-type fargate` option and it will generate a starter task definition JSON file that has the right Fargate structure. More info is available at [ufo init reference](/reference/ufo-init/#fargate-support).
 
+A quick and easy way to test fargate is to follow the [Fargate Docs]({% link _docs/fargate.md %}) which provides a demo example.
+
 **Q: Can I tell ufo to use specific docker build options?**
 
 Yes, you can do this with the environment variable `UFO_DOCKER_BUILD_OPTIONS`.  Example:
@@ -18,9 +20,9 @@ Yes, you can do this with the environment variable `UFO_DOCKER_BUILD_OPTIONS`.
 ```
 $ UFO_DOCKER_BUILD_OPTIONS="--build-arg RAILS_ENV=production" ufo docker build
 Building docker image with:
-  docker build --build-arg RAILS_ENV=production -t tongueroo/hi:ufo-2018-05-19T11-52-16-6714713 -f Dockerfile .
+  docker build --build-arg RAILS_ENV=production -t tongueroo/demo-ufo:ufo-2018-05-19T11-52-16-6714713 -f Dockerfile .
 ...
-Docker image tongueroo/hi:ufo-2018-05-19T11-52-16-6714713 built.  Took 2s.
+Docker image tongueroo/demo-ufo:ufo-2018-05-19T11-52-16-6714713 built.  Took 2s.
 ```
 
 ---
@@ -32,11 +34,11 @@ In short, no. There's some image cleanup logic that relies on the specific namin
 ```
 $ ufo docker build
 $ ufo docker name
-tongueroo/hi:ufo-2018-05-19T11-41-06-6714713
+tongueroo/demo-ufo:ufo-2018-05-19T11-41-06-6714713
 $ docker tag $(ufo docker name) hi:mytag
 $ docker images | grep hi
 hi                                                     mytag                              5b01e38bd060        3 minutes ago       955MB
-tongueroo/hi                                           ufo-2018-05-19T11-41-06-6714713    5b01e38bd060        3 minutes ago       955MB
+tongueroo/demo-ufo                                           ufo-2018-05-19T11-41-06-6714713    5b01e38bd060        3 minutes ago       955MB
 $ docker push hi:mytag
 ```
 
@@ -94,6 +96,6 @@ Also, you might have to enable the log driver by adding the ECS_AVAILABLE_LOGGIN
 
 Hope that helps.
 
-<a id="prev" class="btn btn-basic" href="{% link _docs/next-steps.md %}">Back</a>
-<a id="next" class="btn btn-primary" href="{% link articles.md %}">Next Step</a>
+<a id="prev" class="btn btn-basic" href="{% link _docs/route53-support.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/why-cloudformation.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/fargate.md

@@ -0,0 +1,102 @@
+---
+title: Fargate
+---
+
+Ufo supports Fargate.  AWS Fargate is a technology for Amazon ECS that allows you to run containers without having to manage servers or clusters.  This provides an interesting "serverless" option for running Docker containers on AWS.
+
+## Fargate Example
+
+Here's an example of creating web service with Fargate.
+
+    git clone https://github.com/tongueroo/demo-ufo
+    cd demo-ufo
+    ufo init --image tongueroo/demo-ufo --app demo --force --launch-type fargate --execution-role-arn arn:aws:iam::123456789012:role/ecsTaskExecutionRole
+    ufo current --service demo-web
+    ufo ship
+
+Replace the `--execution-role-arn` with the ecsTaskExecutionRole associated with your account. If you do not have an ecsTaskExecutionRole yet, create one by following [Amazon ECS Task Execution IAM Role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_execution_IAM_role.html) guide.
+
+You should see output similiar to this. Some output has been removed for conciseness.
+
+    $ ufo ship
+    Building docker image with:
+      docker build -t tongueroo/demo-ufo:ufo-2018-06-29T22-54-07-20b3a10 -f Dockerfile .
+    ...
+    10:58:38PM CREATE_COMPLETE AWS::ECS::Service Ecs
+    10:58:40PM CREATE_COMPLETE AWS::CloudFormation::Stack development-demo-web
+    Stack success status: CREATE_COMPLETE
+    Time took for stack deployment: 4m 24s.
+    Software shipped!
+    $
+
+### Verification ufo commands
+
+You can verify that service with these ufo commands.
+
+    $ ufo ps
+    => Service: demo-web
+       Service name: development-demo-web-Ecs-1LMRH98Y352F7
+       Status: ACTIVE
+       Running count: 1
+       Desired count: 1
+       Launch type: FARGATE
+       Task definition: demo-web:84
+       Elb: develop-Elb-BNIP29PG593M-771779085.us-east-1.elb.amazonaws.com
+    +----------+------+-------------+---------------+---------+-------+
+    |    Id    | Name |   Release   |    Started    | Status  | Notes |
+    +----------+------+-------------+---------------+---------+-------+
+    | 78e02265 | web  | demo-web:84 | 2 minutes ago | RUNNING |       |
+    +----------+------+-------------+---------------+---------+-------+
+    $ ufo scale 2
+    Scale demo-web service in development cluster to 2
+    $ ufo ps --no-summary
+    +----------+------+-------------+---------------+---------+-------+
+    |    Id    | Name |   Release   |    Started    | Status  | Notes |
+    +----------+------+-------------+---------------+---------+-------+
+    | 78e02265 | web  | demo-web:84 | 2 minutes ago | RUNNING |       |
+    +----------+------+-------------+---------------+---------+-------+
+    $ ufo ps --no-summary
+    +----------+------+-------------+---------------+---------+-------+
+    |    Id    | Name |   Release   |    Started    | Status  | Notes |
+    +----------+------+-------------+---------------+---------+-------+
+    | 02b78575 | web  | demo-web:84 | PENDING       | PENDING |       |
+    | 78e02265 | web  | demo-web:84 | 2 minutes ago | RUNNING |       |
+    +----------+------+-------------+---------------+---------+-------+
+    $ ufo ps --no-summary
+    +----------+------+-------------+----------------+---------+-------+
+    |    Id    | Name |   Release   |    Started     | Status  | Notes |
+    +----------+------+-------------+----------------+---------+-------+
+    | 02b78575 | web  | demo-web:84 | 12 seconds ago | RUNNING |       |
+    | 78e02265 | web  | demo-web:84 | 3 minutes ago  | RUNNING |       |
+    +----------+------+-------------+----------------+---------+-------+
+    $
+
+### Verification curl
+
+You can verify that the app is up and running curling the ELB DNS.
+
+    $ curl develop-Elb-BNIP29PG593M-771779085.us-east-1.elb.amazonaws.com ; echo
+    42
+    $
+
+Congratulations 🎉 You have successfully deployed an docker web service to "serverless" Fargate.
+
+## Clean up
+
+Remove the service to save costs.
+
+    $ ufo destroy
+    You are about to destroy demo-web service on the development cluster.
+    Are you sure you want to do this? (y/n) y
+    Deleting CloudFormation stack with ECS resources: development-demo-web.
+    11:05:40PM DELETE_IN_PROGRESS AWS::CloudFormation::Stack development-demo-web User
+    ...
+    11:07:51PM DELETE_COMPLETE AWS::EC2::SecurityGroup EcsSecurityGroup
+    Stack development-demo-web deleted.
+    $
+
+Here's an article that compares the cost of ECS Fargate: [Heroku vs ECS Fargate vs EC2 On-Demand vs EC2 Spot Pricing Comparison](https://blog.boltops.com/2018/04/22/heroku-vs-ecs-fargate-vs-ec2-on-demand-vs-ec2-spot-pricing-comparison)
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/conventions.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/ufo-env.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/helpers.md

@@ -4,13 +4,13 @@ title: Helpers
 
 The `task_definitions.rb` file has access to helper methods. These helper methods provide useful contextual information about the project.
 
-For example, one of the helper methods provides the exposed port in the Dockerfile of the project. This is useful if someone changes the exported port in the Dockerfile, he will likely forget to also update the ufo variable.  You can reference the port via the helper to prevent this from happening. Here is a list of the helpers:
+For example, one of the helper methods provides the exposed port in the Dockerfile of the project. This is useful if someone changes the exported port in the Dockerfile, he will likely forget also to update the ufo variable.  You can reference the port via the helper to prevent this from happening. Here is a list of the helpers:
 
 Helper  | Description
 ------------- | -------------
-full\_image\_name | The full docker image name that ufo builds. The "base" portion of the docker image name is defined in `settings.yml`. For example, the base portion is `tongueroo/hi` and the full image name is `tongueroo/hi:ufo-[timestamp]-[sha]`. The base name does not include the generated Docker tag, which contains a timestamp and git sha of the Dockerfile that is used.
+full\_image\_name | The full docker image name that ufo builds. The "base" portion of the docker image name is defined in `settings.yml`. For example, the base portion is `tongueroo/demo-ufo` and the full image name is `tongueroo/demo-ufo:ufo-[timestamp]-[sha]`. The base name does not include the generated Docker tag, which contains a timestamp and git sha of the project.
 dockerfile\_port | Exposed port extracted from the Dockerfile of the project. 
-env_vars(text) | This method takes a block of text that contains the env values in `key=value` format and converts that block of text to the proper task definition json format.
+env_vars(text) | This method takes a block of text that contains the env values in `key=value` format and converts that block of text to the proper task definition JSON format.
 env_file(path) | This method takes a `.env` file which contains a simple key-value list of environment variables and converts the list to the proper task definition JSON format.
 task_definition_name | The name of the task_definition.  So if the code looks like this `task_definition "demo-web" do`, the task_definition_name is "demo-web".
 

data/docs/_docs/load-balancer.md

@@ -0,0 +1,72 @@
+---
+title: Load Balancer Support
+---
+
+Ufo can automatically create a load balancer and associate it with an ECS service.  The options:
+
+1. Create an ELB.
+2. Use existing ELB by providing a target group arn.
+3. Do not create an ELB.
+
+## Examples
+
+Here are examples of each of them:
+
+    # Create an ELB
+    ufo ship demo-web --elb=true
+
+    # Use existing target group from pre-created ELB
+    ufo ship demo-web --elb=arn:aws:elasticloadbalancing:us-east-1:123456789:targetgroup/target-name/2378947392743
+
+    # Disable creating ELB
+    ufo ship demo-web --elb=false
+
+## ELB Retained
+
+Ufo retains the ELB setting.  So future `ufo ship` commands will not suddenly remove the load balancer.  If you need to change the elb setting, then you need to explicitly set a new `--elb` value.
+
+Important: Adding and removing load balancers will change the ELB DNS.  Please take pre-caution using the elb options.  This risk is mitigated if you have configured [Route53 support]({% link _docs/route53-support.md %}).
+
+## Web Service Convention
+
+By convention, if the container name is 'web' in the task definition. Deployments of new services will automatically create a load balancer.  The behavior can be disabled with `--elb=false` for web containers.
+
+    ufo ship demo-web --elb=false
+
+For non-web container the `--elb` option must be explicitly set to `--elb=true` if you want a load balancer to be created.
+
+## ELB Types: Application and Network
+
+Ufo supports application and network load balancer types.  To specify the type use `--elb-type`.  Examples:
+
+    ufo ship demo-web --elb-type network
+    ufo ship demo-web --elb-type application # default
+
+## ELB Static IP addresses for Network Load Balancers
+
+Network load balancers support static EIP address. You can create a network load balancer using pre-allocated EIP addresses with the the `--elb-eip-ids` option. Example:
+
+    ufo deploy demo-web --elb-eip-ids eipalloc-a8de9ca1 eipalloc-a8de9ca2
+
+If you use the `--elb-eip-ids` option, ufo assumes you want an `--elb-type=network` since only network load balancers support EIPs.
+
+When specifying the `--elb-eip-ids` option, the list length must be the same as the number of subnets configured in your `.ufo/settings/network/default.yml` profile.  The `--elb-eip-ids` setting is optional. If you do not specify it, a network load balancer will still be created.
+
+If you need to change the EIPs for existing services, you might get a "TargetGroup cannot be associated with more than one load balancer" error. To work around this you can set the env variable `UFO_FORCE_TARGET_GROUP=1` which will force a re-creation of the target group.
+
+    UFO_FORCE_TARGET_GROUP=1 ufo deploy demo-web --elb-eip-ids eipalloc-ac226fa4 eipalloc-b5206dbd
+
+To remove the EIPs but still keep the network load balancer, you can specify either:
+
+    UFO_FORCE_TARGET_GROUP=1 ufo deploy demo-web --elb-eip-ids ' ' --elb-type network
+    UFO_FORCE_TARGET_GROUP=1 ufo deploy demo-web --elb-eip-ids 'empty' --elb-type network
+
+## Load Balancer Implementation
+
+Under the hood, ufo implements load balancer support with CloudFormation. You can see these resources by visiting the CloudFormation console and clicking on the corresponding stack.  Here's an example:
+
+<img src="/img/docs/cloudformation-resources.png" class="doc-photo" />
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/ufo-current.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/security-groups.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>