mirror of https://github.com/docker/compose.git
177 lines
7.5 KiB
Markdown
177 lines
7.5 KiB
Markdown
|
# Compose - Amazon ECS mapping
|
||
|
|
|
||
|
|
This document outlines the conversion of an application defined in a Compose file to AWS resources.
|
||
|
|
Each service is mapped to an ECS service in the project's cluster.
|
||
|
|
|
||
|
|
## Compose fields mapping
|
||
|
|
|
||
|
|
The table below lists supported Compose file fields and their AWS counterparts.
|
||
|
|
|
||
|
|
__Legend:__
|
||
|
|
|
||
|
|
- __✓:__ Implemented
|
||
|
|
- __n:__ Not yet implemented
|
||
|
|
- __x:__ Not applicable / no available conversion
|
||
|
|
|
||
|
|
| Keys |Map| Notes |
|
||
|
|
|--------------------------------|---|--------------------------------------------------------------|
|
||
|
|
| __Service__ | ✓ |
|
||
|
|
| service.service.build | x | Ignored. No image build support on AWS.
|
||
|
|
| service.cap_add, cap_drop | ✓ | Supported with [Fargate limitations](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_KernelCapabilities.html)
|
||
|
|
| service.command | ✓ |
|
||
|
|
| service.configs | x |
|
||
|
|
| service.cgroup_parent | x |
|
||
|
|
| service.container_name | x |
|
||
|
|
| service.credential_spec | x |
|
||
|
|
| service.deploy | ✓ |
|
||
|
|
| service.deploy.endpoint_mode | x |
|
||
|
|
| service.deploy.mode | x |
|
||
|
|
| service.deploy.replicas | ✓ | Set service initial scale. Auto-scaling, when enabled, will make this dynamic
|
||
|
|
| service.deploy.placement | ✓ | Used with EC2 support to select a machine type and AMI
|
||
|
|
| service.deploy.update_config | ✓ |
|
||
|
|
| service.deploy.resources | ✓ | Fargate resource is selected with the lowest instance type for configured memory and cpu
|
||
|
|
| service.deploy.restart_policy | ✓ |
|
||
|
|
| service.deploy.labels | ✓ |
|
||
|
|
| service.devices | x |
|
||
|
|
| service.depends_on | ✓ | Implemented using CloudFormation Depends_on
|
||
|
|
| service.dns | x |
|
||
|
|
| service.dns_search | x |
|
||
|
|
| service.domainname | x |
|
||
|
|
| service.tmpfs | x | Not supported on Fargate, see https://github.com/docker/compose-cli/issues/839
|
||
|
|
| service.entrypoint | ✓ |
|
||
|
|
| service.env_file | ✓ |
|
||
|
|
| service.environment | ✓ |
|
||
|
|
| service.expose | x |
|
||
|
|
| service.extends | ✓ |
|
||
|
|
| service.external_links | x |
|
||
|
|
| service.extra_hosts | x |
|
||
|
|
| service.group_add | x |
|
||
|
|
| service.healthcheck | ✓ | This configures container level health check as reported on ECS console. Application Load Balancer will also check for HTTP service health by accessing `/` and expect a HTTP 200 status code.
|
||
|
|
| service.hostname | x |
|
||
|
|
| service.image | ✓ | Private images will be accessible by passing x-aws-pull_policy with ARN of a username+password secret
|
||
|
|
| service.isolation | x |
|
||
|
|
| service.labels | x |
|
||
|
|
| service.links | x |
|
||
|
|
| service.logging | ✓ | Can be used to customize CloudWatch Logs configuration
|
||
|
|
| service.network_mode | x |
|
||
|
|
| service.networks | x | Communication between services is implemented by SecurityGroups within the application VPC.
|
||
|
|
| service.pid | x |
|
||
|
|
| service.ports | ✓ | Only symetrical port mapping is supported in ECS. See [Exposing ports](#exposing-ports).
|
||
|
|
| service.secrets | ✓ | See [Secrets](#secrets).
|
||
|
|
| service.security_opt | x |
|
||
|
|
| service.stop_grace_period | x |
|
||
|
|
| service.stop_signal | x |
|
||
|
|
| service.sysctls | x |
|
||
|
|
| service.ulimits | ✓ | Only support `nofile` ulimit due to Fargate limitations
|
||
|
|
| service.userns_mode | x |
|
||
|
|
| service.volumes | ✓ | Mapped to EFS File Systems. See [Persistent volumes](#persistent-volumes).
|
||
|
|
| service.restart | x | Replaced by service.deployment.restart_policy
|
||
|
|
| | |
|
||
|
|
| __Volume__ | x |
|
||
|
|
| driver | ✓ | See [Persistent volumes](#persistent-volumes).
|
||
|
|
| driver_opts | ✓ |
|
||
|
|
| external | ✓ | `name` must be an EFS filesystem ID
|
||
|
|
| labels | x |
|
||
|
|
| | |
|
||
|
|
| __Secret__ | x |
|
||
|
|
| external | ✓ | `name` must be set to secret's ARN
|
||
|
|
| file | ✓ | file content will be uploaded into AWS Secret Manager
|
||
|
|
| | |
|
||
|
|
| __Config__ | x |
|
||
|
|
| | |
|
||
|
|
|
||
|
|
|
||
|
|
## Logs
|
||
|
|
|
||
|
|
Application logs can be obtained container with `docker compose logs`.
|
||
|
|
The Docker ECS integration relies on AWS CloudWatch Logs to collect logs from all containers. CloudWatch can be customized by setting service `logging.driver_opts`
|
||
|
|
by passing configuration attributes prefixed with `awslogs-`.
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
test:
|
||
|
|
image: mycompany/webapp
|
||
|
|
logging:
|
||
|
|
driver-opts:
|
||
|
|
awslogs-datetime-pattern: "some-pattern"
|
||
|
|
```
|
||
|
|
|
||
|
|
|
||
|
|
## Exposing ports
|
||
|
|
|
||
|
|
When one or more services expose ports, a Load Balancer is created for the application.
|
||
|
|
As all services are expose through the same Load Balancer, only one service can expose a given port number.
|
||
|
|
The source and target ports defined in the Compose file MUST be the same, as service-to-service communication don't go trought the Load Balancer and could not
|
||
|
|
benefit from Listeners abstraction to assign a distinct published port.
|
||
|
|
|
||
|
|
If services in the Compose file only expose ports 80 or 443, an Application Load Balancer is created, otherwise ECS integration will provision a Network Load Balancer.
|
||
|
|
HTTP services using distinct ports can force use of an ALB by claiming the http protocol with `x-aws-protocol` custom extension within the port declaration:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
test:
|
||
|
|
image: mycompany/webapp
|
||
|
|
ports:
|
||
|
|
- target: 8080
|
||
|
|
x-aws-protocol: http
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
## Persistent volumes
|
||
|
|
|
||
|
|
Docker volumes are mapped to EFS file systems. Volumes can be external (`name` must then be set to filesystem ID) or will be created when the application is
|
||
|
|
first deployed. `docker compose down` will NOT delete the filesystem, and it will be re-attached to the application on future runs.
|
||
|
|
`driver_opts` can be used to tweak the EFS filsystem.
|
||
|
|
|
||
|
|
Volume mount can be customized to workaround Posix filesystem permission issues by setting user and group IDs to be used to write to filesystem, whatever user
|
||
|
|
is configured to run the container.
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
services:
|
||
|
|
myservice:
|
||
|
|
image: mycompany/webapp
|
||
|
|
volumes:
|
||
|
|
- mydata:/mount/testvolumes
|
||
|
|
|
||
|
|
volumes:
|
||
|
|
mydata:
|
||
|
|
driver_opts:
|
||
|
|
performance-mode: maxIO
|
||
|
|
throughput-mode: bursting
|
||
|
|
uid: 0
|
||
|
|
gid: 0
|
||
|
|
```
|
||
|
|
|
||
|
|
|
||
|
|
## Secrets
|
||
|
|
|
||
|
|
Secrets can be defined in compose files, and will need secret files available at deploy time next to the compose file.
|
||
|
|
The content of the secret file will be made available inside selected containers, by default under `/run/secrets/<SECRET_NAME>`.
|
||
|
|
External secrets are also supported, `name` must then be set to secret's ARN
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
services:
|
||
|
|
nginx:
|
||
|
|
image: mycompany/webapp
|
||
|
|
secrets:
|
||
|
|
- mysecret
|
||
|
|
|
||
|
|
secrets:
|
||
|
|
mysecret:
|
||
|
|
file: ./my_secret1.txt
|
||
|
|
```
|
||
|
|
|
||
|
|
|
||
|
|
## Container Resources
|
||
|
|
|
||
|
|
CPU and memory limits can be set in compose. Those are used to select the minimal [Fargate size](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html) that will match those limits.
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
services:
|
||
|
|
nginx:
|
||
|
|
image: mycompany/webapp
|
||
|
|
deploy:
|
||
|
|
resources:
|
||
|
|
limits:
|
||
|
|
cpu: 0.5
|
||
|
|
memory: 2Gb
|
||
|
|
```
|