Deploy a clustered application to Amazon ECS by using AWS Copilot

Created by Jean-Baptiste Guillois (AWS), Mathew George (AWS), and Thomas Scott (AWS)

Summary

This pattern shows how to deploy containers in an Amazon Elastic Container Service (Amazon ECS) cluster in two ways—by using the Amazon Web Services (AWS) Management Console, and by using AWS Copilot—to demonstrate how AWS Copilot simplifies deployment tasks.

Amazon ECS is a highly scalable, fast container management service that makes it easy to run, stop, and manage containers on a cluster. Your containers are defined in a task definition that you use to run individual tasks or tasks within a service. You can run your tasks and services on a serverless infrastructure that is managed by AWS Fargate. Alternatively, for more control over your infrastructure, you can run your tasks and services on a cluster of Amazon Elastic Compute Cloud (Amazon EC2) instances that you manage.

The AWS Copilot command line interface (CLI) commands simplify building, releasing, and operating production-ready containerized applications on Amazon ECS from a local development environment. The AWS Copilot CLI aligns with developer workflows that support modern application best practices: from using infrastructure as code to creating a continuous integration and continuous delivery (CI/CD) pipeline provisioned on behalf of a user. You can use the AWS Copilot CLI as part of your everyday development and testing cycle as an alternative to the AWS Management Console.

Prerequisites and limitations

Prerequisites 

• An active AWS account

• AWS Command Line Interface (AWS CLI) locally installed and configured to use your AWS account (see the installation instructions and the configuration instructions in the AWS CLI documentation)

• AWS Copilot locally installed (see the installation instructions in the Amazon ECS documentation)

• Docker installed on your local machine (see the Docker documentation)

Limitations

• Docker enforces pull limits of 100 container images per 6 hours per IP address on the free plan.

Architecture

Target technology stack  

• AWS environment set up with a virtual private cloud (VPC), public and private subnets, and security groups

• Amazon ECS cluster

• Amazon ECS service and task definition

• Amazon Elastic Container Registry (Amazon ECR)

• Amazon DynamoDB

• Application Load Balancer

• AWS Fargate

• Amazon Identity and Access Management (IAM)

• Amazon CloudWatch

• AWS CloudTrail

Target architecture 

When you deploy the sample application for this pattern, multiple tasks are created and deployed in separate Availability Zones. Each task stores data in Amazon DynamoDB. When you access the webpage for a task, you can view the data from all other tasks.

Tools

AWS services

• Amazon ECR – Amazon Elastic Container Registry (Amazon ECR) is an AWS managed container image registry service that is secure, scalable, and reliable. Amazon ECR supports private repositories with resource-based permissions using IAM.

• Amazon ECS – Amazon Elastic Container Service (Amazon ECS) is a highly scalable, fast container management service for running, stopping, and managing containers on a cluster. You can run your tasks and services on a serverless infrastructure that is managed by AWS Fargate. Alternatively, for more control over your infrastructure, you can run your tasks and services on a cluster of Amazon Elastic Compute Cloud (Amazon EC2) instances that you manage.

• AWS Copilot  – AWS Copilot provides a command line interface that helps you launch and manage containerized applications on AWS, including pushing to a registry, creating a task definition, and creating a cluster.

• AWS Fargate  – AWS Fargate is a serverless, pay-as-you-go compute engine that lets you focus on building applications without managing servers. AWS Fargate is compatible with both Amazon ECS and Amazon Elastic Kubernetes Service (Amazon EKS). When you run your Amazon ECS tasks and services with the Fargate launch type or a Fargate capacity provider, you package your application in containers, specify the CPU and memory requirements, define networking and IAM policies, and launch the application. Each Fargate task has its own isolation boundary and doesn’t share the underlying kernel, CPU resources, memory resources, or elastic network interface with another task.

• Amazon DynamoDB – Amazon DynamoDB is a fully managed NoSQL database service that provides fast and predictable performance with seamless scalability.

• Elastic Load Balancing (ELB) – Elastic Load Balancing automatically distributes your incoming traffic across multiple targets, such as EC2 instances, containers, and IP addresses, in one or more Availability Zones. It monitors the health of its registered targets, and routes traffic only to the healthy targets. Elastic Load Balancing scales your load balancer as your incoming traffic changes over time. It can automatically scale to the vast majority of workloads.

Tools

• Docker Command Line Interface

• AWS Command Line Interface (AWS CLI)

• AWS Copilot command line interface

Code 

The code for the sample application used in this pattern is available on GitHub, in the Cluster Sample Application repository. Follow the instructions in the next section to use the sample files.

Epics

Deploy the application stack - option 1 (AWS Management Console)

Task	Description	Skills required
Clone the GitHub repository.	Clone the sample code repository by using the command: git clone https://github.com/aws-samples/cluster-sample-app cluster-sample-app && cd cluster-sample-app	App developer, AWS DevOps
Create your Amazon ECR repository.	Sign in to the AWS Management Console and open the Amazon ECR console at https://console.aws.amazon.com/ecr/repositories. Choose Create repository. For the repository name, enter cluster-sample-app. For all other settings, keep the default values. Choose Create repository. For more information, see Creating a private repository in the Amazon ECR documentation.	App developer, AWS DevOps
Build, tag, and push your Docker image to your Amazon ECR repository.	Select the repository you just created and choose View push commands. Copy the commands that are displayed and run them locally to build, tag, and push your docker image. These commands will be similar to the following. To authenticate your Docker client to the registry: aws ecr get-login-password --region <YOUR_AWS_REGION> | docker login --username AWS --password-stdin <YOUR_AWS_ACCOUNT>.dkr.ecr.<YOUR_AWS_REGION>.amazonaws.com To build your Docker image: docker build -t cluster-sample-app . To tag your Docker image: docker tag cluster-sample-app:latest <YOUR_AWS_ACCOUNT>.dkr.ecr.<YOUR_AWS_REGION>.amazonaws.com/cluster-sample-app:latest To push the Docker image to your repository: docker push <YOUR_AWS_ACCOUNT>.dkr.ecr.<YOUR_AWS_REGION>.amazonaws.com/cluster-sample-app:latest	App developer, AWS DevOps
Deploy the application stack.	Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation/. Choose Create stack. In the Prepare template section, choose Template is ready. In the Specify template section, choose Upload a template file. Choose the local file cluster-sample-app-stack.yml that you cloned from the GitHub repository as the CloudFormation template, and then choose Next. Enter a name for your stack, and then choose Next. Keep all default options, and then choose Next. Review all options, acknowledge the creation of IAM resources, and then choose Create stack. When your application stack has been deployed, choose the Output tab, copy the URL, and open it in your browser to access the application. For more information about deploying CloudFormation templates, see Creating a stack in the AWS CloudFormation documentation.	AWS DevOps, App developer

Deploy the application stack – option 2 (AWS Copilot CLI)

Task	Description	Skills required
Clone the GitHub repository.	Clone the sample code repository by using the command: git clone https://github.com/aws-samples/cluster-sample-app cluster-sample-app && cd cluster-sample-app	App developer, AWS DevOps
Deploy your container image to AWS by using the AWS Copilot CLI.	Deploy the application in one step by using the following command in the root directory of your project: copilot init --app cluster-sample-app --name demo --type "Load Balanced Web Service" --dockerfile ./Dockerfile --port 8080 --deploy You should then be able to access the application by using the DNS name provided as output.	App developer, AWS DevOps

Delete the created resources

Task	Description	Skills required
Delete the resources created through the AWS Management Console.	If you used option 1 (the AWS Management Console) to deploy the application stack, follow these steps when you’re ready to delete the resources you created: Open the CloudFormation console at https://console.aws.amazon.com/cloudformation/. Select the stack you created, and then choose Delete. Open the Amazon ECR console at https://console.aws.amazon.com/ecr/repositories. Select the repository you created, and then choose Delete.	App developer, AWS DevOps
Delete the resources created by AWS Copilot.	If you used option 2 (the AWS Copilot CLI) to deploy the application stack, run the following command from the root directory of your project when you’re ready to delete the resources you created: copilot app delete	App developer, AWS DevOps

Related resources

• Installing or updating the latest version of the AWS CLI (AWS CLI documentation)

• Using the AWS Copilot command line interface (Amazon ECS documentation)

• Amazon ECS on AWS Fargate (Amazon ECR documentation)

• Amazon ECS documentation

• Amazon ECR documentation

• Amazon CloudFormation documentation

• Docker Desktop (Docker documentation)