Configure the Docker for AWS load balancer

Estimated reading time: 4 minutes

How does it work?

When you create a service, any ports that are exposed with -p are automatically exposed through the platform load balancer:

$ docker service create --name nginx -p 80:80 nginx

This opens up port 80 on the Elastic Load Balancer (ELB) and direct any traffic on that port, to your swarm service.

How can I configure my load balancer to support SSL/TLS traffic?

Docker uses Amazons’ ACM service, which provides free SSL/TLS certificates, and can be used with ELBs. You need to create a new certificate for your domain, and get the ARN for that certificate.

You add a label to your service to tell swarm that you want to use a given ACM cert for SSL connections to your service.

Examples

Start a service and listen on the ELB with ports 80 and 443. Port 443 is served using a SSL certificate from ACM, which is referenced by the ARN that is described in the service label com.docker.aws.lb.arn

$ docker service create \
  --name demo \
  --detach=true \
  --publish 80:80 \
  --publish 443:80 \
  --label com.docker.aws.lb.arn="arn:aws:acm:us-east-1:0123456789:certificate/c02117b6-2b5f-4507-8115-87726f4ab963" \
  yourname/your-image:latest

By default when you add an ACM ARN as a label, it listens on port 443. If you want to change which port to listen too you append an @ symbol and a list of ports you want to expose.

links SSL to port 443

com.docker.aws.lb.arn="arn:..."

links SSL to port 444

com.docker.aws.lb.arn="arn:...@444"

links SSL to ports 444 and 8080

com.docker.aws.lb.arn="arn:...@444,8080"

More full examples

Listen for HTTP on ports 80 and HTTPS on 444

$ docker service create \
  --name demo \
  --detach=true \
  --publish 80:80 \
  --publish 444:80 \
  --label com.docker.aws.lb.arn="arn:aws:acm:us-east-1:0123456789:certificate/c02117b6-2b5f-4507-8115-87726f4ab963@444" \
   yourname/your-image:latest

SSL listen on port 444 and 443

$ docker service create \
  --name demo \
  --detach=true \
  --publish 80:80 \
  --publish 444:80 \
  --label com.docker.aws.lb.arn="arn:aws:acm:us-east-1:0123456789:certificate/c02117b6-2b5f-4507-8115-87726f4ab963@443,444" \
   yourname/your-image:latest

SSL listen on port 8080

$ docker service create \
  --name demo \
  --detach=true \
  --publish 8080:80 \
  --label com.docker.aws.lb.arn="arn:aws:acm:us-east-1:0123456789:certificate/c02117b6-2b5f-4507-8115-87726f4ab963@8080" \
  yourname/your-image:latest

HTTPS vs SSL load balancer protocols

Docker for AWS version 17.07.0 and later also support the HTTPS listener protocol when using ACM certificates.

Use the HTTPS protocol if your app relies on checking the X-Forwarded-For header for resolving the client IP address. Note that the client IP is also available with SSL by using the Proxy Protocol, but many apps and app frameworks don’t support this.

The only valid options are HTTPS and SSL. Specifying any other value will cause SSL to be selected. For backwards compatibility the default protocol is SSL.

A HTTPS listener on port 443

com.docker.aws.lb.arn="arn:...@HTTPS:443"

A SSL (TCP) listener on port 443

com.docker.aws.lb.arn="arn:...@443"

com.docker.aws.lb.arn="arn:...@SSL:443"

A HTTPS listener on port 443, and a SSL (TCP) listener on port 8080

com.docker.aws.lb.arn="arn:...@HTTPS:443,8080"

A SSL (TCP) listener on port 443 and 8080

Since BAD isn’t a valid option, it will revert back to a SSL (TCP) port for 443.

com.docker.aws.lb.arn="arn:...@BAD:443,8080"

Add a CNAME for your ELB

Once you have your ELB setup, with the correct listeners and certificates, you need to add a DNS CNAME that points to your ELB at your DNS provider.

ELB SSL limitations

If you remove the service that has the com.docker.aws.lb.arn label, that listener and certificate is removed from the ELB.
If you edit the ELB config directly from the dashboard, the changes are removed after the next update.

Can I manually change the ELB configuration?

No. If you make any manual changes to the ELB, they are removed the next time we update the ELB configuration based on any swarm changes. This is because the swarm service configuration is the source of record for service ports. If you add listeners to the ELB manually, they could conflict with what is in swarm, and cause issues.

aws load balancer elb