tyler.durden
/
compose
mirror of https://github.com/docker/compose.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

readme: Tidy and add docs link 

Signed-off-by: Christopher Crone <christopher.crone@docker.com>
Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
This commit is contained in:
Christopher Crone 2020-07-09 12:25:34 +02:00 committed by Nicolas De Loof
parent 164e0d750d
commit bdb8ad0b95
No known key found for this signature in database
GPG Key ID: 9858809D6F8F6E7E
1 changed files with 56 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
ecs/README.md
View File

@ -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
```