From c7752c1f87f85f9ad8534ae3e273d41e05117d48 Mon Sep 17 00:00:00 2001
From: Nicolas De Loof <nicolas.deloof@gmail.com>
Date: Wed, 18 Nov 2020 11:53:37 +0100
Subject: [PATCH] Document custom load balancer usage

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
---
 engine/context/ecs-integration.md | 38 ++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/engine/context/ecs-integration.md b/engine/context/ecs-integration.md
index fa6678af2d..802eaf0135 100644
--- a/engine/context/ecs-integration.md
+++ b/engine/context/ecs-integration.md
@@ -348,7 +348,42 @@ of a VPC when deploying a Compose application.
 - Use `x-aws-loadbalancer` as a top-level element in your Compose file to set
 the ARN of an existing LoadBalancer.
 
-- Use `external: true` inside a network definition in your Compose file for
+The latter can be used for those who want to customize application exposure, typically to
+use an existing domain name for your application:
+
+1. Use AWS web console or CLI to get your VPC and Subnets IDs. You can typically retrieve default VPC ID and attached subnets using this AWS CLI commands:
+```console
+➜  aws ec2 describe-vpcs --filters Name=isDefault,Values=true --query 'Vpcs[0].VpcId' 
+"vpc-123456"
+➜  aws ec2 describe-subnets --filters Name=vpc-id,Values=vpc-123456 --query 'Subnets[*].SubnetId'
+[
+    "subnet-1234abcd", 
+    "subnet-6789ef00", 
+]
+```
+1. Use AWS CLI to create your load balancer. The AWS Web Console can also be used but will require to assing at least one listener, which we don't need here.
+```console
+➜  tutu aws elbv2 create-load-balancer --name myloadbalancer --type application --subnets "subnet-1234abcd" "subnet-6789ef00"
+{
+    "LoadBalancers": [
+        {
+            "IpAddressType": "ipv4", 
+            "VpcId": "vpc-123456", 
+            "LoadBalancerArn": "arn:aws:elasticloadbalancing:us-east-1:1234567890:loadbalancer/app/myloadbalancer/123abcd456", 
+            "DNSName": "myloadbalancer-123456.us-east-1.elb.amazonaws.com", 
+...            
+```
+1. To assign your application an existing domain name, you can configure your DNS with a
+CNAME entry pointing to just-created loadbalancer's `DNSName` reported as you created the loadbalancer.
+
+1. Use Loadbalancer ARN to set `x-aws-loadbalancer` in your compose file, and deploy your application using `docker compose up` command.
+
+Please note Docker ECS integration won't be aware of this domain name, so `docker compose ps` command will report URLs with loadbalancer DNSName, not your own domain.
+
+
+
+
+You also can use `external: true` inside a network definition in your Compose file for
 Docker Compose CLI to _not_ create a Security Group, and set `name` with the
 ID of an existing SecurityGroup you want to use for network connectivity between
 services:
@@ -360,6 +395,7 @@ networks:
     name: "sg-1234acbd"
 ```
 
+
 ## Local simulation
 
 When you deploy your application on ECS, you may also rely on the additional AWS services.