ECS integration Compose features

Important

Docker Compose's integration for ECS and ACI is retiring in November 2023. {: .important}

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
KeysMapNotes
Service
service.service.buildxIgnored. No image build support on AWS.
service.cap_add, cap_dropSupported with Fargate limitationsopen_in_new
service.command
service.configsx
service.cgroup_parentx
service.container_namex
service.credential_specx
service.deploy
service.deploy.endpoint_modex
service.deploy.modex
service.deploy.replicasSet service initial scale. Auto-scaling, when enabled, will make this dynamic
service.deploy.placementUsed with EC2 support to select a machine type and AMI
service.deploy.update_config
service.deploy.resourcesFargate resource is selected with the lowest instance type for configured memory and cpu
service.deploy.restart_policy
service.deploy.labels
service.devicesx
service.depends_onImplemented using CloudFormation Depends_on
service.dnsx
service.dns_searchx
service.domainnamex
service.tmpfsxNot supported on Fargate, see https://github.com/docker/compose-cli/issues/839open_in_new
service.entrypoint
service.env_file
service.environment
service.exposex
service.extends
service.external_linksx
service.extra_hostsx
service.group_addx
service.healthcheckThis 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.hostnamex
service.imagePrivate images will be accessible by passing x-aws-pull_policy with ARN of a username+password secret
service.isolationx
service.labelsx
service.linksx
service.loggingCan be used to customize CloudWatch Logs configuration
service.network_modex
service.networksxCommunication between services is implemented by SecurityGroups within the application VPC.
service.pidx
service.portsOnly symetrical port mapping is supported in ECS. See Exposing ports.
service.secretsSee Secrets.
service.security_optx
service.stop_grace_periodx
service.stop_signalx
service.sysctlsx
service.ulimitsOnly support nofile ulimit due to Fargate limitations
service.userns_modex
service.volumesMapped to EFS File Systems. See Persistent volumes.
service.restartxReplaced by service.deployment.restart_policy
Volumex
driverSee Persistent volumes.
driver_opts
externalname must be an EFS filesystem ID
labelsx
Secretx
externalname must be set to secret's ARN
filefile content will be uploaded into AWS Secret Manager
Configx

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-.

  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 exposed 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 through 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:

  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.

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

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 sizeopen_in_new that will match those limits.

services:
    nginx:
        image: mycompany/webapp
        deploy:
          resources:
            limits:
              cpus: '0.5'
              memory: 2Gb