ufo 4.5.11 → 5.0.0

data/docs/_docs/more/stuck-cloudformation.md

@@ -1,6 +1,6 @@
 ---
 title: Stuck CloudFormation
-nav_order: 38
+nav_order: 39
 ---
 
 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.
@@ -26,4 +26,4 @@ To cancel a current deploy, run:
 
 This is the same thing as canceling the stack update in the CloudFormation console.
 
-{% include prev_next.md %}
+{% include prev_next.md %}

data/docs/_docs/more/why-cloudformation.md

@@ -1,6 +1,6 @@
 ---
 title: Why CloudFormation
-nav_order: 36
+nav_order: 37
 ---
 
 Version 3 of ufo was a simpler implementation and did not make use of CloudFormation to create the ECS service. In version 4, ufo uses CloudFormation to create the ECS Service.  This is because ufo became more powerful. Notably, support for Load Balancers was added. With this power, also came added complexity. So the complexity was push onto CloudFormation.  Hence, ECS service is implemented as CloudFormation resource in version 4.
@@ -18,4 +18,4 @@ You can check the resources created with CloudFormation by clicking on the stack
 
 <img src="/img/docs/cloudformation-resources.png" class="doc-photo" />
 
-{% include prev_next.md %}
+{% include prev_next.md %}

data/docs/_docs/next-steps.md

@@ -1,6 +1,6 @@
 ---
 title: Next Steps
-nav_order: 46
+nav_order: 47
 ---
 
 This concludes the tutorial guide for ufo. Hopefully you are now more comfortable with ufo's basic usage, concepts, and have a feel for the workflow.
@@ -13,4 +13,4 @@ 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!
 
-{% include prev_next.md %}
+{% include prev_next.md %}

data/docs/_docs/quick-start-ec2.md

@@ -26,6 +26,7 @@ This quickstart assumes:
 
 * You have push access to the repo. Refer to the Notes "Repo Push Access" section below for more info.
 * You are using ECS EC2 and have an ECS cluster with EC2 Container instances running. Refer to the Notes "ECS EC2 vs ECS Fargate" section below for more info.
+* The ECS Cluster is in the default VPC. If it is not you need to use the `--vpc-id`, `--ecs-subnets`, and `--elb-subnets` options in the [ufo init]({% link _reference/ufo-init.md %}) command.
 
 ## What Happened
 
@@ -82,4 +83,4 @@ If you would like not to manage the EC2 server fleet, you are looking for ECS Fa
 
 Learn more in the next sections.
 
-{% include prev_next.md %}
+{% include prev_next.md %}

data/docs/_docs/secrets.md

@@ -0,0 +1,112 @@
+---
+title: Secrets
+---
+
+## What are Secrets?
+
+[ECS supports injecting secrets or sensitive data](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data.html) into the the environment as variables.  ECS handles the decryption the secrets go straight from AWS to the ECS task environment. It never passes through the machine calling `ufo ship` IE: your laptop, a deploy server, or CodeBuild, etc.
+
+ECS supports 2 storage backends for secrets:
+
+1. [Secrets Manager](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data-secrets.html#secrets-envvar)
+2. [Systems Manager Parameter Store](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data-parameters.html#secrets-envvar-parameters)
+
+Here are both of the formats:
+
+Secrets manager format:
+
+```json
+{
+  "containerDefinitions": [{
+    "secrets": [{
+      "name": "environment_variable_name",
+      "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-AbCdEf"
+    }]
+  }]
+}
+```
+
+Parameter store format:
+
+```json
+{
+  "containerDefinitions": [{
+    "secrets": [{
+      "name": "environment_variable_name",
+      "valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name"
+    }]
+  }]
+}
+```
+
+## UFO Support
+
+Ufo supports both forms of secrets. You create a `.secrets` file and can reference it in the `.ufo/templates/main.json.erb`
+
+```json
+{
+  "family": "<%= @family %>",
+  # ...
+  <% if @secrets %>
+  "secrets": <%= helper.secrets_file(".secrets") %>,
+  <% end %>
+}
+```
+
+The `.secrets` file is like an env file that will understand a secrets-smart format.  Example:
+
+    NAME1=SSM:/my/parameter_name
+    NAME2=SECRETSMANAGER:/my/secret_name-AbCdEf
+
+The `SSM:` and `SECRETSMANAGER:` prefix will be expanded to the full ARN. You can also just specify the full ARN.
+
+    NAME1=arn:aws:ssm:region:aws_account_id:parameter/my/parameter_name
+    NAME2=arn:aws:secretsmanager:region:aws_account_id:secret:my/secret_name-AbCdEf
+
+In turn, this generates:
+
+```json
+{
+  "containerDefinitions": [{
+    "secrets": [
+      {
+        "name": "NAME1",
+        "valueFrom": "arn:aws:ssm:us-west-2:536766270177:parameter/demo/development/foo"
+      },
+      {
+        "name": "NAME2",
+        "valueFrom": "arn:aws:secretsmanager:us-west-2:536766270177:secret:/demo/development/my-secret-test-qRoJel"
+      }
+    ]
+  }]
+}
+```
+
+## Substitution
+
+Ufo also does a simple substition on the value. For example, the `:UFO_ENV` is replaced with the actual value of `UFO_ENV=development`. Example:
+
+    NAME1=SSM:demo/:UFO_ENV/parameter_name
+    NAME2=SECRETSMANAGER:demo/:UFO_ENV/secret_name-AbCdEf
+
+Expands to:
+
+    NAME1=arn:aws:ssm:region:aws_account_id:parameter/demo/development/parameter_name
+    NAME2=arn:aws:secretsmanager:region:aws_account_id:secret:/demo/development/secret_name-AbCdEf
+
+## IAM Permission
+
+If you're using secrets, you'll need to provide an IAM execution role so the EC2 instance has permission to read the secrets. Here's a starter example:
+
+.ufo/iam_roles/execution_role.rb
+
+```ruby
+managed_iam_policy("AmazonEC2ContainerRegistryReadOnly")
+managed_iam_policy("AmazonSSMReadOnlyAccess")
+managed_iam_policy("CloudWatchLogsFullAccess")
+managed_iam_policy("SecretsManagerReadWrite")
+```
+
+More info [ECS IAM Roles]({% link _docs/iam-roles.md %})
+
+{% include prev_next.md %}

data/docs/_docs/settings.md

@@ -51,4 +51,4 @@ An interesting option is `aws_profile`.  This allows you to tightly connect an A
 
 Normally, the ECS cluster defaults to whatever UFO_ENV is set to by [convention]({% link _docs/conventions.md %}).  For example, when `UFO_ENV=production` the ECS Cluster is `production` and when `UFO_ENV=development` the ECS Cluster is `development`.  There are several ways to override this behavior. This is detailed in the [Settings Cluster docs]({% link _docs/settings/cluster.md %}).
 
-{% include prev_next.md %}
+{% include prev_next.md %}

data/docs/_docs/settings/aws_profile.md

@@ -33,4 +33,4 @@ The binding is two-way. So:
 
 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.
 
-{% include prev_next.md %}
+{% include prev_next.md %}

data/docs/_docs/settings/cfn.md

@@ -9,4 +9,4 @@ nav_order: 14
 
 {% include cfn-customize.md %}
 
-{% include prev_next.md %}
+{% include prev_next.md %}

data/docs/_docs/settings/cluster.md

@@ -11,25 +11,19 @@ Normally, the ECS cluster defaults to whatever UFO_ENV is set to by [convention]
 
 By default, these are all the same:
 
-```sh
-ufo ship demo-web
-UFO_ENV=development ufo ship demo-web # same
-UFO_ENV=development ufo ship demo-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 demo-web
-UFO_ENV=production ufo ship demo-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 demo-web --cluster custom-cluster # override the cluster
-UFO_ENV=production ufo ship demo-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
 
 The cavaet is that you must remember to specify `--cluster`.  A wrapper `bin/deploy` script could be useful here.
 
@@ -69,4 +63,4 @@ The precedence of the settings from highest to lowest is:
 * cluster environment setting
 * UFO_ENV default convention
 
-{% include prev_next.md %}
+{% include prev_next.md %}

data/docs/_docs/settings/network.md

@@ -32,4 +32,4 @@ elb_subnets | Used to create elb load balancer.  Defaults to same subnets as ecs
 ecs_security_groups | Additional security groups to associate with the ECS tasks.
 elb_security_groups | Additional security groups to associate with the ELB.
 
-{% include prev_next.md %}
+{% include prev_next.md %}

data/docs/_docs/ssl_errors.md

@@ -1,6 +1,5 @@
 ---
 Title: SSL Errors
-# nav_order:
 ---
 
 UFO uses the AWS Ruby SDK and the underlying default SSL certificate chain configured in your active Ruby and
@@ -38,4 +37,4 @@ Once you have updated OpenSSL and your `brew` packages, use the helper scripts a
 
 The `update-cert-chain.sh` file was created using the suggestions from <https://gemfury.com/help/could-not-verify-ssl-certificate/>. Please review the information at <https://gemfury.com/help/could-not-verify-ssl-certificate/> if the `Helper Scripts` above do not fully resolve your issue.
 
-The `test-aws-api-access.rb` uses examples from the <https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/quick-start-guide.html> for using and configuring the Ruby AWS SDK on your system.
+The `test-aws-api-access.rb` uses examples from the <https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/quick-start-guide.html> for using and configuring the Ruby AWS SDK on your system.

data/docs/_docs/structure.md

@@ -37,4 +37,4 @@ File / Directory  | Description
 
 Now that you know where the ufo configurations are located and what they look like, let’s use ufo!
 
-{% include prev_next.md %}
+{% include prev_next.md %}

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

@@ -58,4 +58,4 @@ 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 ufo automatically calls the `aws ecr get-login` command and authenticates for you.
 
-{% include prev_next.md %}
+{% include prev_next.md %}

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

@@ -89,4 +89,4 @@ The `image` value is the name that ufo will use as a base portion of the name to
 
 The other settings are optional.  You can learn more about them at [Settings]({% link _docs/settings.md %}).
 
-{% include prev_next.md %}
+{% include prev_next.md %}

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

@@ -92,4 +92,4 @@ We've been typing the `demo-web` service name explicitly.  We can set the curren
 
 Congratulations 🎊 You have successfully built a Docker image, register it and deployed it to AWS ECS.
 
-{% include prev_next.md %}
+{% include prev_next.md %}

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

@@ -35,4 +35,4 @@ 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 %}
+{% include prev_next.md %}

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

@@ -174,4 +174,4 @@ demo-worker task definition registered.
 $
 ```
 
-{% include prev_next.md %}
+{% include prev_next.md %}

data/docs/_docs/tutorial.md

@@ -11,4 +11,4 @@ In the next sections, we'll walk through using ufo in detail. We will ufo-ify a
 
 Let's start!
 
-{% include prev_next.md %}
+{% include prev_next.md %}

data/docs/_docs/ufo-current.md

@@ -1,6 +1,6 @@
 ---
 title: Ufo Current
-nav_order: 22
+nav_order: 23
 ---
 
 ## service
@@ -46,4 +46,4 @@ This can be shorten with with current also.
     ufo current --services demo-web demo-worker demo-clock
     ufo ships
 
-{% include prev_next.md %}
+{% include prev_next.md %}

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

@@ -1,6 +1,6 @@
 ---
 title: UFO_ENV_EXTRA
-nav_order: 21
+nav_order: 22
 ---
 
 <div class="video-box"><div class="video-container"><iframe src="https://www.youtube.com/embed/UVQuwQGToYE" frameborder="0" allowfullscreen=""></iframe></div></div>
@@ -19,4 +19,4 @@ The precedence:
 1. UFO_ENV_EXTRA - takes highest precedence
 2. `.ufo/current` env-extra setting - takes lower precedence
 
-{% include prev_next.md %}
+{% include prev_next.md %}

data/docs/_docs/ufo-env.md

@@ -1,6 +1,6 @@
 ---
 title: UFO_ENV
-nav_order: 20
+nav_order: 21
 ---
 
 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.
@@ -45,4 +45,4 @@ AWS_PROFILE=whatever => UFO_ENV=development # since there are no profiles that m
 
 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 %}
+{% include prev_next.md %}

data/docs/_docs/ufo-logs.md

@@ -0,0 +1,50 @@
+---
+title: ufo logs command
+nav_order: 20
+---
+
+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,6 +1,6 @@
 ---
 title: Ufo Task Params
-nav_order: 23
+nav_order: 24
 ---
 
 You can run one off task with the [ufo task](https://ufoships.com/reference/ufo-task/) command.
@@ -40,4 +40,4 @@ ERB and [shared variables]({% link _docs/variables.md %}) are available in the p
 
 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 %}
+{% include prev_next.md %}

data/docs/_docs/upgrading.md

@@ -1,6 +1,6 @@
 ---
 title: Upgrading
-nav_order: 33
+nav_order: 34
 ---
 
 <ul>
@@ -10,4 +10,4 @@ nav_order: 33
 {% endfor %}
 </ul>
 
-{% include prev_next.md %}
+{% include prev_next.md %}

data/docs/_docs/upgrading/upgrade4.5.md

@@ -3,7 +3,7 @@ title: Upgrading to Version 4.5
 short_title: Version 4.5
 order: 1
 categories: upgrading
-nav_order: 34
+nav_order: 35
 ---
 
 In ufo version 4.4 and 4.5, the default cloudformation stack names used by ufo were changed.
@@ -49,4 +49,4 @@ Version | Setting
 
 CloudFormation names the resources it creates with the beginning portion of the stack name. When the stack name prepends the environment then resources like ELBs a little bit harder to identify since they might be named something like this `product-Elb-K0LFFQ9LK50W`. It makes it harder to distinguish ELBs from different apps created by ufo.
 
-{% include prev_next.md %}
+{% include prev_next.md %}

data/docs/_docs/upgrading/upgrade4.md

@@ -3,7 +3,7 @@ title: Upgrading to Version 4.0
 short_title: Version 4.0
 order: 2
 categories: upgrading
-nav_order: 35
+nav_order: 36
 ---
 
 A major change in ufo from version 3 to 4 is that the ECS service is now created by CloudFormation. If you have an existing ECS service deployed by ufo version 3, when you deploy your app again with ufo version 4, there will be a new additional ECS service created. Here is the recommended upgrade path.
@@ -45,4 +45,4 @@ File | Changes
 .ufo/settings/cfn/default.yml | Starter cfn settings file.
 .ufo/settings/network/default.yml | This generated file will have the vpc and subnets that you specified above.  You can change them directly in this file to control what network settings ufo uses.
 
-{% include prev_next.md %}
+{% include prev_next.md %}