ufo 3.5.7 → 4.0.0

data/docs/_docs/migrations.md

@@ -5,13 +5,13 @@ title: Database Migrations
 A common task is to run database migrations with newer code before deploying the code. This is easily achieved with the `ufo task` command. Here's an example:
 
 ```sh
-ufo task hi-web --command bundle exec rake db:migrate
+ufo task demo-web -c bundle exec rake db:migrate
 ```
 
 It is nice to wrap the commands in a wrapper script in case you have to do things like to load the environment.
 
 ```sh
-ufo task hi-web --command bin/migrate
+ufo task demo-web -c bin/migrate
 ```
 
 The `bin/migrate` script can look like this:

data/docs/_docs/next-steps.md

@@ -12,7 +12,7 @@ From here, there are a few resources that can help you continue along:
 
 Everyone can contribute to make ufo better, including the documentation. These docs are of the same ufo repo in the [docs folder](https://github.com/tongueroo/ufo/tree/master/docs). Please fork the project and open a pull request!  We love your pull requests. Contributions are encouraged and welcomed!
 
-<a id="prev" class="btn btn-basic" href="{% link _docs/automated-cleanup.md %}">Back</a>
-<a id="next" class="btn btn-primary" href="{% link _docs/faq.md %}">Next Step</a>
+<a id="prev" class="btn btn-basic" href="{% link articles.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link reference.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>
 

data/docs/_docs/params.md

@@ -7,61 +7,32 @@ Additionally, the params that ufo sends to the [ruby aws-sdk](https://docs.aws.a
 A starter project `.ufo/params.yml` file is generated as part of the `ufo init` command. Let's take a look at an example `params.yml`:
 
 ```yaml
-<%
-  # replace with actual values:
-  @subnets = ["subnet-111","subnet-222"]
-  @security_groups = ["sg-111"]
-%>
 # These params are passsed to the corresponding aws-sdk ecs client methods.
 # AWS Docs example: https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/ECS/Client.html#run_task-instance_method
 #
-# Comments left in as examples.
-# Uncomment launch_type and network_configuration sections to enable fargate.
+# The network helper provides access to the .ufo/settings/network/[PROFILE].yml
 #
-
-# ufo ship calls create_service when service doesnt exist
-create_service:
-  deployment_configuration:
-    maximum_percent: 200
-    minimum_healthy_percent: 100
-  desired_count: 1
-  # launch_type: "FARGATE"
-  # network_configuration:
-  #   awsvpc_configuration:
-  #     subnets: <%= @subnets.inspect %> # required
-  #     security_groups: <%= @security_groups.inspect %>
-  #     assign_public_ip: "ENABLED" # accepts ENABLED, DISABLED
-
-
-# ufo ship calls update_service when service already exists
-# update service is provide as an example below.  Though it is probably better
-# to not add any options to update_service if you are using the ECS console
-# to update these settings often.
-update_service:
+# More docs: http://ufoships.com/docs/params/
 
 # ufo task calls run_tasks
 run_task:
-  # launch_type: "FARGATE"
-  # network_configuration:
-  #   awsvpc_configuration:
-  #     subnets: <%= @subnets.inspect %> # required
-  #     security_groups: <%= @security_groups.inspect %>
-  #     assign_public_ip: "ENABLED" # accepts ENABLED, DISABLED
+  # network_configuration is required for FARGATE
+  network_configuration:
+    awsvpc_configuration:
+      subnets: <%= network[:ecs_subnets].inspect %> # required
+      security_groups: <%= network[:ecs_security_groups].inspect %>
+      assign_public_ip: "ENABLED" # accepts ENABLED, DISABLED
 ```
 
 Ufo provides 1st class citizen access to adjust the params sent to the aws-sdk calls:
 
-* create_service - `ufo ship` calls this when the ECS service does not yet exist.
-* update_service - `ufo ship` calls this when the ECS service already exists.
-* run_task - `ufo task` calls this.
-
-The parameters from this `params.yml` file get merged with params ufo generates internally.  Here's an example of where the merging happens in the source code for the run task command [task.rb](https://github.com/tongueroo/ufo/blob/90f12df035843528770122deb328d150249a25e2/lib/ufo/task.rb#L20).  Also, here's the starter [params.yml source code](https://github.com/tongueroo/ufo/blob/master/lib/template/.ufo/params.yml) for reference.
+The parameters from this `params.yml` file get merged with params ufo generates internally.  Here's an example of where the merging happens in the source code for the run task command [task.rb](https://github.com/tongueroo/ufo/blob/master/lib/ufo/task.rb).  Also, here's the starter [params.yml source code](https://github.com/tongueroo/ufo/blob/master/lib/template/.ufo/params.yml.tt) for reference.
 
-ERB and [shared variables]({% link _docs/variables.md %}) are available in the params file.  Notice how ERB is used at the top of the example file to set some subnets to prevent duplication. You can also define the subnets in your config/variables and use them in them in the params.yml file.
+ERB and [shared variables]({% link _docs/variables.md %}) are available in the params file.  You can also define the subnets in your config/variables and use them in them in the params.yml file.
 
 NOTE: The params.yml file does not have access to the `task_definition_name` helper method. That is only available in the `task_definitions.rb` template_definition code blocks.
 
-<a id="prev" class="btn btn-basic" href="{% link _docs/settings.md %}">Back</a>
-<a id="next" class="btn btn-primary" href="{% link _docs/ufo-env.md %}">Next Step</a>
+<a id="prev" class="btn btn-basic" href="{% link _docs/settings-cfn.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/route53-support.md

@@ -0,0 +1,28 @@
+---
+title: Route53 Support
+---
+
+Ufo can create a "pretty" route53 record and set it's value to the created ELB DNS name. This is done by configuring the `.ufo/settings/cfn/default.yml` file. Example:
+
+```yaml
+dns:
+  name: "{stack_name}.mydomain.com."
+  hosted_zone_name: mydomain.com. # dont forget the trailing period
+```
+
+The `{stack_name}` variable gets substituted with the CloudFormation stack name launched by ufo. So for example:
+
+    ufo ship demo-web
+
+Results in:
+
+    "{stack_name}.mydomain.com." => "development-demo-web.mydomain.com."
+
+**IMPORTANT**: The route53 host zone must already exist. You can create route53 hosted zone with the cli like so:
+
+    aws route53 create-hosted-zone --name mydomain.com --caller-reference $(date +%s)
+    aws route53 list-hosted-zones
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/ssl-support.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/faq.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/run-in-pieces.md

@@ -27,11 +27,11 @@ ufo tasks register # registers all genreated task definitions .ufo/output to ECS
 Update the service with the task definitions in `.ufo/output` untouched.
 
 ```bash
-ufo deploy hi-web
+ufo deploy demo-web
 ```
 
 Note if you use the `ufo deploy` you should ensure that you have already pushed the docker image to your docker registry.  Or else the task will not be able to spin up because the docker image does not exist.  This is one of the reasons it is recommended that you use `ufo ship`.
 
-<a id="prev" class="btn btn-basic" href="{% link _docs/auto-completion.md %}">Back</a>
+<a id="prev" class="btn btn-basic" href="{% link _docs/upgrade4.md %}">Back</a>
 <a id="next" class="btn btn-primary" href="{% link _docs/single-task.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/security-groups.md

@@ -0,0 +1,54 @@
+---
+title: Security Groups
+---
+
+Ufo creates and manages two security groups. One for the ELB and one for the ECS tasks.
+
+Some consideration for these security groups:
+
+* Network load balancers do not support security groups. So an ELB security group is only created if the load balancer is an Application load balancer.
+* The ECS security group for tasks currently always gets created, but is only used if network_mode is awsvpc. This is because in bridge network mode the EC2 container instance’s Ethernet card and its security group is used. The EC2 containers group security group is outside the control of ufo. You’ll need to configure the security group appropriately yourself. Ufo will only assign the ECS security group when awsvpc node mode is used and ufo has control of the security group.
+
+## EC2 Instance Security Group Help
+
+If you are seeing that the Targets in the ELB Target Group are reporting unhealthy, it is usually a security group issue.  You might see this out with `ufo ps`:
+
+    $ ufo ps --no-summary
+    +----------+------+--------------+----------------+---------+-------------------------+
+    |    Id    | Name |   Release    |    Started     | Status  |          Notes          |
+    +----------+------+--------------+----------------+---------+-------------------------+
+    | 070a9c0a | web  | demo-web:169 | 6 minutes ago  | STOPPED | Failed ELB health check |
+    | d02728ba | web  | demo-web:169 | 3 minutes ago  | STOPPED | Failed ELB health check |
+    | 8dcf81ae | web  | demo-web:169 | 13 seconds ago | RUNNING |                         |
+    +----------+------+--------------+----------------+---------+-------------------------+
+    There are targets the target group reporting unhealthy.  This can cause containers to cycle. Here's the error:
+    (service development-demo-web-Ecs-13D2BFA4ULNC9) (instance i-0812a3bcd94babf12) (port 32779) is unhealthy in (target-group arn:aws:elasticloadbalancing:us-east-1:111111111111:targetgroup/devel-Targe-1MJR8V6VOWBGI/3f44f85710fe0297) due to (reason Request timed out)
+    Check out the ECS console events tab for more info.
+    $
+
+If you are using network mode bridge, then you'll need to need to configure the container instance's security group to allow traffic to the Docker ephemeral port range. For details on the Docker ephemeral port range on AWS, you search for "ephemeral" on the [ECS Port Mapping Docs](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_PortMapping.html).
+
+In general, ports below 32768 are outside of the ephemeral port range. So an easy way to configure the container instance's security group is to whitelist ports 32768 to 65535 to your VPC's CIDR block. An example of a CIDR block range could be `10.0.0.0/16`. The CIDR block is being suggested because the Application load balancer and security group created by ufo can change if you change the load balancer settings.
+
+If you are using a network load balancer and are running bridge network mode, then you need to whitelist ports 32768 to 65535 to `0.0.0.0/0`.  This is because network load balancers operate at layer 4 of the OSI model and cannot be assigned security groups, so they use the security group of the instance.  If you feel this is too loose of permissions, you can use awsvpc mode. There are some considerations for awsvpc mode though which is discussed next.
+
+## Pros and Cons: awsvpc vs bridge network mode
+
+With network bridge mode, the Docker containers of multiple services share the EC2 container instance's security group. So you have less granular control over opening ports for specific services only. For example, let’s say service A and B both are configured use bridge network mode. If you open up port 3000 for service A, it will also open up port 3000 for service B because they use the same security group at the EC2 instance level.
+
+One advantage of bridge mode is you can use dynamic port mapping and do not have to worry about network card limits.
+
+With awsvpc network mode, you must consider the limit of ethernet cards for the instance type. The table that lists the limits are under section the aws EC2 docs under [IP Addresses Per Network Interface Per Instance Type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) For example, a t2 large instance has a limit of 3 Ethernet cards. This means, at most, you can run 3 ECS tasks on that instance in awsvpc network mode.
+
+The advantage of awsvpc mode is that since the ECS task has its own network card and security group, there’s more granular control of the permissions per ECS service. For example, when service A and B are using awsvpc mode, they can have different security groups associated with them. In this mode, ufo creates a security group and sets up the permissions so the load balancer can talk to the containers.  You can also add additional security group to the `.ufo/settings/network/default.yml` config.
+
+The following table summarizes the pros and cons:
+
+Network mode | Pros | Cons
+--- | ---
+bridge | The numbers of containers you can run will not be limited due to EC2 instance network cards limits. | Less fine grain security control over security group permissions with multiple ECS services.
+awsvpc | Fine grain security group permissions for each ECS service. | The number of containers can be limited by the number of network cards the EC2 instance type supports.
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/load-balancer.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/ssl-support.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/settings-cfn.md

@@ -0,0 +1,11 @@
+---
+title: Settings Cfn
+---
+
+## Customizing Resources
+
+{% include cfn-customize.md %}
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/settings-network.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/params.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/settings-network.md

@@ -0,0 +1,34 @@
+---
+title: Settings Network
+---
+
+The settings.yml file references a network settings file with the `network_profile` option. This file has configurations that are related to the network.  The source code for the starter template file is at [network/default.yml.tt](https://github.com/tongueroo/ufo/blob/master/lib/template/.ufo/settings/network/default.yml.tt)  Here's an example network settings file.
+
+```
+---
+vpc: vpc-11111111
+ecs_subnets: # at least 2 subnets required
+  - subnet-11111111
+  - subnet-22222222
+elb_subnets: # defaults to same subnets as ecs_subnets when not set
+  - subnet-33333333
+  - subnet-44444444
+
+# Optional existing security group ids to add in addition to the ones created by ufo.
+# elb_security_groups:
+#   - sg-aaa
+# ecs_security_groups:
+#   - sg-bbb
+```
+
+Option | Description
+--- | ---
+vpc | Used to create ecs and elb security groups, target group in the CloudFormation template.
+ecs_subnets | Used to assign a subnet mapping to the ECS service created in CloudFormation when the network mode is awsvpc. Also used to in .ufo/params.yml as part of the run_task api call that is made by `ufo task`.
+elb_subnets | Used to create elb load balancer.
+ecs_security_groups | Additional security groups to associate with the ECS tasks.
+elb_security_groups | Additional security groups to associate with the ELB.
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/settings.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/settings-cfn.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/settings.md

@@ -2,7 +2,7 @@
 title: Settings
 ---
 
-The behavior of ufo can be configured with a `settings.yml` file.  A starter project `.ufo/settings.yml` file is generated as part of the `ufo init` command. You can have multiple settings files. The options from the files get merged and respected in the following precedence:
+The behavior of ufo can be configured with a `settings.yml` file.  A starter project `.ufo/settings.yml` file is generated as part of the `ufo init` command. There are can be multiple settings files. The options from the files get merged and respected in the following precedence:
 
 1. current folder - The current folder's `.ufo/settings.yml` values take the highest precedence.
 2. user - The user's `~/.ufo/settings.yml` values take the second highest precedence.
@@ -12,9 +12,11 @@ Let's take a look at an example `settings.yml`:
 
 ```yaml
 base:
-  image: tongueroo/hi
+  image: tongueroo/demo-ufo
   # clean_keep: 30 # cleans up docker images on your docker server.
   # ecr_keep: 30 # cleans up images on ECR and keeps this remaining amount. Defaults to keep all.
+  network_profile: default # .ufo/settings/network/default.yml file
+  cfn_profile: default # .ufo/settings/cfn/default.yml file
 
 development:
   # cluster: dev # uncomment if you want the cluster name be other than the default
@@ -37,11 +39,13 @@ The table below covers each setting:
 
 Setting  | Description
 ------------- | -------------
-`image`  | The `image` value is the name that ufo will use for the Docker image name to be built.  Only provide the basename part of the image name without the tag because ufo automatically generates the tag for you. For example, `tongueroo/hi` is correct and `tongueroo/hi:my-tag` is incorrect.
+`aws_profiles`  | If you have the `AWS_PROFILE` environment variable set, this will ensure that you are deploying the right `UFO_ENV` to the right AWS environment. It is explained below.
+`cfn_profile` | The name of the cfn profile settings file to use. Maps to .ufo/settings/cfn/NAME.yml file
 `clean_keep`  | Docker images generated from ufo are cleaned up automatically for you at the end of `ufo ship`. This controls how many docker images to keep around. The default is 3.
-`ecr_keep`  | If you are using AWS ECR, then the ECR images can also be automatically cleaned up at the end of `ufo ship`. By default this is set to `nil` and all AWS ECR are kept.
 `cluster`  | By convention, the ECS cluster that ufo deploys to matches the `UFO_ENV`. If `UFO=development`, then `ufo ship` deploys to the `development` ECS cluster. This is option overrides this convention.
-`aws_profiles`  | If you have the `AWS_PROFILE` environment variable set, this will ensure that you are deploying the right `UFO_ENV` to the right AWS
+`ecr_keep`  | If you are using AWS ECR, then the ECR images can also be automatically cleaned up at the end of `ufo ship`. By default this is set to `nil` and all AWS ECR are kept.
+`image`  | The `image` value is the name that ufo will use for the Docker image name to be built.  Only provide the basename part of the image name without the tag because ufo automatically generates the tag for you. For example, `tongueroo/demo-ufo` is correct and `tongueroo/demo-ufo:my-tag` is incorrect.
+`network_profile` | The name of the network profile settings file to use. Maps to .ufo/settings/network/NAME.yml file
 
 ## ECS Cluster Convention
 
@@ -50,23 +54,23 @@ Normally, the ECS cluster defaults to whatever UFO_ENV is set to by [convention]
 By default, these are all the same:
 
 ```sh
-ufo ship hi-web
-UFO_ENV=development ufo ship hi-web # same
-UFO_ENV=development ufo ship hi-web --cluster development # same
+ufo ship demo-web
+UFO_ENV=development ufo ship demo-web # same
+UFO_ENV=development ufo ship demo-web --cluster development # same
 ```
 
 If you use a specific `UFO_ENV=production`, these are the same
 
 ```
-UFO_ENV=production ufo ship hi-web
-UFO_ENV=production ufo ship hi-web --cluster production # same
+UFO_ENV=production ufo ship demo-web
+UFO_ENV=production ufo ship demo-web --cluster production # same
 ```
 
 Override the convention by explicitly specifying the `--cluster` option in the CLI.
 
 ```sh
-ufo ship hi-web --cluster custom-cluster # override the cluster
-UFO_ENV=production ufo ship hi-web --cluster production-cluster # override the cluster
+ufo ship demo-web --cluster custom-cluster # override the cluster
+UFO_ENV=production ufo ship demo-web --cluster production-cluster # override the cluster
 ```
 
 Override the convention by setting the cluster option in the `settings.yml` file, so you won't have to specify the `--cluster` option in the command repeatedly.
@@ -103,9 +107,8 @@ AWS_PROFILE=dev-profile2 => UFO_ENV=development
 AWS_PROFILE=prod-profile => UFO_ENV=production
 ```
 
-This behavior prevents you from switching `AWS_PROFILE`s and then accidentally deploying a production based docker image to development and vice versa because you forgot to also switch `UFO_ENV` to its respective environment.
+This behavior prevents you from switching `AWS_PROFILE`s, forgetting to switch `UFO_ENV` and then accidentally deploying a production based docker image to development and vice versa because you forgot to also switch `UFO_ENV` to its respective environment.
 
 <a id="prev" class="btn btn-basic" href="{% link _docs/structure.md %}">Back</a>
-<a id="next" class="btn btn-primary" href="{% link _docs/params.md %}">Next Step</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/settings-network.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>
-

data/docs/_docs/single-task.md

@@ -5,15 +5,15 @@ title: Run Single Task
 Sometimes you do not want to run a long running `service` but a one time task. Running Rails migrations are an example of a one off task.  Here is an example of how you would run a one time task.
 
 ```
-ufo task hi-web --command bundle exec rake db:migrate
+ufo task demo-web -c bundle exec rake db:migrate
 ```
 
 At the end of the output you should see you the task ARN:
 
 ```sh
-$ ufo task hi-web --command bundle exec rake db:migrate
+$ ufo task demo-web -c bundle exec rake db:migrate
 ...
-Running task_definition: hi-web
+Running task_definition: demo-web
 Task ARN: arn:aws:ecs:us-west-2:994926937775:task/a0e4229d-3d39-4b26-9151-6ab6869b84d4
 $
 ```

data/docs/_docs/ssl-support.md

@@ -0,0 +1,42 @@
+---
+title: SSL Support
+---
+
+## Application Load Balancers
+
+If you are using an Application Load Balancer you can configure SSL support by adjusting the listener in `.ufo/settings/cfn/default.yml`.  Here's an example:
+
+```
+listener:
+  port: 443
+  protocol: HTTPS
+  certificates:
+  - certificate: arn:aws:acm:us-east-1:111111111111:certificate/11111111-2222-3333-4444-555555555555
+```
+
+For the certificate arn, you will need to create a certificate with AWS ACM. To do so, you can follow these instructions: [Request a Public Certificate
+](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html)
+
+Once this is configured, you deploy the app again:
+
+    ufo ship
+
+## Network Load Balancers
+
+Network Load Balancers work at layer 4, so they do not support SSL termination because SSL happens higher up in the OSI model layers. With Network Load Balancers you handle SSL termination within your app with the app server you are using.  For example, it could be apache, nginx or tomcat.
+
+You also will need to also configure the target group to check the port that your app server is listening to and configure the health_check_protocol to HTTPS.  Here's an example:
+
+```
+listener:
+  port: 443
+target_group:
+  port: 443
+  health_check_protocol: HTTPS
+```
+
+The protocol in the case of the network load balancer is TCP and is configured to TCP by default by ufo for Network Load Balancers, so you don't have to configure it.
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/security-groups.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/route53-support.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/structure.md

@@ -9,6 +9,8 @@ Ufo creates a `.ufo` folder within your project which contains the required file
 ├── output
 ├── params.yml
 ├── settings.yml
+├── settings/cfn/default.yml
+├── settings/network/default.yml
 ├── task_definitions.rb
 ├── templates
 |   └── main.json.erb
@@ -24,7 +26,9 @@ File / Directory  | Description
 ------------- | -------------
 <code>output/</code>  | The folder where the generated task definitions are written to.  The way the task definitions are generated is covered in [ufo tasks build]({% link _docs/tutorial-ufo-tasks-build.md %}).
 <code>params</code>  | This is where you can adjust the params that get send to the aws-sdk api calls. More info at [Params]({% link _docs/params.md %}).
-<code>settings.yml</code>  | Ufo's settings file, where you adjust the default [settings]({% link _docs/settings.md %}).
+<code>settings.yml</code>  | Ufo's general settings file, where you adjust the default [settings]({% link _docs/settings.md %}).
+<code>settings/cfn/default.yml</code>  | Ufo's cfn settings. You can customize the CloudFormation resource properties here.
+<code>settings/network/default.yml</code>  | Ufo's network settings. You can customize the vpc and subnets to used here.
 <code>task_definitions.rb</code>  | This is where you define the task definitions and specify the variables to be used by the ERB templates.
 <code>templates/</code>  | The ERB templates with the task definition json code.  The templates are covered in more detail in [ufo tasks build]({% link _docs/tutorial-ufo-tasks-build.md %}).
 <code>templates/main.json.erb</code>  | This is the main and starter template task definition json file that ufo initially generates.

data/docs/_docs/stuck-cloudformation.md

@@ -0,0 +1,30 @@
+---
+title: Stuck CloudFormation
+---
+
+The CloudFormation stack update or creation can get stuck in a `*_IN_PROGRESS` state for a very long time, like more than an hour.  This happens when you deploy an ECS service that fails to stabilize. Usually, this is an error with the Docker container failing to start up successfully.
+There can be many reasons for this, here are some examples:
+
+* Bug in the startup script in the Dockerfile.
+* There are no container instances available to place the docker ECS task.
+* You have a rails app and it is failing to connect to the database upon startup, maybe due to a security group setting.
+
+To resolve this, you can:
+
+1. cancel the current deploy
+2. fix the underlying issue
+3. deploy again
+
+## Canceling Deployment
+
+If an ECS deployment does not finish within 10 minutes because the ECS service is not stabilizing, it is usually due one of the reasons above. In these cases, it is safe to cancel and try again.
+
+To cancel a current deploy, run:
+
+    ufo cancel
+
+This is the same thing as canceling the stack update in the CloudFormation console.
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/customize-cloudformation.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/upgrade4.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/tutorial-ufo-docker-build.md

@@ -4,7 +4,7 @@ title: Build Docker
 
 ## Build the Docker Image
 
-Let's use the `ufo docker build` command to build the docker image. The command uses the `Dockerfile` in the current project to build the docker image.  You use your own Dockerfile so you have fully control over how you would like the image to be built.  For this tutorial we will continue to use the [tongueroo/hi](https://github.com/tongueroo/hi) app and it's Dockerfile. Let's run the command:
+Let's use the `ufo docker build` command to build the docker image. The command uses the `Dockerfile` in the current project to build the docker image.  You use your own Dockerfile so you have fully control over how you would like the image to be built.  For this tutorial we will continue to use the [tongueroo/demo-ufo](https://github.com/tongueroo/demo-ufo) app and it's Dockerfile. Let's run the command:
 
 ```sh
 ufo docker build
@@ -15,38 +15,25 @@ You should see similar output (some of the output has been truncated for concise
 ```sh
 $ ufo docker build
 Building docker image with:
-  docker build -t tongueroo/hi:ufo-2017-06-11T22-18-03-a18aa30 -f Dockerfile .
-Sending build context to Docker daemon 734.2 kB
-Step 1 : FROM ruby:2.3.3
- ---> 0e1db669d557
-Step 2 : RUN apt-get update &&   apt-get install -y     build-essential     nodejs &&   rm -rf /var/lib/apt/lists/* && apt-get clean && apt-get purge
+  docker build -t tongueroo/demo-ufo:ufo-2018-06-28T16-33-57-7e0af94 -f Dockerfile .
+Sending build context to Docker daemon    128kB
+Step 1/10 : FROM ruby:2.5.1
+ ---> 857bc7ff918f
+Step 2/10 : WORKDIR /app
  ---> Using cache
- ---> 931ace833716
+ ---> 4e93fbb496c9
 ...
-Step 7 : ADD . /app
- ---> fae2452e6c35
-Removing intermediate container 4c93f92a7fd8
-Step 8 : RUN bundle install --system
- ---> Running in f851b9cb7d27
-Using rake 12.0.0
-Using i18n 0.8.1
-...
-Using web-console 2.3.0
-Bundle complete! 12 Gemfile dependencies, 56 gems now installed.
-Bundled gems are installed into /usr/local/bundle.
- ---> 194830c5c1a8
-...
-Removing intermediate container 67545cd4cd09
-Step 11 : CMD bin/web
- ---> Running in b1b26e68d957
- ---> 8547bb48b21f
-Removing intermediate container b1b26e68d957
-Successfully built 8547bb48b21f
-Docker image tongueroo/hi:ufo-2017-06-11T22-18-03-a18aa30 built.  Took 33s.
-$
+Step 10/10 : CMD bin/web
+ ---> Running in cd63ebaec8aa
+ ---> 14852737c639
+Removing intermediate container cd63ebaec8aa
+Successfully built 14852737c639
+Successfully tagged tongueroo/demo-ufo:ufo-2018-06-28T16-33-57-7e0af94
+Docker image tongueroo/demo-ufo:ufo-2018-06-28T16-33-57-7e0af94 built.
+Docker build took 2s.
 ```
 
-As you can see `ufo docker build` effectively shells out and calls `docker build -t tongueroo/hi:ufo-2017-06-11T22-18-03-a18aa30 -f Dockerfile .`.  The docker image tag that is generated contains a useful timestamp and the current HEAD git sha of the project that you are on.
+As you can see `ufo docker build` shells out and calls `docker build -t tongueroo/demo-ufo:ufo-2017-06-11T22-18-03-a18aa30 -f Dockerfile .`.  The docker image tag that is generated contains a useful timestamp and the current HEAD git sha of the project that you are on.
 
 By default when you are running `ufo docker build` directly it does not push the docker image to the registry.  If you would like it to push the built image to a registry at the end of the build use the `--push` flag.
 
@@ -63,11 +50,12 @@ ufo docker push
 You should see the image being pushed with a message that looks something like this:
 
 ```sh
-Pushed tongueroo/hi:ufo-2017-06-11T22-22-32-a18aa30 docker image. Took 9s.
+Pushed tongueroo/demo-ufo:ufo-2018-06-28T16-33-57-7e0af94 docker image.
+Docker push took 12s.
 ```
 
 
-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 you can use the `aws ecr get-login` command.
+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 automatically calls the `aws ecr get-login` command and authenticates for you.
 
 <a id="prev" class="btn btn-basic" href="{% link _docs/tutorial-ufo-init.md %}">Back</a>
 <a id="next" class="btn btn-primary" href="{% link _docs/tutorial-ufo-tasks-build.md %}">Next Step</a>