ufo 5.0.7 → 6.0.0

data/docs/_docs/tutorial-ufo-init.md

@@ -1,86 +0,0 @@
----
-title: Setup Ufo
-nav_order: 5
----
-
-The easiest way to create this ufo folder is by using the `ufo init` command.  For this tutorial we'll [tongueroo/demo-ufo](https://github.com/tongueroo/demo-ufo) which is a small test sinatra app.
-Let's run the command in our newly cloned project.
-
-```sh
-git clone https://github.com/tongueroo/demo-ufo.git
-cd demo-ufo
-ufo init --app=demo --image=tongueroo/demo-ufo
-```
-
-You should see output similiar to this:
-
-```sh
-$ ufo init --app=demo --image=tongueroo/demo-ufo
-Setting up ufo project...
-      create  .env
-      create  .ufo/params.yml
-      create  .ufo/settings.yml
-      create  .ufo/settings/cfn/default.yml
-      create  .ufo/settings/network/default.yml
-      create  .ufo/task_definitions.rb
-      create  .ufo/templates/fargate.json.erb
-      create  .ufo/templates/main.json.erb
-      create  .ufo/variables/base.rb
-      create  .ufo/variables/development.rb
-      create  .ufo/variables/production.rb
-   identical  Dockerfile
-      create  bin/deploy
-      append  .gitignore
-      create  .dockerignore
-Starter ufo files created.
-Congrats 🎉 You have successfully set up ufo for your project.
-$
-```
-
-The `ufo init` command generated a few starter ufo files for you. The standard directory structure of the ufo folder looks like this:
-
-```sh
-.ufo
-├── output
-├── settings.yml
-├── task_definitions.rb
-├── templates
-|   └── main.json.erb
-└── variables
-    ├── base.rb
-    ├── production.rb
-    └── development.rb
-```
-
-The explanation of the folders and files were covered in detailed earlier at [Structure]({% link _docs/structure.md %}).
-
-## Settings
-
-Take a look at the `settings.yml` file and notice that it contains some default configuration settings so you do not have to type out these options repeatedly for some of the ufo commands.
-
-```yaml
-# More info: http://ufoships.com/docs/settings/
-base:
-  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.
-  # defaults when an new ECS service is created by ufo ship
-
-development:
-  # cluster: dev # uncomment if you want the cluster name be other than the default
-                 # the default is to match UFO_ENV.  So UFO_ENV=development means the ECS
-                 # cluster will be name development
-  # When you have AWS_PROFILE set to one of these values, ufo will switch to the desired
-  # environment. This prevents you from switching AWS_PROFILE, forgetting to
-  # also switch UFO_ENV, and accidentally deploying to production vs development.
-  # aws_profile: dev_profile1
-
-production:
-  # cluster: prod
-```
-
-The `image` value is the name that ufo will use as a base portion of the name to generate a Docker image name, it should not include the tag portion.
-
-The other settings are optional.  You can learn more about them at [Settings]({% link _docs/settings.md %}).
-
-{% include prev_next.md %}

data/docs/_docs/tutorial-ufo-ship.md

@@ -1,95 +0,0 @@
----
-title: Deploy One App
-nav_order: 8
----
-
-## Step 3 - Ship the Code to ECS
-
-In this guide we have walked through what ufo does step by step.  First ufo builds the Docker image with `ufo docker build`.  Then it will build and register the ECS task definitions with the `ufo tasks` commands. Now we'll deploy the code to ECS.
-
-```sh
-ufo ship demo-web
-```
-
-By convention, ufo will ship the docker container to an ECS cluster with the same value as UFO_ENV, which defaults to development.  So the command above is the same as:
-
-```sh
-ufo ship demo-web --cluster development
-UFO_ENV=development ufo ship demo-web
-```
-
-When you run `ufo ship demo-web`:
-
-1. It builds the docker image.
-2. Generates a task definition and registers it.
-3. Updates the ECS service to use it.
-
-If the ECS service demo-web does not yet exist, ufo will create the service for you. Ufo will also automatically create the ECS cluster.
-
-NOTE: Ufo creates the ECS cluster record, but you still need to associate ECS Container Instances to the cluster yourself.
-
-By convention, if the service has a container name web, ufo will automatically create an Load Balancer.  Let's take a look at the example out from the `ufo ship`.  Some of the output has been removed for conciseness.
-
-```sh
-$ ufo ship demo-web
-Building docker image with:
-  docker build -t tongueroo/demo-ufo:ufo-2018-06-28T16-41-11-7e0af94 -f Dockerfile .
-...
-Deploying demo-web...
-Ensuring log group for demo-web task definition exists
-Log group name: ecs/demo-web
-Creating stack development-demo-web...
-Generated template saved at: /tmp/ufo/development-demo-web/stack.yml
-Generated parameters saved at: /tmp/ufo/development-demo-web/parameters.yml
-04:41:27PM CREATE_IN_PROGRESS AWS::CloudFormation::Stack development-demo-web User Initiated
-04:41:31PM CREATE_IN_PROGRESS AWS::EC2::SecurityGroup ElbSecurityGroup
-04:41:31PM CREATE_IN_PROGRESS AWS::EC2::SecurityGroup EcsSecurityGroup
-04:41:31PM CREATE_IN_PROGRESS AWS::ElasticLoadBalancingV2::TargetGroup TargetGroup
-04:41:31PM CREATE_IN_PROGRESS AWS::EC2::SecurityGroup ElbSecurityGroup Resource creation Initiated
-04:41:32PM CREATE_IN_PROGRESS AWS::EC2::SecurityGroup EcsSecurityGroup Resource creation Initiated
-04:41:32PM CREATE_IN_PROGRESS AWS::ElasticLoadBalancingV2::TargetGroup TargetGroup Resource creation Initiated
-...
-04:44:46PM CREATE_COMPLETE AWS::ECS::Service Ecs
-04:44:48PM CREATE_COMPLETE AWS::CloudFormation::Stack development-demo-web
-Stack success status: CREATE_COMPLETE
-Time took for stack deployment: 3m 22s.
-Software shipped!
-$
-```
-
-Checking the ECS console you should see something like this:
-
-<img src="/img/tutorials/ecs-console-ufo-ship.png" class="doc-photo" />
-
-You have successfully deployed a Docker image to ECS! 🍾🥂
-
-## Checking ECS Service
-
-Another way to check that the ECS service is running is with the `ufo ps` command.
-
-    $ ufo ps demo-web
-    => Service: demo-web
-       Service name: development-demo-web-Ecs-12DRF2703Z3D2
-       Status: ACTIVE
-       Running count: 1
-       Desired count: 1
-       Launch type: EC2
-       Task definition: demo-web:82
-       Elb: develop-Elb-ZY1VARS3KP14-2141687965.us-east-1.elb.amazonaws.com
-    +----------+------+-------------+---------------+---------+-------+
-    |    Id    | Name |   Release   |    Started    | Status  | Notes |
-    +----------+------+-------------+---------------+---------+-------+
-    | e4426421 | web  | demo-web:82 | 5 minutes ago | RUNNING |       |
-    +----------+------+-------------+---------------+---------+-------+
-
-## Ufo Current Tip
-
-We've been typing the `demo-web` service name explicitly.  We can set the current service with the `ufo current` command to save us from typing each time.  Example:
-
-    ufo current --service demo-web
-    ufo ship # now same as ufo ship demo-web
-    ufo ps # now same as ufo ps demo-web
-
-Congratulations 🎊 You have successfully built a Docker image, register it and deployed it to AWS ECS.
-
-{% include prev_next.md %}

data/docs/_docs/tutorial-ufo-ships.md

@@ -1,38 +0,0 @@
----
-title: Deploy Multiple Apps
-nav_order: 9
----
-
-You might have noticed in the tutorial that the generated starter .ufo folder contains 3 task definitions a `web`, `worker` and `clock` role.  This is a common pattern.  The web process handles web traffic, the worker process handles background job processing that would be too slow and potentially block web requests, and a clock process is typically used to schedule recurring jobs.
-
-These processes typically use the same codebase and same docker image, but have slightly different run time settings.  The docker run command for a web process could be [puma](http://puma.io/) and the command for a worker process could be [sidekiq](http://sidekiq.org/).  Environment variables are also sometimes different.  The important key is that the same docker image is used for all 3 services but the task definition for each service is slightly different.
-
-While we can use the `ufo ship` command to deploy to all 3 service roles individually like so:
-
-```sh
-ufo ship demo-web
-ufo ship demo-worker
-ufo ship demo-clock
-```
-
-This would build a new Docker image for each process.  We actually want have the same docker image running on all of these roles.  In this case where we want to use the *same* Docker image for all 3 roles, ufo provides a `ufo ships` command.
-
-## ufo ships
-
-```sh
-ufo ships demo-web demo-worker demo-clock
-```
-
-You can check on the ECS console and should see something similar to this:
-
-<img src="/img/tutorials/ecs-console-ufo-ships.png" class="doc-photo" />
-
-You can shorten the command by taking advantage of shell expansion:
-
-```sh
-ufo ships demo-{web,worker,clock}
-```
-
-In the case of the `ufo ships` command the `--wait` option defaults to false so that all the specified ECS services update in parallel.  You can check on the status of the update on the CloudFormation console.
-
-{% include prev_next.md %}

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

@@ -1,177 +0,0 @@
----
-title: Task Definitions
-nav_order: 7
----
-
-## Build the ECS Task Definitions
-
-Now that we have a Docker image pushed to a registry we can use that image for ECS.  Ufo takes that image and adds it to an ECS task definition.  This is where ufo is powerful.  Ufo gives you the power to build and control your ECS task definition directly.
-
-Let's take a look at the files that are used by ufo to build the ECS task definition.  These files were generated by the `ufo init` command at the beginning.
-
-1. `.ufo/templates/main.json.erb`
-2. `.ufo/task_definitions.rb`
-
-Ufo task definitions are written as an ERB template that makes it directly accessible. You can configure it to your requirements.  Here is an example of an ERB template `.ufo/templates/main.json.erb` and shows how to modify the task definition:
-
-**.ufo/templates/main.json.erb**:
-
-```json
-{
-    "family": "<%= @family %>",
-    "containerDefinitions": [
-        {
-            "name": "<%= @name %>",
-            "image": "<%= @image %>",
-            "cpu": <%= @cpu %>,
-            <% if @memory %>
-            "memory": <%= @memory %>,
-            <% end %>
-            <% if @memory_reservation %>
-...
-            "essential": true
-        }
-    ]
-}
-```
-
-The instance variable values are specified in `.ufo/task_definitions.rb` via a DSL.  Here's the file:
-
-**.ufo/task_definitions.rb**:
-
-```
-task_definition "demo-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 "demo-worker" do
-  source "main" # will use ufo/templates/main.json.erb
-  variables(
-    family: task_definition_name,
-    name: "worker",
-    command: ["bin/worker"]
-  )
-end
-```
-
-## Shared Variables
-
-Ufo has a concept of shared variables, covered in [Shared Variables]({% link _docs/variables.md %}). The shared variables are set in the `variables` folder and allow you to use a set of shared variables common to your templates:
-
-**.ufo/variables/base.rb**:
-
-```ruby
-@image = helper.full_image_name # includes the git sha tongueroo/demo-ufo:ufo-[sha].
-@cpu = 256
-@memory_reservation = 512
-@environment = helper.env_file(".env")
-```
-
-**.ufo/variables/development.rb**:
-
-```ruby
-@environment = helper.env_vars(%Q{
-  RAILS_ENV=development
-  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.
-
-If you need to modify the task definition template to suit your own needs it is simple, just edit `main.json.erb`.  You do not have to dive deep into internal code somewhere.  It is all there for you to control fully.
-
-The `task_definition.rb` has access to some useful helper methods detailed in [Helpers]({% link _docs/helpers.md %}).
-
-Let's build the task definitions:
-
-```sh
-ufo tasks build
-```
-
-You should see output similar to below:
-
-```sh
-$ ufo tasks build
-Building Task Definitions...
-Generating Task Definitions:
-  .ufo/output/demo-web.json
-  .ufo/output/demo-worker.json
-  .ufo/output/demo-clock.json
-Task Definitions built in .ufo/output
-$
-```
-
-Let's take a look at one of the generated files: `.ufo/output/demo-web.json`.
-
-```json
-{
-  "family": "demo-web",
-  "containerDefinitions": [
-    {
-      "name": "web",
-      "image": "tongueroo/demo-ufo:ufo-2018-06-29T23-20-47-20b3a10",
-      "cpu": 256,
-      "memory": 512,
-      "memoryReservation": 512,
-      "portMappings": [
-        {
-          "containerPort": 4567,
-          "protocol": "tcp"
-        }
-      ],
-      "command": null,
-      "environment": [
-        {
-          "name": "RAILS_ENV",
-          "value": "development"
-        },
-        {
-          "name": "SECRET_KEY_BASE",
-          "value": "secret"
-        }
-      ],
-      "logConfiguration": {
-        "logDriver": "awslogs",
-        "options": {
-          "awslogs-group": "ecs/demo-web",
-          "awslogs-region": "us-east-1",
-          "awslogs-stream-prefix": "demo"
-        }
-      },
-      "essential": true
-    }
-  ]
-}
-```
-
-## Register the ECS Task Definitions
-
-You have built the ECS task definitions locally on your machine. To register the task definitions in the `output` folder run:
-
-```sh
-ufo tasks register
-```
-
-You should see something similar to this:
-
-```sh
-$ ufo tasks register
-Equivalent aws cli command:
-  aws ecs register-task-definition --cli-input-json file://.ufo/output/demo-web.json
-demo-web task definition registered.
-Equivalent aws cli command:
-  aws ecs register-task-definition --cli-input-json file://.ufo/output/demo-clock.json
-demo-clock task definition registered.
-Equivalent aws cli command:
-  aws ecs register-task-definition --cli-input-json file://.ufo/output/demo-worker.json
-demo-worker task definition registered.
-$
-```
-
-{% include prev_next.md %}

data/docs/_docs/tutorial.md

@@ -1,14 +0,0 @@
----
-title: Tutorial
-nav_order: 4
----
-
-In the next sections, we'll walk through using ufo in detail. We will ufo-ify a project. Then we'll go through the step by step process that ufo automated.  Normally ufo is not really used in step like fashion like in this tutorial, but going through it step by step really helps to understand how ufo works.  Here are the steps we'll go through:
-
-1. We'll build a docker image by using `ufo docker`.
-2. We'll build and register the task definitions to ECS with the newly built docker images with `ufo tasks`
-3. Finally, we'll use `ufo ship` to run through entire process.
-
-Let's start!
-
-{% include prev_next.md %}

data/docs/_docs/ufo-current.md

@@ -1,49 +0,0 @@
----
-title: Ufo Current
-nav_order: 26
----
-
-## service
-
-There's a handy way to shorten ufo commands by setting the current service.  Example:
-
-    ufo ship demo-web # normal usage
-    ufo current --service demo-web
-    ufo ship # no longer have to type: demo-web
-
-To view the current settings run `ufo current` with no options.
-
-    $ ufo current
-    Current env_extra: 1
-    Current service: demo-web
-
-Setting the current service helps shorten other commands also:
-
-    ufo cancel
-    ufo deploy
-    ufo destroy
-    ufo ps
-    ufo releases
-    ufo resources
-    ufo rollback VERSION
-    ufo scale COUNT
-    ufo ship
-
-## UFO_ENV_EXTRA
-
-The UFO_ENV_EXTRA env variable allows you create multiple environments with of the same services quickly.  More info about is is detailed at [ufo-env-extra]({% link _docs/ufo-env-extra.md %}).  You can also set a current UFO_ENV_EXTRA with the `--env-extra` option.
-
-    ufo current --env-extra 1
-
-## services
-
-The `ufo ships` commands builds one Docker image and deploys them to multiple ECS services, so it usually takes a list of services like so:
-
-    ufo ships demo-web demo-worker demo-clock
-
-This can be shorten with with current also.
-
-    ufo current --services demo-web demo-worker demo-clock
-    ufo ships
-
-{% include prev_next.md %}

data/docs/_docs/ufo-env-extra.md

@@ -1,22 +0,0 @@
----
-title: UFO_ENV_EXTRA
-nav_order: 25
----
-
-<div class="video-box"><div class="video-container"><iframe src="https://www.youtube.com/embed/UVQuwQGToYE" frameborder="0" allowfullscreen=""></iframe></div></div>
-
-Ufo has an concept of extra environments. This is controlled by the `UFO_ENV_EXTRA` variable.  By setting `UFO_ENV_EXTRA` you can create additional identical ECS services or environments.
-
-    ufo ship demo-web # creates a demo-web ecs service
-    UFO_ENV_EXTRA=2 ufo ship demo-web # creates a demo-web-2 ecs service
-
-The `UFO_ENV_EXTRA` can also be set with `ufo current` so you do not have to type it over.
-
-    ufo current --env-extra 1
-
-The precedence:
-
-1. UFO_ENV_EXTRA - takes highest precedence
-2. `.ufo/current` env-extra setting - takes lower precedence
-
-{% include prev_next.md %}

data/docs/_docs/ufo-env.md

@@ -1,46 +0,0 @@
----
-title: UFO_ENV
-nav_order: 24
----
-
-Ufo's behavior is controlled by the `UFO_ENV` environment variable.  For example, the `UFO_ENV` variable is used to layer different ufo variable files together to make it easy to specify settings for different environments like production and development.  This is covered thoroughly in the [Variables]({% link _docs/variables.md %}) section.  `UFO_ENV` defaults to `development` when not set.
-
-## Setting UFO_ENV
-
-The `UFO_ENV` can be set in several ways:
-
-1. Exported as an environment variable to your shell - This takes the second highest precedence.
-2. From the `aws_profiles` setting in your `settings.yml` file - This takes the lowest precedence.
-
-## As an environment variable
-
-```sh
-export UFO_ENV=production
-ufo ship demo-web
-```
-
-You can set `UFO_ENV` in your `~/.profile`.
-
-## In .ufo/settings.yml
-
-The most interesting way to set `UFO_ENV` is with the `aws_profiles` setting in `.ufo/settings.yml`.  Let's say you have a `~/.ufo/settings.yml` with the following:
-
-```yaml
-development:
-  aws_profile: my-dev-profile
-
-production:
-  aws_profile: my-prod-profile
-```
-
-In this case, when you set `AWS_PROFILE` to switch AWS profiles, ufo picks this up and maps the `AWS_PROFILE` value to the specified `UFO_ENV` using the `aws_profiles` lookup.  Example:
-
-```sh
-AWS_PROFILE=my-prod-profile => UFO_ENV=production
-AWS_PROFILE=my-dev-profile => UFO_ENV=development
-AWS_PROFILE=whatever => UFO_ENV=development # since there are no profiles that match
-```
-
-Notice how `AWS_PROFILE=whatever` results in `UFO_ENV=development`.  This is because there are no matching aws_profiles in the `settings.yml`.  More info on settings is available at [settings]({% link _docs/settings.md %}).
-
-{% include prev_next.md %}

data/docs/_docs/ufo-logs.md

@@ -1,49 +0,0 @@
----
-title: ufo logs command
-nav_order: 23
----
-
-The ufo logs command will tail the logs of the ecs service if you are using the awslogs driver.
-
-## Examples
-
-    $ ufo logs demo-web
-    2020-01-16 23:58:16 UTC 10.20.120.135 - - [16/Jan/2020:23:58:16 +0000] "GET / HTTP/1.1" 200 3 0.0003
-    2020-01-16 23:58:16 UTC 10.20.120.135 - - [16/Jan/2020:23:58:16 UTC] "GET / HTTP/1.1" 200 3
-    2020-01-16 23:58:16 UTC - -> /
-
-## Current Set
-
-If you have a current service name set.
-
-    $ ufo current --service demo-web
-    $ ufo logs # follow by default
-    2020-01-16 23:58:16 UTC 10.20.120.135 - - [16/Jan/2020:23:58:16 +0000] "GET / HTTP/1.1" 200 3 0.0003
-    2020-01-16 23:58:16 UTC 10.20.120.135 - - [16/Jan/2020:23:58:16 UTC] "GET / HTTP/1.1" 200 3
-    2020-01-16 23:58:16 UTC - -> /
-
-## Options
-
-By default the logs follow and use the simple format without the log stream. Here's how adjust those options:
-
-    ufo logs --no-follow
-    ufo logs --format detailed # to show stream too
-
-More info: [ufo logs reference]({% link _reference/ufo-logs.md %})
-
-## awslog driver
-
-The generated .ufo task definition defaults to the awslogs driver. If you need it, it looks like this:
-
-```json
-"logConfiguration": {
-  "logDriver": "awslogs",
-  "options": {
-    "awslogs-group": "<%= @awslogs_group %>",
-    "awslogs-region": "<%= @awslogs_region || 'us-east-1' %>",
-    "awslogs-stream-prefix": "<%= @awslogs_stream_prefix %>"
-  }
-}
-```
-
-{% include prev_next.md %}

data/docs/_docs/ufo-task-params.md

@@ -1,43 +0,0 @@
----
-title: Ufo Task Params
-nav_order: 27
----
-
-You can run one off task with the [ufo task](https://ufoships.com/reference/ufo-task/) command.
-
-The `ufo task` commands:
-
-1. Builds the docker image
-2. Registers the ECS task definition
-3. Runs the command
-
-
-The params that ufo sends to the [ruby aws-sdk](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/ECS/Client.html#run_task-instance_method) methods to for the one off task can be customized with a `params.yml` file.  This allows you use the full power of the aws-sdk.
-
-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
-# 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
-#
-# The network helper provides access to the .ufo/settings/network/[PROFILE].yml
-#
-# More docs: http://ufoships.com/docs/params/
-
-# ufo task calls run_tasks
-run_task:
-  # 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:
-
-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.
-
-{% include prev_next.md %}

data/docs/_docs/ufo-tasks-register.md

@@ -1,21 +0,0 @@
----
-title: ufo tasks register
----
-
-The `ufo tasks register` command registers all the generated task definitions in `output/` to AWS ECS. Let's run it:
-
-```sh
-ufo tasks register
-```
-
-You should see something similiar to this:
-
-```sh
-demo-clock task definition registered.
-demo-web task definition registered.
-demo-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" />