From ea9be2076e301a05e8b41fa8ba6cebce8e0b3113 Mon Sep 17 00:00:00 2001 From: Lucas Costi Date: Thu, 17 Dec 2020 16:08:26 +1000 Subject: [PATCH] Added edits and style changes to Amazon guide --- ...ing-to-amazon-elastic-container-service.md | 182 +++++++++--------- 1 file changed, 94 insertions(+), 88 deletions(-) diff --git a/content/actions/guides/deploying-to-amazon-elastic-container-service.md b/content/actions/guides/deploying-to-amazon-elastic-container-service.md index 8c647058e8..d6cc9c814d 100644 --- a/content/actions/guides/deploying-to-amazon-elastic-container-service.md +++ b/content/actions/guides/deploying-to-amazon-elastic-container-service.md @@ -11,56 +11,63 @@ versions: {% data reusables.actions.enterprise-github-hosted-runners %} ### Introduction -[Amazon ECR (Elastic Container Registry)](https://aws.amazon.com/ecr/) and [Amazon ECS (Elastic Container Service)](https://aws.amazon.com/ecs/) are a great combination for running your container-based workloads in the cloud. -This guide will show you how to orchestrate your deployments to Amazon ECR and ECS via GitHub Actions. +This guide explains how to use {% data variables.product.prodname_actions %} to build a containerized application, push it to [Amazon Elastic Container Registry (ECR)](https://aws.amazon.com/ecr/), and deploy it to [Amazon Elastic Container Service (ECS)](https://aws.amazon.com/ecs/). -The included workflow will build and push a new container image to Amazon ECR, and then will deploy a new task definition to Amazon ECS, on every push to the default branch. +On every new release in your {% data variables.product.company_short %} repository, the {% data variables.product.prodname_actions %} workflow builds and pushes a new container image to Amazon ECR, and then deploys a new task definition to Amazon ECS. ### Prerequisites -To adopt this workflow, you will first need to complete the following setup steps: -#### Create an ECR repository to store your images -For example, using [the AWS CLI](https://aws.amazon.com/cli/): +Before creating your {% data variables.product.prodname_actions %} workflow, you will first need to complete the following setup steps for Amazon ECR and ECS: + +1. Create an Amazon ECR repository to store your images. + + For example, using [the AWS CLI](https://aws.amazon.com/cli/): + + {% raw %}```bash{:copy} + aws ecr create-repository \ + --repository-name $ECR_REPOSITORY \ + --region $AWS_REGION + ```{% endraw %} + + Ensure that you use the same Amazon ECR repository name for the `ECR_REPOSITORY` variable in the workflow below. + + Ensure that you use the same AWS region value for the `AWS_REGION` variable in the workflow below. + +2. Create an Amazon ECS task definition, cluster, and service. + + For details, follow the [Getting started wizard on the Amazon ECS console](https://us-east-2.console.aws.amazon.com/ecs/home?region=us-east-2#/firstRun), or the [Getting started guide](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/getting-started-fargate.html) in the Amazon ECS documentation. + + Ensure that you note the names you set for the Amazon ECS service and cluster, and use them for the `ECS_SERVICE` and `ECS_CLUSTER` variables in the workflow below. + +3. Store your Amazon ECS task definition as a JSON file in your {% data variables.product.company_short %} repository. + + The format of the file should be the same as the output generated by: + + {% raw %}```bash{:copy} + aws ecs register-task-definition --generate-cli-skeleton + ```{% endraw %} + + Ensure that you set the `ECS_TASK_DEFINITION` variable in the workflow below as the path to the JSON file. + + Ensure that you set the `CONTAINER_NAME` variable in the workflow below as the container name in the `containerDefinitions` section of the task definition. + +4. Create {% data variables.product.prodname_actions %} secrets named `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to store the values for your Amazon IAM access key. + + For more information on creating secrets for {% data variables.product.prodname_actions %}, see "[Encrypted secrets](t/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository)." + + See the documentation for each action used below for the recommended IAM policies for the IAM user, and methods for handling the access key credentials. + +### Creating the workflow + +Once you've completed the prerequisites, you can proceed with creating the workflow. + +The following example workflow demonstrates how to build a container image and push it to Amazon ECR. It then updates the task definition with the new image ID, and deploys the task definition to Amazon ECS. + +Ensure that you provide your own values for all the variables in the `env:` key of the workflow. {% raw %} -```bash{:copy} -aws ecr create-repository \ - --repository-name $ECR_REPOSITORY \ - --region $AWS_REGION -``` -{% endraw %} - -Replace the value of `$ECR_REPOSITORY` in the workflow below with your repository's name. - -Replace the value of `$AWS_REGION` in the workflow below with your repository's region. - -#### Create an ECS task definition, an ECS cluster, and an ECS service -For details, follow [the Getting Started guide on the ECS console](https://us-east-2.console.aws.amazon.com/ecs/home?region=us-east-2#/firstRun). - -Replace the values for `$ECS_SERVICE` and `$ECS_CLUSTER` in the workflow below with your service and cluster names. - -#### Store your ECS task definition as a JSON file in your repository -The format should mirror the output generated by: - -{% raw %} -```bash{:copy} -aws ecs register-task-definition --generate-cli-skeleton -``` -{% endraw %} - -Replace the value of `$ECS_TASK_DEFINITION` in the workflow below with your JSON file's name. - -Replace the value of `$CONTAINER_NAME` in the workflow below with the name of the container in the containerDefinitions section of the task definition. - -#### Store an IAM user access key in GitHub Actions secrets named `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` -See the documentation for each action used below for the recommended IAM policies for this IAM user, and best practices on handling the access key credentials. - -### Workflow -After updating the env section, follow these instructions to add the workflow to your repository: - -{% raw %} -```bash{:copy} +```yaml{:copy} name: Deploy to Amazon ECS on: @@ -87,58 +94,57 @@ jobs: runs-on: ubuntu-latest steps: - - name: Checkout - uses: actions/checkout@v2 + - name: Checkout + uses: actions/checkout@v2 - - name: Configure AWS credentials - uses: aws-actions/configure-aws-credentials@v1 - with: - aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} - aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} - aws-region: $AWS_REGION + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@v1 + with: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + aws-region: $AWS_REGION - - name: Login to Amazon ECR - id: login-ecr - uses: aws-actions/amazon-ecr-login@v1 + - name: Login to Amazon ECR + id: login-ecr + uses: aws-actions/amazon-ecr-login@v1 - - name: Build, tag, and push image to Amazon ECR - id: build-image - env: - ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }} - IMAGE_TAG: ${{ github.sha }} - run: | - # Build a docker container and - # push it to ECR so that it can - # be deployed to ECS. - docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG . - docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG - echo "image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_ENV + - name: Build, tag, and push image to Amazon ECR + id: build-image + env: + ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }} + IMAGE_TAG: ${{ github.sha }} + run: | + # Build a docker container and + # push it to ECR so that it can + # be deployed to ECS. + docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG . + docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG + echo "image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_ENV - - name: Fill in the new image ID in the Amazon ECS task definition - id: task-def - uses: aws-actions/amazon-ecs-render-task-definition@v1 - with: - task-definition: $ECS_TASK_DEFINITION - container-name: $CONTAINER_NAME - image: ${{ steps.build-image.outputs.image }} + - name: Fill in the new image ID in the Amazon ECS task definition + id: task-def + uses: aws-actions/amazon-ecs-render-task-definition@v1 + with: + task-definition: $ECS_TASK_DEFINITION + container-name: $CONTAINER_NAME + image: ${{ steps.build-image.outputs.image }} - - name: Deploy Amazon ECS task definition - uses: aws-actions/amazon-ecs-deploy-task-definition@v1 - with: - task-definition: ${{ steps.task-def.outputs.task-definition }} - service: $ECS_SERVICE - cluster: $ECS_CLUSTER - wait-for-service-stability: true + - name: Deploy Amazon ECS task definition + uses: aws-actions/amazon-ecs-deploy-task-definition@v1 + with: + task-definition: ${{ steps.task-def.outputs.task-definition }} + service: $ECS_SERVICE + cluster: $ECS_CLUSTER + wait-for-service-stability: true ``` {% endraw %} ### Additional resources -The following additional resources may also be of use: -1. Best practices on handling AWS access key credentials: https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html -1. Amazon ECR: https://aws.amazon.com/ecr/ -1. Amazon ECS: https://aws.amazon.com/ecs/ -1. Official AWS GitHub action to configure AWS credentials: https://github.com/aws-actions/configure-aws-credentials -1. Official AWS GitHub action to login to Amazon ECR: https://github.com/aws-actions/amazon-ecr-login -1. Official AWS GitHub action to “render” and Amazon ECS task definition: https://github.com/aws-actions/amazon-ecs-render-task-definition -1. Official AWS GitHub action to register an Amazon ECS task definition and deploy it to an ECS service: https://github.com/aws-actions/amazon-ecs-deploy-task-definition +For more information on the services used in these examples, see the following documentation: + +* "[Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)" in the Amazon AWS documentation. +* Official AWS "[Configure AWS Credentials](https://github.com/aws-actions/configure-aws-credentials)" action. +* Official AWS [Amazon ECR "Login"](https://github.com/aws-actions/amazon-ecr-login) action. +* Official AWS [Amazon ECS "Render Task Definition"](https://github.com/aws-actions/amazon-ecs-render-task-definition) action. +* Official AWS [Amazon ECS "Deploy Task Definition"](https://github.com/aws-actions/amazon-ecs-deploy-task-definition) action.