mirror of https://github.com/docker/compose.git
Document ECS supported compose attributes
Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
This commit is contained in:
Nicolas De Loof
parent
2b8fa9934e
commit
5ee75c70c9
|
|
@ -0,0 +1,176 @@
|
|||
# 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
|
||||
```
|
||||
Loading…
Reference in New Issue