Basic container app with custom image build

Nathan Peck profile picture
Nathan Peck
Senior Developer Advocate at AWS


This pattern shows how to setup an AWS Cloud Development Kit (CDK) application for building and deploying a container image. The container image will be deployed to serverless AWS Fargate capacity, managed by Amazon Elastic Container Service (ECS).

This pattern uses aws-cdk-lib/aws-ecs-patterns, which is a higher level CDK library with easy to use SDK's that launch a set of production ready resources for you with a single SDK call.

Development Environment

To use this pattern you need TypeScript and Node. First, ensure that you have Node.js installed on your development machine. Then create the following files:

  • package.json
  • tsconfig.json
  • cdk.json
File: package.jsonLanguage: json
  "name": "fargate-application-load-balanced-service",
  "version": "1.0.0",
  "description": "Running an application load balanced service on Fargate",
  "private": true,
  "scripts": {
    "build": "tsc",
    "watch": "tsc -w",
    "cdk": "cdk"
  "license": "Apache-2.0",
  "devDependencies": {
    "@types/node": "^8.10.38",
    "aws-cdk": "*",
    "typescript": "~4.6.0"
  "dependencies": {
    "aws-cdk-lib": "^2.0.0",
    "constructs": "^10.0.0"

The files above serve the following purpose:

  • package.json - This file is used by NPM or Yarn to identify and install all the required dependencies:
  • tsconfig.json - Configures the TypeScript settings for the project:
  • cdk.json - Tells CDK what command to run, and provides a place to pass other contextual settings to CDK.

CDK Application

Now you can create an index.ts file that has the actual code for the CDK application:

File: index.tsLanguage: ts
import ec2 = require('aws-cdk-lib/aws-ec2');
import ecs = require('aws-cdk-lib/aws-ecs');
import ecs_patterns = require('aws-cdk-lib/aws-ecs-patterns');
import cdk = require('aws-cdk-lib');
import path = require('path');

const app = new cdk.App();
const stack = new cdk.Stack(app, 'FargateServiceWithLocalImage');

// Create VPC and Fargate Cluster
// NOTE: Limit AZs to avoid reaching resource quotas
const vpc = new ec2.Vpc(stack, 'MyVpc', { maxAzs: 2 });
const cluster = new ecs.Cluster(stack, 'Cluster', { vpc });

// Instantiate Fargate Service with a cluster and a local image that gets
// uploaded to an S3 staging bucket prior to being uploaded to ECR.
// A new repository is created in ECR and the Fargate service is created
// with the image from ECR.
new ecs_patterns.ApplicationLoadBalancedFargateService(stack, "FargateService", {
  taskImageOptions: {
    image: ecs.ContainerImage.fromAsset(path.resolve(__dirname, 'local-image'))


There are three core resource types you will see in this CDK application:

  • ec2.Vpc - A private network to host your application resources
  • ecs.Cluster - The ECS cluster is a namespace for holding all the instances of your application. The cluster comes with an AWS Fargate capacity provider that will be used to launch the application containers.
  • ecs_patterns.ApplicationLoadBalancedFargateService - This is a high level CDK pattern which automatically creates an Application Load Balancer ingress, and launches the referenced image inside of the cluster, on AWS Fargate capacity.

You will also notice the ecs.ContainerImage.fromAsset() command. This code finds the local Dockerfile inside of the referenced folder, builds it into a container image, and then uploads that container image.


Use the following commands to interact with the sample CDK application:

  • npm run-script cdk diff - Show a preview of resources to be deployed
  • npm run-script cdk deploy - Deploy the resources onto your AWS account
  • npm run-script cdk destroy - Tear down the deployed stack

Next steps