Lexicon & Definitions ¶

Before diving into the examples and getting started, there are a few terms to be familiar to get the most out of the documentation and examples

CloudFormation / CFN ¶

The AWS CloudFormation service.

In AWS CFN, a template is used in order to create a stack. The Stack will then create the resources etc. See more details with the AWS CFN Stack Anatomy

Service Family ¶

When defining a services in Docker Compose, running docker-compose up will start all containers at the same time on the machine running Docker. When deploying to Amazon Web Services (AWS) Elastic Container Service (ECS) using ECS Compose-X, each service is represented as its own Task Definition and Service Definition, and can be managed across multiple hosts.

Sometimes, it is desirable to have more than one container running at the same time, in which case a Family can be used to group multiple containers into the same Task Definition. To define multiple services from the Docker Compose file to be part of the same Family, set the ecs.task.family label in the deploy configuration.

For example, within ECS Compose-X, setting x-ray to true in the service definition automatically adds a sidecar aws-xray-daemon container as an additional container, of the same Family.

Hint

If not specified via the deploy label ecs.task.family , it uses the service name.

For example, below, we indicate that nginx should be part of the “kafdrop” family. The ECS Task Definition will therefore have the settings for the nginx service and the kafdrop service, into one.

           services:
  nginx:
    image: nginx
    deploy:
      labels:
        ecs.task.family: kafdrop

    depends_on:
      - kafdrop

  kafdrop:
    image: kafdrop

          

Tip

You can link the same service to more than one service should the configuration be identical

            services:
  nginx:
    image: nginx
    deploy:
      labels:
        ecs.task.family: kafdrop,grafana # nginx is re-used as-is in both families

  kafdrop:
    image: kafdrop

  grafana:
    image: grafana

           

In the x-elbv2 module, the services listed require to indicate both the Family and the service/container to send traffic to, as the ELBv2 can send traffic to either. Some other features might also require to specify the family:service combination at times.

Otherwise for IAM and most modules, pointing to the service for permissions/access prefers the family name.

Task Definition ¶

The ECS task definition as defined in ECS. This is what determines overall CPU, RAM, docker volumes and source (i.e. EFS) as well as IAM roles to use.

Service Definition ¶

The ECS Cluster uses the service definition to create a service based on the task definition. This service has properties such as the VPC, Subnets, auto-scaling, and other settings that define the deployment.

services.x-feature ¶

Extension fields are used to extend the utility of the ECS Compose-X template, allowing you to customize the behavior of the services in the stack. They are not used by docker-compose, but can be used to add additional features to the template that docker-compose does not support.

For example, here x-s3 is a top level feature of ECS Compose-X, whereas x-scaling only applies at the Service Family level.

           x-s3:               # x-s3 is a top level definition
  bucket-01: {}

services:
  nginx:
    image: nginx
    x-scaling:      # This is a service.x- extension
        Range: 1-10

          

JSON Schema ¶

ECS Compose-X validates the input given to it to maintain the same level of accuracy as Docker Compose, which utilizes the Compose-Spec JSON schema. This simplifies the code and results in a more straightforward syntax. The compose-spec is extended with the additional features in ECS Compose-X.