diff --git a/Makefile b/Makefile index d002c7d..655f630 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,10 @@ SHELL := /bin/bash +# List of targets the `readme` target should call before generating the readme +export README_DEPS ?= docs/targets.md docs/terraform.md + -include $(shell curl -sSL -o .build-harness "https://git.io/build-harness"; echo .build-harness) +## Lint terraform code lint: - $(SELF) terraform/install terraform/get-modules terraform/get-plugins terraform/lint terraform/validate + $(SELF) terraform/install terraform/get-modules terraform/get-plugins terraform/lint terraform/validate \ No newline at end of file diff --git a/README.md b/README.md index ce7216a..90295bd 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,122 @@ -![Cloud Posse](https://cloudposse.com/logo-300x69.png) + + +[![Cloud Posse](https://cloudposse.com/logo-300x69.svg)](https://cloudposse.com) + +# terraform-aws-ecs-container-definition + + [![Build Status](https://travis-ci.org/cloudposse/terraform-aws-ecs-container-definition.svg?branch=master)](https://travis-ci.org/cloudposse/terraform-aws-ecs-container-definition) [![Latest Release](https://img.shields.io/github/release/cloudposse/terraform-aws-ecs-container-definition.svg)](https://github.com/cloudposse/terraform-aws-ecs-container-definition/releases/latest) [![Slack Community](https://slack.cloudposse.com/badge.svg)](https://slack.cloudposse.com) -# terraform-aws-ecs-container-definition [![Build Status](https://travis-ci.org/cloudposse/terraform-aws-ecs-container-definition.svg?branch=master)](https://travis-ci.org/cloudposse/terraform-aws-ecs-container-definition) Terraform module to generate well-formed JSON documents that are passed to the `aws_ecs_task_definition` Terraform resource as [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions). + +--- + +This project is part of our comprehensive ["SweetOps"](https://docs.cloudposse.com) approach towards DevOps. + + +It's 100% Open Source and licensed under the [APACHE2](LICENSE). + + + + + + + + + ## Usage This module is meant to be used as output only, meaning it will be used to create outputs which are consumed as a parameter by Terraform resources or other modules. + + + + + +## Makefile Targets +``` +Available targets: + + help This help screen + help/all Display help for all targets + lint Lint terraform code + +``` + +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|:----:|:-----:|:-----:| +| command | The command that is passed to the container. | string | `` | no | +| container_cpu | The number of cpu units to reserve for the container. This is optional for tasks using Fargate launch type and the total amount of container_cpu of all containers in a task will need to be lower than the task-level cpu value. | string | `256` | no | +| container_image | The image used to start the container. Images in the Docker Hub registry available by default. | string | - | yes | +| container_memory | The amount of memory (in MiB) to allow the container to use. This is a hard limit, if the container attempts to exceed the container_memory, the container is killed. This field is optional for Fargate launch type and the total amount of container_memory of all containers in a task will need to be lower than the task memory value. | string | `256` | no | +| container_memory_reservation | The amount of memory (in MiB) to reserve for the container. If container needs to exceed this threshold, it can do so up to the set container_memory hard limit. | string | `128` | no | +| container_name | The name of the container. Up to 255 characters ([a-z], [A-Z], [0-9], -, _ allowed). | string | - | yes | +| container_port | The port number on the container bound to assigned host_port. | string | `80` | no | +| entrypoint | The entry point that is passed to the container. | string | `` | no | +| environment | The environment variables to pas to the container. This is a list of maps. | string | `` | no | +| essential | Determines whether all other containers in a task are stopped, if this container fails or stops for any reason. Due to how Terraform type casts booleans in json it is required to double quote this value. | string | `true` | no | +| healthcheck | A map containing command (string), interval (duration in seconds), retries (1-10, number of times to retry before marking container unhealthy, and startPeriod (0-300, optional grace period to wait, in seconds, before failed healthchecks count toward retries) | string | `` | no | +| host_port | The port number on the container instance (host) to reserve for the container_port. If using containers in a task with the awsvpc or host network mode, the hostPort can either be left blank or set to the same value as the containerPort. | string | `80` | no | +| log_driver | The log driver to use for the container. If using Fargate launch type, only supported value is awslogs. | string | `awslogs` | no | +| log_options | The configuration options to send to the log_driver. | string | `` | no | +| protocol | The protocol used for the port mapping. Options: tcp or udp. | string | `tcp` | no | +| readonly_root_filesystem | Determines whether a container is given read-only access to its root filesystem. Due to how Terraform type casts booleans in json it is required to double quote this value. | string | `false` | no | +| working_directory | The working directory to run commands inside the container. | string | `` | no | + +## Outputs + +| Name | Description | +|------|-------------| +| json | JSON encoded container definitions for use with other terraform resources such as aws_ecs_task_definition. | + + + + +## Related Projects + +Check out these related projects. + +- [terraform-aws-ecs-codepipeline](https://github.com/cloudposse/terraform-aws-ecs-codepipeline) - Terraform Module for CI/CD with AWS Code Pipeline and Code Build for ECS https://cloudposse.com/ +- [terraform-aws-ecs-events](https://github.com/cloudposse/terraform-aws-ecs-events) - Provide a standard set of ECS events that notify an SNS topic +- [terraform-aws-ecs-cloudwatch-autoscaling](https://github.com/cloudposse/terraform-aws-ecs-cloudwatch-autoscaling) - Terraform module to autoscale ECS Service based on CloudWatch metrics +- [terraform-aws-ecs-container-definition](https://github.com/cloudposse/terraform-aws-ecs-container-definition) - A Terraform module to generate well-formed JSON documents (container definitions) that are passed to the aws_ecs_task_definition Terraform resource +- [terraform-aws-ecs-launch-template](https://github.com/cloudposse/terraform-aws-ecs-launch-template) - Terraform module for generating an AWS Launch Template for ECS that handles draining on Spot Termination Requests +- [terraform-aws-ecs-web-app](https://github.com/cloudposse/terraform-aws-ecs-web-app) - Terraform module that implements a web app on ECS and supporting AWS resources. +- [terraform-aws-ecs-spot-fleet](https://github.com/cloudposse/terraform-aws-ecs-spot-fleet) - [wip] Terraform module to create a diversified spot fleet for ECS clusters +- [terraform-aws-ecs-cloudwatch-sns-alarms](https://github.com/cloudposse/terraform-aws-ecs-cloudwatch-sns-alarms) - Terraform module to create CloudWatch Alarms on ECS Service level metrics. +- [terraform-aws-ecs-alb-service-task](https://github.com/cloudposse/terraform-aws-ecs-alb-service-task) - A Terraform module which implements an ECS service which exposes a web service via ALB. + + + ## Help **Got a question?** -File a GitHub [issue](https://github.com/cloudposse/terraform-aws-ecs-container-definition/issues), send us an [email](mailto:hello@cloudposse.com) or reach out to us on [Gitter](https://gitter.im/cloudposse/). +File a GitHub [issue](https://github.com/cloudposse/terraform-aws-ecs-container-definition/issues), send us an [email][email] or join our [Slack Community][slack]. + +## Commerical Support + +Work directly with our team of DevOps experts via email, slack, and video conferencing. + +We provide *commercial support* for all of our [Open Source][github] projects. As a *Dedicated Support* customer, you have access to our team of subject matter experts at a fraction of the cost of a fulltime engineer. + +[![E-Mail](https://img.shields.io/badge/email-hello@cloudposse.com-blue.svg)](mailto:hello@cloudposse.com) + +- **Questions.** We'll use a Shared Slack channel between your team and ours. +- **Troubleshooting.** We'll help you triage why things aren't working. +- **Code Reviews.** We'll review your Pull Requests and provide constructive feedback. +- **Bug Fixes.** We'll rapidly work to fix any bugs in our projects. +- **Build New Terraform Modules.** We'll develop original modules to provision infrastructure. +- **Cloud Architecture.** We'll assist with your cloud strategy and design. +- **Implementation.** We'll provide hands on support to implement our reference architectures. + + +## Community Forum + +Get access to our [Open Source Community Forum][slack] on Slack. It's **FREE** to join for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build *sweet* infrastructure. ## Contributing @@ -22,7 +126,7 @@ Please use the [issue tracker](https://github.com/cloudposse/terraform-aws-ecs-c ### Developing -If you are interested in being a contributor and want to get involved in developing `terraform-aws-ecs-container-definition`, we would love to hear from you! Shoot us an [email](mailto:hello@cloudposse.com). +If you are interested in being a contributor and want to get involved in developing this project or [help out](https://github.com/orgs/cloudposse/projects/3) with our other projects, we would love to hear from you! Shoot us an [email](mailto:hello@cloudposse.com). In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow. @@ -30,13 +134,20 @@ In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow. 2. **Clone** the project to your own machine 3. **Commit** changes to your own branch 4. **Push** your work back up to your fork - 5. Submit a **Pull request** so that we can review your changes + 5. Submit a **Pull Request** so that we can review your changes + +**NOTE:** Be sure to merge the latest changes from "upstream" before making a pull request! + + +## Copyright -**NOTE:** Be sure to merge the latest from "upstream" before making a pull request! +Copyright © 2017-2018 [Cloud Posse, LLC](https://cloudposse.com) -## License -[APACHE 2.0](LICENSE) © 2018 [Cloud Posse, LLC](https://cloudposse.com) + +## License + +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) See [LICENSE](LICENSE) for full details. @@ -48,7 +159,7 @@ See [LICENSE](LICENSE) for full details. "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 + https://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an @@ -57,35 +168,47 @@ See [LICENSE](LICENSE) for full details. specific language governing permissions and limitations under the License. -## About -`terraform-aws-ecs-container-definition` is maintained and funded by [Cloud Posse, LLC][website]. -![Cloud Posse](https://cloudposse.com/logo-300x69.png) -Like it? Please let us know at -We love [Open Source Software](https://github.com/cloudposse/)! -See [our other projects][community] -or [hire us][hire] to help build your next cloud platform. + +## Trademarks + +All other trademarks referenced herein are the property of their respective owners. + +## About + +This project is maintained and funded by [Cloud Posse, LLC][website]. Like it? Please let us know at + +[![Cloud Posse](https://cloudposse.com/logo-300x69.svg)](https://cloudposse.com) + +We're a [DevOps Professional Services][hire] company based in Los Angeles, CA. We love [Open Source Software](https://github.com/cloudposse/)! + +We offer paid support on all of our projects. + +Check out [our other projects][github], [apply for a job][jobs], or [hire us][hire] to help with your cloud strategy and implementation. + + [docs]: https://docs.cloudposse.com/ [website]: https://cloudposse.com/ - [community]: https://github.com/cloudposse/ + [github]: https://github.com/cloudposse/ + [jobs]: https://cloudposse.com/jobs/ [hire]: https://cloudposse.com/contact/ + [slack]: https://slack.cloudposse.com/ + [linkedin]: https://www.linkedin.com/company/cloudposse + [twitter]: https://twitter.com/cloudposse/ + [email]: mailto:hello@cloudposse.com + + +### Contributors +| [![Sarkis Varozian][sarkis_avatar]][sarkis_homepage]
[Sarkis Varozian][sarkis_homepage] | +|---| -## Contributors + [sarkis_homepage]: https://github.com/sarkis + [sarkis_avatar]: https://github.com/sarkis.png?size=150 -| [![Erik Osterman][erik_img]][erik_web]
[Erik Osterman][erik_web] | [![Andriy Knysh][andriy_img]][andriy_web]
[Andriy Knysh][andriy_web] |[![Igor Rodionov][igor_img]][igor_web]
[Igor Rodionov][igor_img]|[![Sarkis Varozian][sarkis_img]][sarkis_web]
[Sarkis Varozian][sarkis_web] | -|-------------------------------------------------------|------------------------------------------------------------------|------------------------------------------------------------------|------------------------------------------------------------------| -[erik_img]: http://s.gravatar.com/avatar/88c480d4f73b813904e00a5695a454cb?s=144 -[erik_web]: https://github.com/osterman/ -[andriy_img]: https://avatars0.githubusercontent.com/u/7356997?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 -[andriy_web]: https://github.com/aknysh/ -[igor_img]: http://s.gravatar.com/avatar/bc70834d32ed4517568a1feb0b9be7e2?s=144 -[igor_web]: https://github.com/goruha/ -[sarkis_img]: https://avatars3.githubusercontent.com/u/42673?s=144&v=4 -[sarkis_web]: https://github.com/sarkis/ diff --git a/README.yaml b/README.yaml new file mode 100644 index 0000000..bac2548 --- /dev/null +++ b/README.yaml @@ -0,0 +1,74 @@ +--- +# +# This is the canonical configuration for the `README.md` +# Run `make readme` to rebuild the `README.md` +# + +# Name of this project +name: terraform-aws-ecs-container-definition + +# Logo for this project +#logo: docs/logo.png + +# License of this project +license: "APACHE2" + +# Canonical GitHub repo +github_repo: cloudposse/terraform-aws-ecs-container-definition + +# Badges to display +badges: + - name: "Build Status" + image: "https://travis-ci.org/cloudposse/terraform-aws-ecs-container-definition.svg?branch=master" + url: "https://travis-ci.org/cloudposse/terraform-aws-ecs-container-definition" + - name: "Latest Release" + image: "https://img.shields.io/github/release/cloudposse/terraform-aws-ecs-container-definition.svg" + url: "https://github.com/cloudposse/terraform-aws-ecs-container-definition/releases/latest" + - name: "Slack Community" + image: "https://slack.cloudposse.com/badge.svg" + url: "https://slack.cloudposse.com" + +related: + - name: "terraform-aws-ecs-codepipeline" + description: "Terraform Module for CI/CD with AWS Code Pipeline and Code Build for ECS https://cloudposse.com/" + url: "https://github.com/cloudposse/terraform-aws-ecs-codepipeline" + - name: "terraform-aws-ecs-events" + description: "Provide a standard set of ECS events that notify an SNS topic" + url: "https://github.com/cloudposse/terraform-aws-ecs-events" + - name: "terraform-aws-ecs-cloudwatch-autoscaling" + description: "Terraform module to autoscale ECS Service based on CloudWatch metrics" + url: "https://github.com/cloudposse/terraform-aws-ecs-cloudwatch-autoscaling" + - name: "terraform-aws-ecs-container-definition" + description: "A Terraform module to generate well-formed JSON documents (container definitions) that are passed to the aws_ecs_task_definition Terraform resource" + url: "https://github.com/cloudposse/terraform-aws-ecs-container-definition" + - name: "terraform-aws-ecs-launch-template" + description: "Terraform module for generating an AWS Launch Template for ECS that handles draining on Spot Termination Requests" + url: "https://github.com/cloudposse/terraform-aws-ecs-launch-template" + - name: "terraform-aws-ecs-web-app" + description: "Terraform module that implements a web app on ECS and supporting AWS resources." + url: "https://github.com/cloudposse/terraform-aws-ecs-web-app" + - name: "terraform-aws-ecs-spot-fleet" + description: "[wip] Terraform module to create a diversified spot fleet for ECS clusters" + url: "https://github.com/cloudposse/terraform-aws-ecs-spot-fleet" + - name: "terraform-aws-ecs-cloudwatch-sns-alarms" + description: "Terraform module to create CloudWatch Alarms on ECS Service level metrics." + url: "https://github.com/cloudposse/terraform-aws-ecs-cloudwatch-sns-alarms" + - name: "terraform-aws-ecs-alb-service-task" + description: "A Terraform module which implements an ECS service which exposes a web service via ALB." + url: "https://github.com/cloudposse/terraform-aws-ecs-alb-service-task" + +# Short description of this project +description: |- + Terraform module to generate well-formed JSON documents that are passed to the `aws_ecs_task_definition` Terraform resource as [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions). +# How to use this project +usage: |- + This module is meant to be used as output only, meaning it will be used to create outputs which are consumed as a parameter by Terraform resources or other modules. + +include: + - "docs/targets.md" + - "docs/terraform.md" + +# Contributors to this project +contributors: + - name: "Sarkis Varozian" + github: "sarkis" \ No newline at end of file diff --git a/docs/targets.md b/docs/targets.md new file mode 100644 index 0000000..09c39cd --- /dev/null +++ b/docs/targets.md @@ -0,0 +1,9 @@ +## Makefile Targets +``` +Available targets: + + help This help screen + help/all Display help for all targets + lint Lint terraform code + +``` diff --git a/docs/terraform.md b/docs/terraform.md new file mode 100644 index 0000000..4a4071e --- /dev/null +++ b/docs/terraform.md @@ -0,0 +1,29 @@ + +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|:----:|:-----:|:-----:| +| command | The command that is passed to the container. | string | `` | no | +| container_cpu | The number of cpu units to reserve for the container. This is optional for tasks using Fargate launch type and the total amount of container_cpu of all containers in a task will need to be lower than the task-level cpu value. | string | `256` | no | +| container_image | The image used to start the container. Images in the Docker Hub registry available by default. | string | - | yes | +| container_memory | The amount of memory (in MiB) to allow the container to use. This is a hard limit, if the container attempts to exceed the container_memory, the container is killed. This field is optional for Fargate launch type and the total amount of container_memory of all containers in a task will need to be lower than the task memory value. | string | `256` | no | +| container_memory_reservation | The amount of memory (in MiB) to reserve for the container. If container needs to exceed this threshold, it can do so up to the set container_memory hard limit. | string | `128` | no | +| container_name | The name of the container. Up to 255 characters ([a-z], [A-Z], [0-9], -, _ allowed). | string | - | yes | +| container_port | The port number on the container bound to assigned host_port. | string | `80` | no | +| entrypoint | The entry point that is passed to the container. | string | `` | no | +| environment | The environment variables to pas to the container. This is a list of maps. | string | `` | no | +| essential | Determines whether all other containers in a task are stopped, if this container fails or stops for any reason. Due to how Terraform type casts booleans in json it is required to double quote this value. | string | `true` | no | +| healthcheck | A map containing command (string), interval (duration in seconds), retries (1-10, number of times to retry before marking container unhealthy, and startPeriod (0-300, optional grace period to wait, in seconds, before failed healthchecks count toward retries) | string | `` | no | +| host_port | The port number on the container instance (host) to reserve for the container_port. If using containers in a task with the awsvpc or host network mode, the hostPort can either be left blank or set to the same value as the containerPort. | string | `80` | no | +| log_driver | The log driver to use for the container. If using Fargate launch type, only supported value is awslogs. | string | `awslogs` | no | +| log_options | The configuration options to send to the log_driver. | string | `` | no | +| protocol | The protocol used for the port mapping. Options: tcp or udp. | string | `tcp` | no | +| readonly_root_filesystem | Determines whether a container is given read-only access to its root filesystem. Due to how Terraform type casts booleans in json it is required to double quote this value. | string | `false` | no | +| working_directory | The working directory to run commands inside the container. | string | `` | no | + +## Outputs + +| Name | Description | +|------|-------------| +| json | JSON encoded container definitions for use with other terraform resources such as aws_ecs_task_definition. | +