|
|
@@ -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
|
|
|
+```
|
Nicolas De loof