diff --git a/cloud/ecs-integration.md b/cloud/ecs-integration.md index a0c3320b05..d744d8db95 100644 --- a/cloud/ecs-integration.md +++ b/cloud/ecs-integration.md @@ -426,6 +426,57 @@ services: The Docker Compose CLI relies on [Amazon CloudFormation](https://docs.aws.amazon.com/cloudformation/){: target="_blank" rel="noopener" class="_"} to manage the application deployment. To get more control on the created resources, you can use `docker compose convert` to generate a CloudFormation stack file from your Compose file. This allows you to inspect resources it defines, or customize the template for your needs, and then apply the template to AWS using the AWS CLI, or the AWS web console. +Once you have identified the changes required to your CloudFormation template, you can include _overlays_ in your +Compose file that will be automatically applied on `compose up`. An _overlay_ is a yaml object that uses the same CloudFormation template data structure as the one generated by ECS integration, but only contains attributes to +be updated or added. It will be merged with the generated template before being applied on the AWS infrastructure. + +### Adjusting Load Balancer http HealthCheck configuration + +While ECS cluster uses the `HealthCheck` command on container to get service health, Application Load Balancers define +their own URL-based HealthCheck mechanism so traffic gets routed. As the Compose model does not offer such an +abstraction (yet), the default one is applied, which queries your service under `/` expecting HTTP status code +`200`. + +You can tweak this behavior using a cloudformation overlay by following the [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticloadbalancingv2-targetgroup.html){:target="_blank" rel="noopener" class="_"} for +configuration reference: + +```yaml +services: + webapp: + image: acme/webapp + ports: + - "80:80" + +x-aws-cloudformation: + Resources: + WebappTCP80TargetGroup: + Properties: + HealthCheckPath: /health + Matcher: + HttpCode: 200-499 +``` + +### Setting SSL termination by Load Balancer + +You can use Application Load Balancer to handle the SSL termination for HTTPS services, so that your code, which ran inside +a container, doesn't have to. This is currently not supported by the ECS integration due to the lack of an equivalent abstraction in the Compose specification. However, you can rely on overlays to enable this feature on generated Listeners configuration: + +```yaml +services: + webapp: + image: acme/webapp + ports: + - "80:80" + +x-aws-cloudformation: + Resources: + WebappTCP80Listener: + Properties: + Certificates: + - CertificateArn: "arn:aws:acm:certificate/123abc" + Protocol: HTTPS +``` + ## Using existing AWS network resources By default, the Docker Compose CLI creates an ECS cluster for your Compose application, a Security Group per network in your Compose file on your AWS account’s default VPC, and a LoadBalancer to route traffic to your services.