Skip to content

Commit 77ee65a

Browse files
author
jasonwalsh
committed
Update README.md and include module examples
- Include module inputs and outputs - Include examples - Update outputs to include `arn`, `family`, and `revision` of the task definition
1 parent 15c3016 commit 77ee65a

File tree

3 files changed

+217
-0
lines changed

3 files changed

+217
-0
lines changed

‎README.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,161 @@
11
[![CircleCI](https://circleci.com/gh/mongodb/terraform-aws-ecs-task-definition.svg?style=svg)](https://circleci.com/gh/mongodb/terraform-aws-ecs-task-definition)
2+
3+
> A Terraform module for creating Amazon [ECS Task Definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html)
4+
5+
## Contents
6+
7+
- [Motivation](#motivation)
8+
- [Use Cases](#use-cases)
9+
- [Requirements](#requirements)
10+
- [Usage](#usage)
11+
- [Inputs](#inputs)
12+
- [Outputs](#outputs)
13+
- [Testing](#testing)
14+
15+
## Motivation
16+
17+
The purpose of this module is to generate a valid Amazon [ECS Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) dynamically. A task definition is required to run Docker containers in Amazon ECS. A task definition contains a list of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions) received by the Docker daemon to create a container instance.
18+
19+
### Use Cases
20+
21+
- Have Terraform generate valid task definitions dynamically
22+
- Update the ECS task definition and trigger new [service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) deployments automatically (see [examples/ecs_update_service.tf](examples/ecs_update_service.tf))
23+
24+
## Requirements
25+
26+
- [Terraform](https://www.terraform.io/downloads.html)
27+
- [Go](https://golang.org/dl/) (for testing)
28+
29+
## Usage
30+
31+
This module uses the same parameters as the [`ContainerDefinition`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDefinition.html) object. Given the following Terraform configuration:
32+
33+
```hcl
34+
provider "aws" {}
35+
36+
module "mongo-task-definition" {
37+
source = "github.com/mongodb/terraform-aws-ecs-task-definition"
38+
39+
family = "mongo"
40+
image = "mongo:3.6"
41+
memory = 512
42+
name = "mongo"
43+
44+
portMappings = [
45+
{
46+
containerPort = 27017
47+
},
48+
]
49+
}
50+
```
51+
52+
Invoking the commands defined below creates an ECS task definition with the following [`containerDefinitions`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RegisterTaskDefinition.html#ECS-RegisterTaskDefinition-request-containerDefinitions):
53+
54+
$ terraform init
55+
$ terraform apply
56+
57+
```json
58+
[
59+
{
60+
"command": null,
61+
"cpu": null,
62+
"disableNetworking": false,
63+
"dnsSearchDomains": null,
64+
"dnsServers": null,
65+
"dockerLabels": null,
66+
"dockerSecurityOptions": null,
67+
"entryPoint": null,
68+
"environment": null,
69+
"essential": true,
70+
"extraHosts": null,
71+
"healthCheck": null,
72+
"hostname": null,
73+
"image": "mongo:3.6",
74+
"interactive": false,
75+
"links": null,
76+
"linuxParameters": null,
77+
"logConfiguration": null,
78+
"memory": 512,
79+
"memoryReservation": null,
80+
"mountPoints": null,
81+
"name": "mongo",
82+
"portMappings": [{"containerPort":27017}],
83+
"privileged": false,
84+
"pseudoTerminal": false,
85+
"readonlyRootFilesystem": false,
86+
"repositoryCredentials": null,
87+
"resourceRequirements": null,
88+
"secrets": null,
89+
"systemControls": null,
90+
"ulimits": null,
91+
"user": null,
92+
"volumesFrom": null,
93+
"workingDirectory": null
94+
}
95+
]
96+
```
97+
98+
## Inputs
99+
100+
| Name | Description | Type | Default | Required |
101+
|------|-------------|:----:|:-----:|:-----:|
102+
| command | The command that is passed to the container | list | `<list>` | no |
103+
| cpu | The number of cpu units reserved for the container | string | `"0"` | no |
104+
| disableNetworking | When this parameter is true, networking is disabled within the container | string | `"false"` | no |
105+
| dnsSearchDomains | A list of DNS search domains that are presented to the container | list | `<list>` | no |
106+
| dnsServers | A list of DNS servers that are presented to the container | list | `<list>` | no |
107+
| dockerLabels | A key/value map of labels to add to the container | map | `<map>` | no |
108+
| dockerSecurityOptions | A list of strings to provide custom labels for SELinux and AppArmor multi-level security systems | list | `<list>` | no |
109+
| entryPoint | The entry point that is passed to the container | list | `<list>` | no |
110+
| environment | The environment variables to pass to a container | list | `<list>` | no |
111+
| essential | If the essential parameter of a container is marked as true, and that container fails or stops for any reason, all other containers that are part of the task are stopped | string | `"true"` | no |
112+
| execution\_role\_arn | The Amazon Resource Name (ARN) of the task execution role that the Amazon ECS container agent and the Docker daemon can assume | string | `""` | no |
113+
| extraHosts | A list of hostnames and IP address mappings to append to the /etc/hosts file on the container | list | `<list>` | no |
114+
| family | You must specify a family for a task definition, which allows you to track multiple versions of the same task definition | string | n/a | yes |
115+
| healthCheck | The health check command and associated configuration parameters for the container | map | `<map>` | no |
116+
| hostname | The hostname to use for your container | string | `""` | no |
117+
| image | The image used to start a container | string | `""` | no |
118+
| interactive | When this parameter is true, this allows you to deploy containerized applications that require stdin or a tty to be allocated | string | `"false"` | no |
119+
| ipc\_mode | The IPC resource namespace to use for the containers in the task | string | `"host"` | no |
120+
| links | The link parameter allows containers to communicate with each other without the need for port mappings | list | `<list>` | no |
121+
| linuxParameters | Linux-specific modifications that are applied to the container, such as Linux KernelCapabilities | map | `<map>` | no |
122+
| logConfiguration | The log configuration specification for the container | map | `<map>` | no |
123+
| memory | The hard limit (in MiB) of memory to present to the container | string | `"0"` | no |
124+
| memoryReservation | The soft limit (in MiB) of memory to reserve for the container | string | `"0"` | no |
125+
| mountPoints | The mount points for data volumes in your container | list | `<list>` | no |
126+
| name | The name of a container | string | `""` | no |
127+
| network\_mode | The Docker networking mode to use for the containers in the task | string | `"bridge"` | no |
128+
| pid\_mode | The process namespace to use for the containers in the task | string | `"host"` | no |
129+
| placement\_constraints | An array of placement constraint objects to use for the task | list | `<list>` | no |
130+
| portMappings | The list of port mappings for the container | list | `<list>` | no |
131+
| privileged | When this parameter is true, the container is given elevated privileges on the host container instance (similar to the root user) | string | `"false"` | no |
132+
| pseudoTerminal | When this parameter is true, a TTY is allocated | string | `"false"` | no |
133+
| readonlyRootFilesystem | When this parameter is true, the container is given read-only access to its root file system | string | `"false"` | no |
134+
| repositoryCredentials | The private repository authentication credentials to use | map | `<map>` | no |
135+
| requires\_compatibilities | The launch type required by the task | list | `<list>` | no |
136+
| resourceRequirements | The type and amount of a resource to assign to a container | list | `<list>` | no |
137+
| secrets | The secrets to pass to the container | list | `<list>` | no |
138+
| systemControls | A list of namespaced kernel parameters to set in the container | list | `<list>` | no |
139+
| tags | The metadata that you apply to the task definition to help you categorize and organize them | map | `<map>` | no |
140+
| task\_role\_arn | The short name or full Amazon Resource Name (ARN) of the IAM role that containers in this task can assume | string | `""` | no |
141+
| ulimits | A list of ulimits to set in the container | list | `<list>` | no |
142+
| user | The user name to use inside the container | string | `""` | no |
143+
| volumes | A list of volume definitions in JSON format that containers in your task may use | list | `<list>` | no |
144+
| volumesFrom | Data volumes to mount from another container | list | `<list>` | no |
145+
| workingDirectory | The working directory in which to run commands inside the container | string | `""` | no |
146+
147+
## Outputs
148+
149+
| Name | Description |
150+
|------|-------------|
151+
| arn | The full Amazon Resource Name (ARN) of the task definition |
152+
| container\_definitions | A list of container definitions in JSON format that describe the different containers that make up your task |
153+
| family | The family of your task definition, used as the definition name |
154+
| revision | The revision of the task in a particular family |
155+
156+
## Testing
157+
158+
This module uses [Terratest](https://github.com/gruntwork-io/terratest), a Go library maintained by [Gruntwork](https://gruntwork.io/), to write automated tests for your infrastructure code. To invoke tests, run the following commands:
159+
160+
$ dep ensure
161+
$ go test -v ./...

‎examples/ecs_update_service.tf‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# This configuration demonstrates forcing the new deployment of an ECS
2+
# service if there is a change to the ECS task definition. The
3+
# configuration uses the `null_resource` provider to invoke the
4+
# `local-exec` provisioner whenever the task definition ARN changes.
5+
#
6+
# To force a new deployment even if there are no changes made to the
7+
# task definition, `taint` the resource:
8+
#
9+
# $ terraform taint null_resource.update-service
10+
11+
provider "aws" {}
12+
13+
module "mongo-task-definition" {
14+
source = "github.com/mongodb/terraform-aws-ecs-task-definition"
15+
16+
family = "mongo"
17+
image = "mongo:3.6"
18+
memory = 512
19+
name = "mongo"
20+
21+
portMappings = [
22+
{
23+
containerPort = 27017
24+
},
25+
]
26+
}
27+
28+
resource "aws_ecs_service" "mongo" {
29+
cluster = "mongo"
30+
name = "mongo"
31+
task_definition = "${module.mongo-task-definition.arn}"
32+
}
33+
34+
resource "null_resource" "update-service" {
35+
triggers = {
36+
arn = "${module.mongo-task-definition.arn}"
37+
}
38+
39+
provisioner "local-exec" {
40+
command = "aws ecs update-service --cluster ${aws_ecs_service.mongo.cluster} --service ${aws_ecs_service.mongo.name} --task-definition ${module.mongo-task-definition.arn} --force-new-deployment"
41+
}
42+
}

‎outputs.tf‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,19 @@
1+
output "arn" {
2+
description = "The full Amazon Resource Name (ARN) of the task definition"
3+
value = "${aws_ecs_task_definition.ecs_task_definition.arn}"
4+
}
5+
16
output "container_definitions" {
27
description = "A list of container definitions in JSON format that describe the different containers that make up your task"
38
value = "${local.container_definitions}"
49
}
10+
11+
output "family" {
12+
description = "The family of your task definition, used as the definition name"
13+
value = "${aws_ecs_task_definition.ecs_task_definition.family}"
14+
}
15+
16+
output "revision" {
17+
description = "The revision of the task in a particular family"
18+
value = "${aws_ecs_task_definition.ecs_task_definition.revision}"
19+
}

0 commit comments

Comments
 (0)