From cd5bc709406ef886503a2dee9a41e628385c62ca Mon Sep 17 00:00:00 2001 From: Guillaume Tardif Date: Wed, 9 Dec 2020 12:08:34 +0100 Subject: [PATCH] Include ACI/ECS reference docs from compose-cli and make them easier to find for docker users Signed-off-by: Guillaume Tardif --- Dockerfile | 7 ++++ _data/toc.yaml | 14 ++++++- _scripts/fetch-upstream-resources.sh | 9 +++++ {engine/context => cloud}/aci-integration.md | 9 ++++- {engine/context => cloud}/ecs-integration.md | 42 ++++++++++---------- 5 files changed, 58 insertions(+), 23 deletions(-) rename {engine/context => cloud}/aci-integration.md (95%) rename {engine/context => cloud}/ecs-integration.md (94%) diff --git a/Dockerfile b/Dockerfile index 7c30218629..c3e96b94c4 100644 --- a/Dockerfile +++ b/Dockerfile @@ -20,6 +20,9 @@ ARG ENGINE_BRANCH="master" # Distribution ARG DISTRIBUTION_BRANCH="release/2.7" +# Compose CLI +ARG COMPOSE_CLI_BRANCH="main" + ### # Set up base stages for building and deploying ### @@ -35,6 +38,9 @@ ENV ENGINE_BRANCH=${ENGINE_BRANCH} ARG DISTRIBUTION_BRANCH ENV DISTRIBUTION_BRANCH=${DISTRIBUTION_BRANCH} +ARG COMPOSE_CLI_BRANCH +ENV COMPOSE_CLI_BRANCH=${COMPOSE_CLI_BRANCH} + # Fetch upstream resources (reference documentation) # Only add the files that are needed to build these reference docs, so that these # docs are only rebuilt if changes were made to ENGINE_BRANCH or DISTRIBUTION_BRANCH. @@ -45,6 +51,7 @@ WORKDIR /usr/src/app/md_source/ COPY ./_scripts/fetch-upstream-resources.sh ./_scripts/ ARG ENGINE_BRANCH ARG DISTRIBUTION_BRANCH +ARG COMPOSE_CLI_BRANCH RUN ./_scripts/fetch-upstream-resources.sh . diff --git a/_data/toc.yaml b/_data/toc.yaml index cbcc1f417d..d0507afb41 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -81,10 +81,20 @@ guides: title: Configure GitHub Actions - sectiontitle: Deploy your app to the cloud section: - - path: /engine/context/aci-integration/ + - path: /cloud/aci-integration/ title: Docker and ACI - - path: /engine/context/ecs-integration/ + - path: /cloud/aci-container-features/ + title: ACI container features + - path: /cloud/aci-compose-features/ + title: ACI Compose features + - path: /cloud/ecs-integration/ title: Docker and ECS + - path: /cloud/ecs-architecture/ + title: Docker ECS integration architecture + - path: /cloud/ecs-compose-features/ + title: ECS Compose features + - path: /cloud/ecs-compose-examples/ + title: ECS Compose examples - sectiontitle: Run your app in production section: - sectiontitle: Orchestration diff --git a/_scripts/fetch-upstream-resources.sh b/_scripts/fetch-upstream-resources.sh index ff22afe774..4ffb0893cf 100755 --- a/_scripts/fetch-upstream-resources.sh +++ b/_scripts/fetch-upstream-resources.sh @@ -6,6 +6,7 @@ # which are usually set by the Dockerfile. : "${ENGINE_BRANCH?No release branch set for docker/docker and docker/cli}" : "${DISTRIBUTION_BRANCH?No release branch set for docker/distribution}" +: "${COMPOSE_CLI_BRANCH?No release branch set for docker/compose-cli}" # Translate branches for use by svn engine_svn_branch="branches/${ENGINE_BRANCH}" @@ -16,10 +17,15 @@ distribution_svn_branch="branches/${DISTRIBUTION_BRANCH}" if [ "${distribution_svn_branch}" = "branches/master" ]; then distribution_svn_branch=trunk fi +compose_cli_svn_branch="branches/${COMPOSE_CLI_BRANCH}" +if [ "${compose_cli_svn_branch}" = "branches/main" ]; then + compose_cli_svn_branch=trunk +fi # Directories to get via SVN. We use this because you can't use git to clone just a portion of a repository svn co "https://github.com/docker/cli/${engine_svn_branch}/docs/extend" ./engine/extend || (echo "Failed engine/extend download" && exit 1) svn co "https://github.com/docker/docker/${engine_svn_branch}/docs/api" ./engine/api || (echo "Failed engine/api download" && exit 1) +svn co "https://github.com/docker/compose-cli/${compose_cli_svn_branch}/docs" ./cloud || (echo "Failed compose-cli/docs download" && exit 1) svn co "https://github.com/docker/distribution/${distribution_svn_branch}/docs/spec" ./registry/spec || (echo "Failed registry/spec download" && exit 1) svn co "https://github.com/mirantis/compliance/trunk/docs/compliance" ./compliance || (echo "Failed docker/compliance download" && exit 1) @@ -37,3 +43,6 @@ wget --quiet --directory-prefix=./registry/ "https://raw.git # Remove things we don't want in the build rm -f ./engine/extend/cli_plugins.md # the cli plugins api is not a stable API, and not included in the TOC for that reason. rm -f ./registry/spec/api.md.tmpl +rm -f ./cloud/README.md # readme to make things nice in the compose-cli repo, but meaningless here +rm -f ./cloud/architecure.md # Compose-CLI architecture, unrelated to cloud integration +rm -rf ./cloud/images diff --git a/engine/context/aci-integration.md b/cloud/aci-integration.md similarity index 95% rename from engine/context/aci-integration.md rename to cloud/aci-integration.md index 9ea36ac37a..7c786ba9e2 100644 --- a/engine/context/aci-integration.md +++ b/cloud/aci-integration.md @@ -2,6 +2,8 @@ title: Deploying Docker containers on Azure description: Deploying Docker containers on Azure keywords: Docker, Azure, Integration, ACI, context, Compose, cli, deploy, containers, cloud +redirect_from: + - /engine/context/aci-integration/ toc_min: 1 toc_max: 2 --- @@ -16,6 +18,8 @@ In addition, the integration between Docker and Microsoft developer technologies - Set up an ACI context in one Docker command allowing you to switch from a local context to a cloud context and run applications quickly and easily - Simplify single container and multi-container application development using the Compose specification, allowing a developer to invoke fully Docker-compatible commands seamlessly for the first time natively within a cloud container service +Also see the [full list of container features supported by ACI](aci-container-features.md) and [full list of compose features supported by ACI](aci-compose-features.md). + ## Prerequisites To deploy Docker containers on Azure, you must meet the following requirements: @@ -34,6 +38,7 @@ To deploy Docker containers on Azure, you must meet the following requirements: Docker not only runs containers locally, but also enables developers to seamlessly deploy Docker containers on ACI using `docker run` or deploy multi-container applications defined in a Compose file using the `docker compose up` command. The following sections contain instructions on how to deploy your Docker containers on ACI. +Also see the [full list of container features supported by ACI](aci-container-features.md). ### Log into Azure @@ -64,7 +69,7 @@ you have several ones available in Azure. ### Create an ACI context After you have logged in, you need to create a Docker context associated with ACI to deploy containers in ACI. -Creating an ACI context requires an Azure subscription, a resource group, and a region. +Creating an ACI context requires an Azure subscription, a [resource group](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal), and a region. For example, let us create a new context called `myacicontext`: ```console @@ -136,6 +141,8 @@ You can also deploy and manage multi-container applications defined in Compose f All containers in the same Compose application are started in the same container group. Service discovery between the containers works using the service name specified in the Compose file. Name resolution between containers is achieved by writing service names in the `/etc/hosts` file that is shared automatically by all containers in the container group. +Also see the [full list of compose features supported by ACI](aci-compose-features.md). + 1. Ensure you are using your ACI context. You can do this either by specifying the `--context myacicontext` flag or by setting the default context using the command `docker context use myacicontext`. 2. Run `docker compose up` and `docker compose down` to start and then stop a full Compose application. diff --git a/engine/context/ecs-integration.md b/cloud/ecs-integration.md similarity index 94% rename from engine/context/ecs-integration.md rename to cloud/ecs-integration.md index 7b3ece1eae..2523e34759 100644 --- a/engine/context/ecs-integration.md +++ b/cloud/ecs-integration.md @@ -2,6 +2,8 @@ title: Deploying Docker containers on ECS description: Deploying Docker containers on ECS keywords: Docker, AWS, ECS, Integration, context, Compose, cli, deploy, containers, cloud +redirect_from: + - /engine/context/ecs-integration/ toc_min: 1 toc_max: 2 --- @@ -15,6 +17,8 @@ The integration between Docker and Amazon ECS allows developers to use the Docke * Set up an AWS context in one Docker command, allowing you to switch from a local context to a cloud context and run applications quickly and easily * Simplify multi-container application development on Amazon ECS using Compose files +Also see the [ECS integration architecture](ecs-architecture.md), [full list of compose features](ecs-compose-features.md) and [Compose examples for ECS integration](ecs-compose-examples.md). + ## Prerequisites To deploy Docker containers on ECS, you must meet the following requirements: @@ -37,11 +41,9 @@ contain instructions on how to deploy your Compose application on Amazon ECS. ### Requirements -AWS uses a fine-grained permission model, with specific role for each resource type and operation. +AWS uses a fine-grained permission model, with specific role for each resource type and operation. -To ensure that Docker ECS integration is allowed to manage resources for your Compose application, you - -have to ensure your AWS credentials grant access to following AWS IAM permissions: +To ensure that Docker ECS integration is allowed to manage resources for your Compose application, you have to ensure your AWS credentials [grant access to following AWS IAM permissions](https://aws.amazon.com/iam/features/manage-permissions/): * cloudformation:* * ecs:ListAccountSettings @@ -69,7 +71,7 @@ have to ensure your AWS credentials grant access to following AWS IAM permission * route53:GetHostedZone * route53:ListHostedZonesByName -GPU support, which relies on EC2 instances to run containers with attached GPU devices, +GPU support, which relies on EC2 instances to run containers with attached GPU devices, require a few additional permissions: * ec2:DescribeVpcs @@ -79,14 +81,13 @@ require a few additional permissions: * iam:RemoveRoleFromInstanceProfile * iam:DeleteInstanceProfile - ### Create AWS context Run the `docker context create ecs myecscontext` command to create an Amazon ECS Docker context named `myecscontext`. If you have already installed and configured the AWS CLI, the setup command lets you select an existing AWS profile to connect to Amazon. Otherwise, you can create a new profile by passing an -[AWS access key ID and a secret access key](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys){: target="_blank" rel="noopener" class="_"}. +[AWS access key ID and a secret access key](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys){: target="_blank" rel="noopener" class="_"}. Finally, you can configure your ECS context to retrieve AWS credentials by `AWS_*` environment variables, which is a common way to integrate with third-party tools and single-sign-on providers. @@ -101,7 +102,7 @@ After you have created an AWS context, you can list your Docker contexts by runn ```console NAME TYPE DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR -myecscontext ecs credentials read from environment +myecscontext ecs credentials read from environment default * moby Current DOCKER_HOST based configuration unix:///var/run/docker.sock swarm ``` @@ -124,8 +125,8 @@ stop a full Compose application. You can also specify a name for the Compose application using the `--project-name` flag during deployment. If no name is specified, a name will be derived from the working directory. Docker ECS integration converts the Compose application model into a set of AWS resources, described as a [CloudFormation](https://aws.amazon.com/cloudformation/){: target="_blank" rel="noopener" class="_"} template. The actual mapping is described in [technical documentation](https://github.com/docker/compose-cli/blob/main/docs/ecs-architecture.md){: target="_blank" rel="noopener" class="_"}. -You can review the generated template using `docker compose convert` command, and follow CloudFormation applying this model within -[AWS web console](https://console.aws.amazon.com/cloudformation/home){: target="_blank" rel="noopener" class="_"} when you run `docker compose up`, in addition to CloudFormation events being displayed +You can review the generated template using `docker compose convert` command, and follow CloudFormation applying this model within +[AWS web console](https://console.aws.amazon.com/cloudformation/home){: target="_blank" rel="noopener" class="_"} when you run `docker compose up`, in addition to CloudFormation events being displayed in your terminal. - You can view services created for the Compose application on Amazon ECS and @@ -134,6 +135,7 @@ their state using the `docker compose ps` command. - You can view logs from containers that are part of the Compose application using the `docker compose logs` command. +Also see the [full list of compose features](ecs-compose-features.md). ## Rolling update @@ -426,11 +428,11 @@ services: If your AWS account does not have [permissions](https://github.com/docker/ecs-plugin/blob/master/docs/requirements.md#permissions){: target="_blank" rel="noopener" class="_"} to create such resources, or if you want to manage these yourself, you can use the following custom Compose extensions: -- Use `x-aws-cluster` as a top-level element in your Compose file to set the ARN +- Use `x-aws-cluster` as a top-level element in your Compose file to set the ID of an ECS cluster when deploying a Compose application. Otherwise, a cluster will be created for the Compose project. -- Use `x-aws-vpc` as a top-level element in your Compose file to set the ID +- Use `x-aws-vpc` as a top-level element in your Compose file to set the ARN of a VPC when deploying a Compose application. - Use `x-aws-loadbalancer` as a top-level element in your Compose file to set @@ -442,14 +444,14 @@ use an existing domain name for your application: 1. Use the AWS web console or CLI to get your VPC and Subnets IDs. You can retrieve the default VPC ID and attached subnets using this AWS CLI commands: ```console -$ aws ec2 describe-vpcs --filters Name=isDefault,Values=true --query 'Vpcs[0].VpcId' +$ aws ec2 describe-vpcs --filters Name=isDefault,Values=true --query 'Vpcs[0].VpcId' "vpc-123456" $ aws ec2 describe-subnets --filters Name=vpc-id,Values=vpc-123456 --query 'Subnets[*].SubnetId' [ - "subnet-1234abcd", - "subnet-6789ef00", + "subnet-1234abcd", + "subnet-6789ef00", ] ``` 1. Use the AWS CLI to create your load balancer. The AWS Web Console can also be used but will require adding at least one listener, which we don't need here. @@ -460,11 +462,11 @@ $ aws elbv2 create-load-balancer --name myloadbalancer --type application --subn { "LoadBalancers": [ { - "IpAddressType": "ipv4", - "VpcId": "vpc-123456", - "LoadBalancerArn": "arn:aws:elasticloadbalancing:us-east-1:1234567890:loadbalancer/app/myloadbalancer/123abcd456", - "DNSName": "myloadbalancer-123456.us-east-1.elb.amazonaws.com", -... + "IpAddressType": "ipv4", + "VpcId": "vpc-123456", + "LoadBalancerArn": "arn:aws:elasticloadbalancing:us-east-1:1234567890:loadbalancer/app/myloadbalancer/123abcd456", + "DNSName": "myloadbalancer-123456.us-east-1.elb.amazonaws.com", +... ``` 1. To assign your application an existing domain name, you can configure your DNS with a CNAME entry pointing to just-created loadbalancer's `DNSName` reported as you created the loadbalancer.