Skip to content

Commit 8837b7d

Browse files
swintonswinton
committed
Add Amazon ECS guide
1 parent 5a43098 commit 8837b7d

1 file changed

Lines changed: 144 additions & 0 deletions

File tree

‎content/actions/guides/deploying-to-amazon-elastic-container-service.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
title: Deploying to Amazon Elastic Container Service
3+
intro: You can deploy to Amazon Elastic Container Service (ECS) as part of your continuous deployment (CD) workflows.
4+
product: '{% data reusables.gated-features.actions %}'
5+
versions:
6+
free-pro-team: '*'
7+
enterprise-server: '>=2.22'
8+
---
9+
10+
{% data reusables.actions.enterprise-beta %}
11+
{% data reusables.actions.enterprise-github-hosted-runners %}
12+
13+
### Introduction
14+
[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.
15+
16+
This guide will show you how to orchestrate your deployments to Amazon ECR and ECS via GitHub Actions.
17+
18+
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.
19+
20+
### Prerequisites
21+
To adopt this workflow, you will first need to complete the following setup steps:
22+
23+
#### Create an ECR repository to store your images
24+
For example, using [the AWS CLI](https://aws.amazon.com/cli/):
25+
26+
{% raw %}
27+
```bash{:copy}
28+
aws ecr create-repository \
29+
--repository-name $ECR_REPOSITORY \
30+
--region $AWS_REGION
31+
```
32+
{% endraw %}
33+
34+
Replace the value of `$ECR_REPOSITORY` in the workflow below with your repository's name.
35+
36+
Replace the value of `$AWS_REGION` in the workflow below with your repository's region.
37+
38+
#### Create an ECS task definition, an ECS cluster, and an ECS service
39+
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).
40+
41+
Replace the values for `$ECS_SERVICE` and `$ECS_CLUSTER` in the workflow below with your service and cluster names.
42+
43+
#### Store your ECS task definition as a JSON file in your repository
44+
The format should mirror the output generated by:
45+
46+
{% raw %}
47+
```bash{:copy}
48+
aws ecs register-task-definition --generate-cli-skeleton
49+
```
50+
{% endraw %}
51+
52+
Replace the value of `$ECS_TASK_DEFINITION` in the workflow below with your JSON file's name.
53+
54+
Replace the value of `$CONTAINER_NAME` in the workflow below with the name of the container in the containerDefinitions section of the task definition.
55+
56+
#### Store an IAM user access key in GitHub Actions secrets named `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`
57+
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.
58+
59+
### Workflow
60+
After updating the env section, follow these instructions to add the workflow to your repository:
61+
62+
{% raw %}
63+
```bash{:copy}
64+
name: Deploy to Amazon ECS
65+
66+
on:
67+
release:
68+
types: [ created ]
69+
70+
env:
71+
AWS_REGION: your-preferred-aws-region # set this to your preferred AWS region, e.g. us-west-1
72+
ECR_REPOSITORY: your-ecr-repository # set this to your Amazon ECR repository name
73+
ECS_SERVICE: your-ecs-service # set this to your Amazon ECS service name
74+
ECS_CLUSTER: your-ecs-cluster # set this to your Amazon ECS cluster name
75+
ECS_TASK_DEFINITION: your-ecs-task-defintion # set this to the path to your Amazon ECS task definition
76+
# file, e.g. .aws/task-definition.json
77+
CONTAINER_NAME: your-container-name # set this to the name of the container in the
78+
# containerDefinitions section of your task definition
79+
80+
defaults:
81+
run:
82+
shell: bash
83+
84+
jobs:
85+
deploy:
86+
name: Deploy
87+
runs-on: ubuntu-latest
88+
89+
steps:
90+
- name: Checkout
91+
uses: actions/checkout@v2
92+
93+
- name: Configure AWS credentials
94+
uses: aws-actions/configure-aws-credentials@v1
95+
with:
96+
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
97+
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
98+
aws-region: $AWS_REGION
99+
100+
- name: Login to Amazon ECR
101+
id: login-ecr
102+
uses: aws-actions/amazon-ecr-login@v1
103+
104+
- name: Build, tag, and push image to Amazon ECR
105+
id: build-image
106+
env:
107+
ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
108+
IMAGE_TAG: ${{ github.sha }}
109+
run: |
110+
# Build a docker container and
111+
# push it to ECR so that it can
112+
# be deployed to ECS.
113+
docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
114+
docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
115+
echo "image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_ENV
116+
117+
- name: Fill in the new image ID in the Amazon ECS task definition
118+
id: task-def
119+
uses: aws-actions/amazon-ecs-render-task-definition@v1
120+
with:
121+
task-definition: $ECS_TASK_DEFINITION
122+
container-name: $CONTAINER_NAME
123+
image: ${{ steps.build-image.outputs.image }}
124+
125+
- name: Deploy Amazon ECS task definition
126+
uses: aws-actions/amazon-ecs-deploy-task-definition@v1
127+
with:
128+
task-definition: ${{ steps.task-def.outputs.task-definition }}
129+
service: $ECS_SERVICE
130+
cluster: $ECS_CLUSTER
131+
wait-for-service-stability: true
132+
```
133+
{% endraw %}
134+
135+
### Additional resources
136+
The following additional resources may also be of use:
137+
138+
1. Best practices on handling AWS access key credentials: https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html
139+
1. Amazon ECR: https://aws.amazon.com/ecr/
140+
1. Amazon ECS: https://aws.amazon.com/ecs/
141+
1. Official AWS GitHub action to configure AWS credentials: https://github.com/aws-actions/configure-aws-credentials
142+
1. Official AWS GitHub action to login to Amazon ECR: https://github.com/aws-actions/amazon-ecr-login
143+
1. Official AWS GitHub action to “render” and Amazon ECS task definition: https://github.com/aws-actions/amazon-ecs-render-task-definition
144+
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

0 commit comments

Comments
 (0)