tyler.durden/compose
1
0
Fork 0
mirror of https://github.com/docker/compose.git synced 2025-07-28 08:04:09 +02:00
Code Issues Packages Projects Releases Wiki Activity

readme: Tidy and add docs link

Browse Source 
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 ## 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 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 ## Architecture
ECS plugin is a [Docker CLI plugin](https://docs.docker.com/engine/extend/cli_plugins/) The Docker ECS integration is a
root command `ecs` require aws profile to get API credentials from `~/.aws/credentials` [Docker CLI plugin](https://docs.docker.com/engine/extend/cli_plugins/)
as well as AWS region - those will later be stored in a docker context 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/) A `compose.yaml` file is parsed and converted into a
template, which will create all resources in dependent order and cleanup on [CloudFormation](https://aws.amazon.com/cloudformation/) template,
`down` command or deployment failure. 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 - Load
+--------------------------------------+ +--------------------------------------+
| compose Model | | Compose Model |
+--------------------------------------+ +--------------------------------------+
- Validate - Validate
+--------------------------------------+ +--------------------------------------+
| compose Model suitable for ECS | | Compose Model suitable for ECS |
+--------------------------------------+ +--------------------------------------+
- Convert - Convert
+--------------------------------------+ +--------------------------------------+
| CloudFormation Template | | CloudFormation Template |
+--------------------------------------+ +--------------------------------------+
- Apply - Apply
+--------------+ +----------------+ +--------------+ +----------------+
| AWS API | or | stack file | | 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 * The _Load_ phase relies on
purpose should be proposed upstream. [compose-go](https://github.com/compose-spec/compose-go).
* _Validate_ phase is responsible to inject sane ECS defaults into the compose-go model, and validate the `compose.yaml` Any generic code we write for this purpose should be proposed upstream.
file do not include unsupported features. * The _Validate_ phase is responsible for injecting sane ECS defaults into the
* _Convert_ produces a CloudFormation template to define all resources required to implement the application model on AWS. compose-go model, and validating the `compose.yaml` file does not include
* _Apply_ phase do apply the CloudFormation template, either by exporting to a stack file or to deploy on AWS. 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 ## Application model
### Services ### Services
Compose services are mapped to ECS services. Compose specification has no support for multi-container services, nor Compose services are mapped to ECS services. The Compose specification does not
does it support sidecars. When an ECS feature requires a sidecar, we introduce custom Compose extension (`x-aws-*`) have support for multi-container services (like Kubernetes pods) or sidecars.
to actually expose ECS feature as a service-level feature, not plumbing details. 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 ### Networking
We map the "network" abstraction from Compose model to AWS SecurityGroups. The whole application is created within a We map the "network" abstraction from the Compose model to AWS security groups.
single VPC, SecurityGroups are created per networks, including the implicit `default` one. Services are attached The whole application is created within a single VPC,
according to the networks declared in Compose model. Doing so, services attached to a common security group can security groups are created per Compose network, including the implicit
communicate together, while services from distinct SecurityGroups can't. We just can't set service aliasses per network. `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 ```shell script
if [ ! -z LOCALDOMAIN ]; then echo "search ${LOCALDOMAIN}" >> /etc/resolv.conf; fi if [ ! -z LOCALDOMAIN ]; then echo "search ${LOCALDOMAIN}" >> /etc/resolv.conf; fi
``` ```