Creating Amazon ECS resources using the Amazon CDK - Amazon Elastic Container Service
Step 1: Set up your Amazon CDK projectStep 2: Use the Amazon CDK to define a containerized web server on FargateStep 3: Test the web serverStep 4: Clean upNext steps
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).

Creating Amazon ECS resources 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 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
Note

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.

TypeScript
mkdir hello-ecs
cd hello-ecs
cdk init --language typescript
JavaScript
mkdir hello-ecs
cd hello-ecs
cdk init --language javascript
Python
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
Java
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.

C#
mkdir hello-ecs
cd hello-ecs
cdk init --language csharp
Go
mkdir hello-ecs
cd hello-ecs
cdk init --language go
Note

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

TypeScript
aws-cdk-lib/aws-ecs
aws-cdk-lib/aws-ecs-patterns
JavaScript
aws-cdk-lib/aws-ecs
aws-cdk-lib/aws-ecs-patterns
Python
aws_cdk.aws_ecs
aws_cdk.aws_ecs_patterns
Java
software.amazon.awscdk.services.ecs
software.amazon.awscdk.services.ecs.patterns
C#
Amazon.CDK.AWS.ECS
Amazon.CDK.AWS.ECS.Patterns
Go
github.com/aws/aws-cdk-go/awscdk/v2/awsecs
github.com/aws/aws-cdk-go/awscdk/v2/awsecspatterns

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.

Note

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.

TypeScript

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
    });
  }
}
JavaScript

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 }
Python

Update hello-ecs/hello_ecs_stack.py 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
        )
Java

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

package com.myorg;

import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;

import software.amazon.awscdk.services.ecs.ContainerImage;
import software.amazon.awscdk.services.ecs.patterns.ApplicationLoadBalancedFargateService;
import software.amazon.awscdk.services.ecs.patterns.ApplicationLoadBalancedTaskImageOptions;

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();        
    }
}
C#

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
                });
        }
    }
}
Go

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

package main

import (
	"github.com/aws/aws-cdk-go/awscdk/v2"
	// "github.com/aws/aws-cdk-go/awscdk/v2/awssqs"
	"github.com/aws/aws-cdk-go/awscdk/v2/awsecs"
	"github.com/aws/aws-cdk-go/awscdk/v2/awsecspatterns"
	"github.com/aws/constructs-go/constructs/v10"
	"github.com/aws/jsii-runtime-go"
)

type HelloEcsStackProps struct {
	awscdk.StackProps
}

func NewHelloEcsStack(scope constructs.Construct, id string, props *HelloEcsStackProps) awscdk.Stack {
	var sprops awscdk.StackProps
	if props != nil {
		sprops = props.StackProps
	}
	stack := awscdk.NewStack(scope, &id, &sprops)

	// The code that defines your stack goes here

	// example resource
	// queue := awssqs.NewQueue(stack, jsii.String("HelloEcsQueue"), &awssqs.QueueProps{
	// 	VisibilityTimeout: awscdk.Duration_Seconds(jsii.Number(300)),
	// })
	res := awsecspatterns.NewApplicationLoadBalancedFargateService(stack, jsii.String("MyWebServer"),
		&awsecspatterns.ApplicationLoadBalancedFargateServiceProps{
			TaskImageOptions: &awsecspatterns.ApplicationLoadBalancedTaskImageOptions{
				Image: awsecs.ContainerImage_FromRegistry(jsii.String("amazon/amazon-ecs-sample"), &awsecs.RepositoryImageProps{}),
			},
		},
	)
	awscdk.NewCfnOutput(stack, jsii.String("LoadBalancerDNS"), &awscdk.CfnOutputProps{Value: res.LoadBalancer().LoadBalancerDnsName()})

	return stack
}

func main() {
	defer jsii.Close()

	app := awscdk.NewApp(nil)

	NewHelloEcsStack(app, "HelloEcsStack", &HelloEcsStackProps{
		awscdk.StackProps{
			Env: env(),
		},
	})

	app.Synth(nil)
}

// env determines the AWS environment (account+region) in which our stack is to
// be deployed. For more information see: https://docs.aws.amazon.com/cdk/latest/guide/environments.html
func env() *awscdk.Environment {
	// If unspecified, this stack will be "environment-agnostic".
	// Account/Region-dependent features and context lookups will not work, but a
	// single synthesized template can be deployed anywhere.
	//---------------------------------------------------------------------------
	return nil

	// Uncomment if you know exactly what account and region you want to deploy
	// the stack to. This is the recommendation for production stacks.
	//---------------------------------------------------------------------------
	// return &awscdk.Environment{
	//  Account: jsii.String("123456789012"),
	//  Region:  jsii.String("us-east-1"),
	// }

	// Uncomment to specialize this stack for the AWS Account and Region that are
	// implied by the current CLI configuration. This is recommended for dev
	// stacks.
	//---------------------------------------------------------------------------
	// return &awscdk.Environment{
	//  Account: jsii.String(os.Getenv("CDK_DEFAULT_ACCOUNT")),
	//  Region:  jsii.String(os.Getenv("CDK_DEFAULT_REGION")),
	// }
}

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: 0.0.0.0/0
          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 = Hello-MyWeb-ZZZZZZZZZZZZZ-ZZZZZZZZZZ.us-west-2.elb.amazonaws.com
HelloEcsStack.MyWebServerServiceURLYYYYYYYY = http://Hello-MyWeb-ZZZZZZZZZZZZZ-ZZZZZZZZZZ.us-west-2.elb.amazonaws.com

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:

TypeScript

Working with the Amazon CDK in TypeScript

JavaScript

Working with the Amazon CDK in JavaScript

Python

Working with the Amazon CDK in Python

Java

Working with the Amazon CDK in Java

C#

Working with the Amazon CDK in C#

Go

Working with the Amazon CDK in Go

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