doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md
{{< details >}}
{{< /details >}}
This step-by-step guide helps you deploy a project hosted on GitLab.com to the Amazon Elastic Container Service (ECS).
In this guide, you begin by creating an ECS cluster manually using the AWS console. You create and deploy a simple application that you create from a GitLab template.
These instructions work for both GitLab.com and GitLab Self-Managed instances. Ensure your own runners are configured.
us-east-2 region.
You can use any region, but do not change it after you begin.For deploying an application from GitLab, you must first create an infrastructure and initial deployment on AWS. This includes an ECS cluster and related components, such as ECS task definitions, ECS services, and containerized application image.
For the first step here, you create a demo application from a project template.
Use a GitLab project template to get started. As the name suggests, these projects provide a bare-bones application built on some well-known frameworks.
ecs-demo. Make it public so that you can
take advantage of the features available in the
GitLab Ultimate plan.Now that you created a demo project, you must containerize the application and push it to the container registry.
ECS is a container orchestration service, meaning that you must provide a containerized application image during the infrastructure build. To do so, you can use GitLab Auto Build and Container Registry.
In the top bar, select Search or go to and find your ecs-demo project.
Select Set up CI/CD. It brings you to a .gitlab-ci.yml
creation form.
Copy and paste the following content into the empty .gitlab-ci.yml. This defines
a pipeline for continuous deployment to ECS.
include:
- template: AWS/Deploy-ECS.gitlab-ci.yml
Select Commit Changes. It automatically triggers a new pipeline. In this pipeline, the build
job containerizes the application and pushes the image to GitLab container registry.
Visit Deploy > Container Registry. Make sure the application image has been pushed.
Now you have a containerized application image that can be pulled from AWS. Next, you define the spec of how this application image is used in AWS.
The production_ecs job fails because ECS Cluster is not connected yet. You can fix this
later.
ECS Task definitions is a specification about how the application image is started by an ECS service.
Go to ECS > Task Definitions on AWS console.
Select Create new Task Definition.
Choose EC2 as the launch type. Select Next Step.
Set ecs_demo to Task Definition Name.
Set 512 to Task Size > Task memory and Task CPU.
Select Container Definitions > Add container. This opens a container registration form.
Set web to Container name.
Set registry.gitlab.com/<your-namespace>/ecs-demo/master:latest to Image.
Alternatively, you can copy and paste the image path from the GitLab container registry page.
Add a port mapping. Set 80 to Host Port and 5000 to Container port.
Select Create.
Now you have the initial task definition. Next, you create an actual infrastructure to run the application image.
An ECS cluster is a virtual group of ECS services. It's also associated with EC2 or Fargate as the computation resource.
Go to ECS > Clusters on AWS console.
Select Create Cluster.
Select EC2 Linux + Networking as the cluster template. Select Next Step.
Set ecs-demo to Cluster Name.
Choose the default VPC in Networking. If there are no existing VPCs, you can leave it as-is to create a new one.
Set all available subnets of the VPC to Subnets.
Select Create.
Make sure that the ECS cluster has been successfully created.
Now you can register an ECS service to the ECS cluster in the next step.
Note the following:
ECS service is a daemon to create an application container based on the ECS task definition.
Go to ECS > Clusters > ecs-demo > Services on the AWS console
Select Deploy. This opens a service creation form.
Select EC2 in Launch Type.
Set ecs_demo to Task definition. This corresponds to the task definition you created previously.
Set ecs_demo to Service name.
Set 1 to Desired tasks.
Select Deploy.
Make sure that the created service is active.
The AWS console UI changes from time to time. If you can't find a relevant component in the instructions, select the closest one.
Now, the demo application is accessible from the internet.
Go to EC2 > Instances on the AWS console
Search by ECS Instance to find the corresponding EC2 instance that the ECS cluster created.
Select the ID of the EC2 instance. This brings you to the instance detail page.
Copy Public IPv4 address and paste it in the browser. Now you can see the demo application running.
In this guide, HTTPS/SSL is not configured. You can access to the application through HTTP only
(for example, http://<ec2-ipv4-address>).
Now that you have an application running on ECS, you can set up continuous deployment from GitLab.
For GitLab to access the ECS cluster, service, and task definition that you previously created, you must create a deployer user on AWS:
Go to IAM > Users on AWS console.
Select Add user.
Set ecs_demo to User name.
Enable Programmatic access checkbox. Select Next: Permissions.
Select Attach existing policies directly in Set permissions.
Select AmazonECS_FullAccess from the policy list. Select Next: Tags and Next: Review.
Select Create user.
Take note of the Access key ID and Secret access key of the created user.
[!note] Do not share the secret access key in a public place. You must save it in a secure place.
You can register the access information in GitLab CI/CD Variables. These variables are injected into the pipeline jobs and can access the ECS API.
In the top bar, select Search or go to and find your ecs-demo project.
Go to Settings > CI/CD > Variables.
Select Add Variable and set the following key-value pairs.
| Key | Value | Note |
|---|---|---|
AWS_ACCESS_KEY_ID | <Access key ID of the deployer> | For authenticating aws CLI. |
AWS_SECRET_ACCESS_KEY | <Secret access key of the deployer> | For authenticating aws CLI. |
AWS_DEFAULT_REGION | us-east-2 | For authenticating aws CLI. |
CI_AWS_ECS_CLUSTER | ecs-demo | The ECS cluster is accessed by production_ecs job. |
CI_AWS_ECS_SERVICE | ecs_demo | The ECS service of the cluster is updated by production_ecs job. Ensure that this variable is scoped to the appropriate environment (production, staging, review/*). |
CI_AWS_ECS_TASK_DEFINITION | ecs_demo | The ECS task definition is updated by production_ecs job. |
Change a file in the project and see if it's reflected in the demo application on ECS:
In the top bar, select Search or go to and find your ecs-demo project.
Open the app/views/welcome/index.html.erb file.
Select Edit.
Change the text to You're on ECS!.
Select Commit Changes. This automatically triggers a new pipeline. Wait until it finishes.
Access the running application on the ECS cluster. You should see this:
Congratulations! You successfully set up continuous deployment to ECS.
[!note] ECS deploy jobs wait for the rollout to complete before exiting. To disable this behavior, set
CI_AWS_ECS_WAIT_FOR_ROLLOUT_COMPLETE_DISABLEDto a non-empty value.
To use review apps with ECS:
CI_AWS_ECS_SERVICE variable to set the name.review/*.Only one Review App at a time can be deployed because this service is shared by all review apps.
To use SAST with ECS, add the following to your .gitlab-ci.yml file:
include:
- template: Jobs/SAST.gitlab-ci.yml
For more details and configuration options, see the SAST documentation.
To use DAST on non-default branches, set up review apps
and add the following to your .gitlab-ci.yml file:
include:
- template: Security/DAST.gitlab-ci.yml
To use DAST on the default branch:
CI_AWS_ECS_SERVICE variable to set the name.dast-default environment..gitlab-ci.yml file:include:
- template: Security/DAST.gitlab-ci.yml
- template: Jobs/DAST-Default-Branch-Deploy.gitlab-ci.yml
For more details and configuration options, see the DAST documentation.