From bdb8ad0b95234c5f8827286355d824578eb09f71 Mon Sep 17 00:00:00 2001 From: Christopher Crone Date: Thu, 9 Jul 2020 12:25:34 +0200 Subject: [PATCH] readme: Tidy and add docs link Signed-off-by: Christopher Crone Signed-off-by: Nicolas De Loof --- ecs/README.md | 86 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 56 insertions(+), 30 deletions(-) diff --git a/ecs/README.md b/ecs/README.md index bf721a3aa..d948263b6 100644 --- a/ecs/README.md +++ b/ecs/README.md @@ -2,21 +2,34 @@ ## Status -:exclamation: The Docker ECS plugin is still in Beta. It's design and UX will evolve until 1.0 Final release. +:exclamation: The Docker ECS plugin is still in Beta. +Its design and UX will evolve until 1.0 Final release. -## Example +## 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 -ECS plugin is a [Docker CLI plugin](https://docs.docker.com/engine/extend/cli_plugins/) -root command `ecs` require aws profile to get API credentials from `~/.aws/credentials` -as well as AWS region - those will later be stored in a docker context +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` is parsed and converted into a [CloudFormation](https://aws.amazon.com/cloudformation/) -template, which will create all resources in dependent order and cleanup on -`down` command or deployment failure. +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: ``` +--------------------------------------+ @@ -24,48 +37,61 @@ template, which will create all resources in dependent order and cleanup on +--------------------------------------+ - Load +--------------------------------------+ - | compose Model | + | Compose Model | +--------------------------------------+ - Validate +--------------------------------------+ - | compose Model suitable for ECS | + | Compose Model suitable for ECS | +--------------------------------------+ - Convert +--------------------------------------+ | CloudFormation Template | +--------------------------------------+ - Apply - +--------------+ +----------------+ + +--------------+ +----------------+ | AWS API | or | stack file | +--------------+ +----------------+ ``` -* _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. -* _Validate_ phase is responsible to inject sane ECS defaults into the compose-go model, and validate the `compose.yaml` -file do not include unsupported features. -* _Convert_ produces a CloudFormation template to define all resources required to implement the application model on AWS. -* _Apply_ phase do apply the CloudFormation template, either by exporting to a stack file or to deploy on AWS. +* 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. Compose specification has no support for multi-container services, nor -does it support sidecars. When an ECS feature requires a sidecar, we introduce custom Compose extension (`x-aws-*`) -to actually expose ECS feature as a service-level feature, not plumbing details. +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 Compose model to AWS SecurityGroups. The whole application is created within a -single VPC, SecurityGroups are created per networks, including the implicit `default` one. Services are attached -according to the networks declared in Compose model. Doing so, services attached to a common security group can -communicate together, while services from distinct SecurityGroups can't. We just can't set service aliasses per network. +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: -A CloudMap private namespace is created for application as `{project}.local`. Services get registered so that we -get service discovery and DNS round-robin (equivalent for Compose's `endpoint_mode: dnsrr`). Docker images SHOULD -include a tiny entrypoint script to replicate this feature: ```shell script -if [ ! -z LOCALDOMAIN ]; then echo "search ${LOCALDOMAIN}" >> /etc/resolv.conf; fi -``` - +if [ ! -z LOCALDOMAIN ]; then echo "search ${LOCALDOMAIN}" >> /etc/resolv.conf; fi +```