Getting started with Amazon ECS using the Amazon CDK - Amazon Elastic Container Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Getting started with Amazon ECS using the Amazon CDK

The Amazon Cloud Development Kit (Amazon CDK) is an Infrastructure-as-Code (IAC) framework that you can use to define Amazon cloud infrastructure by using a programming language of your choosing. To define your own cloud infrastructure, you first write an app (in one of the CDK's supported languages) that contains one or more stacks. Then, you synthesize it to an Amazon CloudFormation template and deploy your resources to your Amazon Web Services account. Follow the steps in this topic to deploy a containerized web server with Amazon Elastic Container Service (Amazon ECS) and the Amazon CDK on Fargate.

The Amazon Construct Library, included with the CDK, provides modules that you can use to model the resources that Amazon Web Services provide. For popular services, the library provides curated constructs with smart defaults and best practices. One of these modules, specifically aws-ecs-patterns, provides high-level abstractions that you can use to define your containerized service and all the necessary supporting resources in a few lines of code.

This topic uses the ApplicationLoadBalancedFargateService construct. This construct deploys an Amazon ECS service on Fargate behind an application load balancer. The aws-ecs-patterns module also includes constructs that use a network load balancer and run on Amazon EC2.

Before starting this task, set up your Amazon CDK development environment, and install the Amazon CDK by running the following command. For instructions on how to set up your Amazon CDK development environment, see Getting Started With the Amazon CDK - Prerequisites.

npm install -g aws-cdk

These instructions assume you are using Amazon CDK v2.

Step 1: Set up your Amazon CDK project

Create a directory for your new Amazon CDK app and initialize the project.

mkdir hello-ecs cd hello-ecs cdk init --language typescript
mkdir hello-ecs cd hello-ecs cdk init --language javascript
mkdir hello-ecs cd hello-ecs cdk init --language python

After the project is started, activate the project's virtual environment and install the Amazon CDK's baseline dependencies.

source .venv/bin/activate python -m pip install -r requirements.txt
mkdir hello-ecs cd hello-ecs cdk init --language java

Import this Maven project to your Java IDE. For example, in Eclipse, use File > Import > Maven > Existing Maven Projects.

mkdir hello-ecs cd hello-ecs cdk init --language csharp

The Amazon CDK application template uses the name of the project directory to generate names for source files and classes. In this example, the directory is named hello-ecs. If you use a different project directory name, your app won't match these instructions.

Amazon CDK v2 includes stable constructs for all Amazon Web Services in a single package that's called aws-cdk-lib. This package is installed as a dependency when you initialize the project. When working with certain programming languages, the package is installed when you build the project for the first time. This topic covers how to use an Amazon ECS Patterns construct, which provides high-level abstractions for working with Amazon ECS. This module relies on Amazon ECS constructs and other constructs to provision the resources that your Amazon ECS application needs.

The names that you use to import these libraries into your CDK application might differ slightly depending on which programming language you use. For reference, the following are the names that are used in each supported CDK programming language.

aws-cdk-lib/aws-ecs aws-cdk-lib/aws-ecs-patterns
aws-cdk-lib/aws-ecs aws-cdk-lib/aws-ecs-patterns
aws_cdk.aws_ecs aws_cdk.aws_ecs_patterns
Amazon.CDK.AWS.ECS Amazon.CDK.AWS.ECS.Patterns

Step 2: Use the Amazon CDK to define a containerized web server on Fargate

Use the container image amazon-ecs-sample from DockerHub. This image contains a PHP web app that runs on Amazon Linux 2.

In the Amazon CDK project that you created, edit the file that contains the stack definition to resemble one of the following examples.


A stack is a unit of deployment. All resources must be in a stack, and all the resources that are in a stack are deployed at the same time. If a resource fails to deploy, any other resources that were already deployed are rolled back. An Amazon CDK app can contain multiple stacks, and resources in one stack can refer to resources in another stack.


Update lib/hello-ecs-stack.ts so that it resembles the following.

import * as cdk from 'aws-cdk-lib'; import { Construct } from 'constructs'; import * as ecs from 'aws-cdk-lib/aws-ecs'; import * as ecsp from 'aws-cdk-lib/aws-ecs-patterns'; export class HelloEcsStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); new ecsp.ApplicationLoadBalancedFargateService(this, 'MyWebServer', { taskImageOptions: { image: ecs.ContainerImage.fromRegistry('amazon/amazon-ecs-sample'), }, publicLoadBalancer: true }); } }

Update lib/hello-ecs-stack.js so that it resembles the following.

const cdk = require('aws-cdk-lib'); const { Construct } = require('constructs'); const ecs = require('aws-cdk-lib/aws-ecs'); const ecsp = require('aws-cdk-lib/aws-ecs-patterns'); class HelloEcsStack extends cdk.Stack { constructor(scope = Construct, id = string, props = cdk.StackProps) { super(scope, id, props); new ecsp.ApplicationLoadBalancedFargateService(this, 'MyWebServer', { taskImageOptions: { image: ecs.ContainerImage.fromRegistry('amazon/amazon-ecs-sample'), }, publicLoadBalancer: true }); } } module.exports = { HelloEcsStack }

Update hello-ecs/ so that it resembles the following.

import aws_cdk as cdk from constructs import Construct import aws_cdk.aws_ecs as ecs import aws_cdk.aws_ecs_patterns as ecsp class HelloEcsStack(cdk.Stack): def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None: super().__init__(scope, construct_id, **kwargs) ecsp.ApplicationLoadBalancedFargateService(self, "MyWebServer", task_image_options=ecsp.ApplicationLoadBalancedTaskImageOptions( image=ecs.ContainerImage.from_registry("amazon/amazon-ecs-sample")), public_load_balancer=True )

Update src/main/java/com.myorg/ so that it resembles the following.

package com.myorg; import software.constructs.Construct; import; import; import; import; import; public class HelloEcsStack extends Stack { public HelloEcsStack(final Construct scope, final String id) { this(scope, id, null); } public HelloEcsStack(final Construct scope, final String id, final StackProps props) { super(scope, id, props); ApplicationLoadBalancedFargateService.Builder.create(this, "MyWebServer") .taskImageOptions(ApplicationLoadBalancedTaskImageOptions.builder() .image(ContainerImage.fromRegistry("amazon/amazon-ecs-sample")) .build()) .publicLoadBalancer(true) .build(); } }

Update src/HelloEcs/HelloEcsStack.cs so that it resembles the following.

using Amazon.CDK; using Constructs; using Amazon.CDK.AWS.ECS; using Amazon.CDK.AWS.ECS.Patterns; namespace HelloEcs { public class HelloEcsStack : Stack { internal HelloEcsStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props) { new ApplicationLoadBalancedFargateService(this, "MyWebServer", new ApplicationLoadBalancedFargateServiceProps { TaskImageOptions = new ApplicationLoadBalancedTaskImageOptions { Image = ContainerImage.FromRegistry("amazon/amazon-ecs-sample") }, PublicLoadBalancer = true }); } } }

The preceding short snippet includes the following:

  • The service's logical name: MyWebServer.

  • The container image that was obtained from DockerHub: amazon/amazon-ecs-sample.

  • Other relevant information, such as the fact that the load balancer has a public address and is accessible from the Internet.

The Amazon CDK will create all the resources that are required to deploy the web server including the following resources. These resources were omitted in this example.

  • Amazon ECS cluster

  • Amazon VPC and Amazon EC2 instances

  • Auto Scaling group

  • Application Load Balancer

  • IAM roles and policies

Some automatically provisioned resources are shared by all Amazon ECS services defined in the stack.

Save the source file, then run the cdk synth command in your application's main directory. The Amazon CDK runs the app and synthesizes an Amazon CloudFormation template from it, and then displays the template. The template is an approximately 600-line YAML file. The beginning of the file is shown here. Your template might differ from this example.

Resources: MyWebServerLB3B5FD3AB: Type: AWS::ElasticLoadBalancingV2::LoadBalancer Properties: LoadBalancerAttributes: - Key: deletion_protection.enabled Value: "false" Scheme: internet-facing SecurityGroups: - Fn::GetAtt: - MyWebServerLBSecurityGroup01B285AA - GroupId Subnets: - Ref: EcsDefaultClusterMnL3mNNYNVpcPublicSubnet1Subnet3C273B99 - Ref: EcsDefaultClusterMnL3mNNYNVpcPublicSubnet2Subnet95FF715A Type: application DependsOn: - EcsDefaultClusterMnL3mNNYNVpcPublicSubnet1DefaultRouteFF4E2178 - EcsDefaultClusterMnL3mNNYNVpcPublicSubnet2DefaultRouteB1375520 Metadata: aws:cdk:path: HelloEcsStack/MyWebServer/LB/Resource MyWebServerLBSecurityGroup01B285AA: Type: AWS::EC2::SecurityGroup Properties: GroupDescription: Automatically created Security Group for ELB HelloEcsStackMyWebServerLB06757F57 SecurityGroupIngress: - CidrIp: Description: Allow from anyone on port 80 FromPort: 80 IpProtocol: tcp ToPort: 80 VpcId: Ref: EcsDefaultClusterMnL3mNNYNVpc7788A521 Metadata: aws:cdk:path: HelloEcsStack/MyWebServer/LB/SecurityGroup/Resource # and so on for another few hundred lines

To deploy the service in your Amazon Web Services account, run the cdk deploy command in your application's main directory. You're asked to approve the IAM policies that the Amazon CDK generated.

The deployment takes several minutes during which the Amazon CDK creates several resources. The last few lines of the output from the deployment include the load balancer's public hostname and your new web server's URL. They are as follows.

Outputs: HelloEcsStack.MyWebServerLoadBalancerDNSXXXXXXX = HelloEcsStack.MyWebServerServiceURLYYYYYYYY =

Step 3: Test the web server

Copy the URL from the deployment output and paste it into your web browser. The following welcome message from the web server is displayed.

                Screenshot of the Amazon ECS sample application. The output indicates
                    that "Your application is now running on Amazon ECS".

Step 4: Clean up

After you're finished with the web server, end the service using the CDK by running the cdk destroy command in your application's main directory. Doing this prevents you from incurring any unintended charges in the future.

Next steps

To learn more about how to develop Amazon infrastructure using the Amazon CDK, see the Amazon CDK Developer Guide.

For information about writing Amazon CDK apps in your language of choice, see the following:


Working with the Amazon CDK in TypeScript


Working with the Amazon CDK in JavaScript


Working with the Amazon CDK in Python


Working with the Amazon CDK in Java


Working with the Amazon CDK in C#

For more information about the Amazon Construct Library modules used in this topic, see the following Amazon CDK API Reference overviews.