# Docker CLI plugin for Amazon ECS

This was announced at AWS Cloud Containers Conference 2020, read the
[blog post](https://www.docker.com/blog/from-docker-straight-to-aws/).

## Status

:exclamation: The Docker ECS plugin is still in Beta.
Its design and UX will evolve until 1.0 Final release.

## Get started

If you're using macOS or Windows you just need to install
Docker Desktop **Edge** and you will have the ECS integration installed.
You can find links here:
- [macOS](https://hub.docker.com/editions/community/docker-ce-desktop-mac)
- [Windows](https://hub.docker.com/editions/community/docker-ce-desktop-windows)

Linux install instructions are [here](./docs/get-started-linux.md).

## Example and documentation

You can find an application for testing this in [example](./example).

You can find more documentation about using the Docker ECS integration
[here](https://docs.docker.com/engine/context/ecs-integration/).

## Architecture

The Docker ECS integration is a
[Docker CLI plugin](https://docs.docker.com/engine/extend/cli_plugins/)
with the root command of `ecs`.
It requires an AWS profile to select the AWS API credentials from
`~/.aws/credentials` as well as an AWS region. You can read more about CLI AWS
credential management
[here](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).
Once setup, the AWS profile and region are stored in a Docker context.

A `compose.yaml` file is parsed and converted into a
[CloudFormation](https://aws.amazon.com/cloudformation/) template,
which is then used to create all application resources in dependent order.
Resources are cleaned up with the `down` command or in the case of a deployment
failure.

The architecture of the ECS integration is shown below:

```
  +--------------------------------------+
  | compose.yaml file                    |
  +--------------------------------------+
- Load
  +--------------------------------------+
  | Compose Model                        |
  +--------------------------------------+
- Validate
  +--------------------------------------+
  | Compose Model suitable for ECS       |
  +--------------------------------------+
- Convert
  +--------------------------------------+
  | CloudFormation Template              |
  +--------------------------------------+
- Apply
  +--------------+      +----------------+
  | AWS API      |  or  | stack file     |
  +--------------+      +----------------+
```

* The _Load_ phase relies on
  [compose-go](https://github.com/compose-spec/compose-go).
  Any generic code we write for this purpose should be proposed upstream.
* The _Validate_ phase is responsible for injecting sane ECS defaults into the
  compose-go model, and validating the `compose.yaml` file does not include
  unsupported features.
* The _Convert_ phase produces a CloudFormation template to define all
  application resources required to implement the application model on AWS.
* The _Apply_ phase does the actual apply of the CloudFormation template,
  either by exporting to a stack file or to deploy on AWS.

## Application model

### Services

Compose services are mapped to ECS services. The Compose specification does not
have support for multi-container services (like Kubernetes pods) or sidecars.
When an ECS feature requires a sidecar, we use a custom Compose extension
(`x-aws-*`) to expose the ECS features as a service-level feature,
and keep the plumbing details from the user.

### Networking

We map the "network" abstraction from the Compose model to AWS security groups.
The whole application is created within a single VPC,
security groups are created per Compose network, including the implicit
`default` one.
Services are attached according to the networks declared in Compose model.
This approach means that services attached to a common security group can
communicate together, while services from distinct security groups cannot.
This matches the intent of the Compose network model with the limitation that we
cannot set service aliases per network.

A [CloudMap](https://aws.amazon.com/cloud-map/) private namespace is created for
each application as `{project}.local`. Services get registered so that we
have service discovery and DNS round-robin
(equivalent to Compose's `endpoint_mode: dnsrr`). Docker images SHOULD include
an entrypoint script to replicate this feature:

```shell script
if [ ! -z LOCALDOMAIN ]; then echo "search ${LOCALDOMAIN}" >> /etc/resolv.conf; fi
```