jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-30 03:01:36 -05:00
Code Issues Projects Releases Wiki Activity

Added edits and style changes to Amazon guide

Browse Source
This commit is contained in:
Lucas Costi
2020-12-17 16:08:26 +10:00
parent 3ef5057d9f
commit ea9be2076e
1 changed files with 94 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

182
content/actions/guides/deploying-to-amazon-elastic-container-service.md
View File

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