Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

Coordinate resource dependency and task execution by using the AWS Fargate WaitCondition hook construct - AWS Prescriptive Guidance

Coordinate resource dependency and task execution by using the AWS Fargate WaitCondition hook construct

Created by Stan Fan (AWS)

Summary

This pattern describes the WaitCondition hook (waitcondition-hook-for-aws-fargate-task) npm package, which is a cloud-native solution designed for orchestrating AWS Fargate tasks in Amazon Elastic Container Service (Amazon ECS) clusters.

The WaitCondition hook is an AWS Cloud Development Kit (AWS CDK) construct that’s specifically tailored for integration with AWS CloudFormation. The WaitCondition hook provides the following key capabilities:

  • Acts as a wait condition mechanism, pausing CloudFormation stack execution until a specified Fargate task completes, which helps with orderly deployments and resource provisioning.

  • Supports TypeScript and Python, making it ideal for AWS CDK projects.

  • Allows developers and architects to orchestrate deployments by coordinating task completion and resource management for containerized applications on AWS.

  • Enables running Fargate tasks with one or multiple containers embedded in a CloudFormation lifecycle. and can handle task failures and roll back the CloudFormation stack after a task failure.

  • Provides flexibility to add dependencies between resources and the Fargate task execution results, enabling custom tasks or invoking other endpoints. For instance, you can pause a CloudFormation stack and wait for a database migration (done by a Fargate task) and provision other resources that might depend on the success of the database migration.

Prerequisites and limitations

Prerequisites

  • An active AWS account.

  • AWS Cloud Development Kit (AWS CDK) Command Line Interface (CLI) installed on a local workstation. For more information, see AWS CDK CLI reference in the AWS CDK documentation.

  • Node package manager (npm), installed on a local workstation and configured for the AWS CDK in TypeScript. For more information, see Downloading and installing Node.js and npm in the npm documentation.

  • Yarn installed on a local workstation. For more information, see Installation in the Yarn documentation.

Limitations

  • This solution is deployed to a single AWS account.

  • The expected return code of the container is 0 for success. Any other return code indicates failure, and the CloudFormation stack will roll back.

  • Some AWS services aren’t available in all AWS Regions. For Region availability, see AWS services by Region. For specific endpoints, see Service endpoints and quotas, and choose the link for the service.

Architecture

The following diagram shows the construct architecture.

AWS Step Functions workflow of waitcondition-hook-for-aws-fargate-task construct.

The diagram shows the workflow of waitcondition-hook-for-aws-fargate-task:

  1. WaitCondition and WaitConditionHandler are provisioned to listen to the response from the AWS Lambda functions.

  2. Depending on the result of the task, either the CallbackFunction or the ErrorHandlerFunction is triggered by the finish of the Fargate task.

  3. The Lambda function sends a SUCCEED or FAILURE signal to WaitConditionHandler.

  4. WaitConditionHandler continues to provision the resources if the execution result of the Fargate task succeeds, or rolls back the stack if the task failed.

The following diagram shows an example of a workflow to perform a database migration.

Workflow of Amazon RDS database migration using WaitCondition hook construct.

The example workflow uses the waitcondition-hook-for-aws-fargate-task construct to perform a database migration, as follows:

  1. An Amazon Relational Database Service (Amazon RDS) instance is provisioned.

  2. The waitcondition-hook-for-aws-fargate-task construct runs the database migration task and pauses the stack as an Amazon Elastic Compute Cloud (Amazon EC2) instance.

  3. If the migration task finishes successfully, it sends a Succeed signal to CloudFormation. Otherwise, it sends a Fail signal to CloudFormation and rolls back the stack.

Tools

AWS services

  • AWS Cloud Development Kit (AWS CDK) is a software development framework that helps you define cloud infrastructure in code and provision it through AWS CloudFormation.

  • AWS CloudFormation helps you set up AWS resources, provision them quickly and consistently, and manage them throughout their lifecycle across AWS accounts and AWS Regions.

  • Amazon CloudWatch helps you monitor the metrics of your AWS resources and the applications you run on AWS in real time.

  • Amazon Elastic Container Service (Amazon ECS) is a fast and scalable container management service that helps you run, stop, and manage containers on a cluster.

  • AWS Fargate helps you run containers without needing to manage servers or Amazon EC2 instances. It’s used in conjunction with Amazon ECS.

  • AWS Identity and Access Management (IAM) helps you securely manage access to your AWS resources by controlling who is authenticated and authorized to use them.

  • AWS Lambda is a compute service that helps you run code without needing to provision or manage servers. It runs your code only when needed and scales automatically, so you pay only for the compute time that you use.

  • AWS Step Functions is a serverless orchestration service that helps you combine AWS Lambda functions and other AWS services to build business-critical applications.

  • Amazon Virtual Private Cloud (Amazon VPC) helps you launch AWS resources into a virtual network that you’ve defined. This virtual network resembles a traditional network that you would operate in your own data center, with the benefits of using the scalable infrastructure of AWS.

Other tools

  • npm is a software registry that runs in a Node.js environment and is used to share or borrow packages and manage deployment of private packages.

  • Yarn is an open source package manager that you can use to manage dependencies in JavaScript projects. Yarn can assist you with installing, updating, configuring, and removing packages dependencies.

Code repository

The code for this pattern is available in the GitHub waitcondition-hook-for-aws-fargate-task repository.

Best practices

Epics

TaskDescriptionSkills required

Install the AWS CDK.

To install the AWS CDK on your local machine or other environment, run the following command:

npm install -g aws-cdk@latest
Cloud architect, App developer

Bootstrap the AWS CDK.

Bootstrapping is the process of preparing an environment for deployment. To bootstrap your AWS CDK toolkit for the target AWS account and AWS Region, run the following command:

cdk bootstrap aws://ACCOUNT-NUMBER-1/REGION-1

This command creates a CloudFormation stack named CDKToolkit.

Cloud architect

Set up the AWS CDK

TaskDescriptionSkills required

Install the AWS CDK.

To install the AWS CDK on your local machine or other environment, run the following command:

npm install -g aws-cdk@latest
Cloud architect, App developer

Bootstrap the AWS CDK.

Bootstrapping is the process of preparing an environment for deployment. To bootstrap your AWS CDK toolkit for the target AWS account and AWS Region, run the following command:

cdk bootstrap aws://ACCOUNT-NUMBER-1/REGION-1

This command creates a CloudFormation stack named CDKToolkit.

Cloud architect
TaskDescriptionSkills required

Create the CDK project.

Create a CDK project using the language that you prefer. This pattern uses TypeScript. To create a CDK project using TypeScript, run the following command:

cdk init app —language typescript

Cloud architect

Install the package.

Execute npm install on the root path of your CDK project. After the CDK library has been installed, run the following command to install waitcondition-hook-for-aws-fargate-task:

yarn add waitcondition-hook-for-aws-fargate-task

Cloud architect

Build your CDK application and Amazon ECS components.

Build your CDK project. An Amazon ECS task definition resource is required. For information about creating a task definition, see Amazon ECS task definitions in the Amazon ECS documentation.

The following example uses this construct:

import * as cdk from 'aws-cdk-lib'; import { Vpc } from 'aws-cdk-lib/aws-ec2'; import * as ecr from 'aws-cdk-lib/aws-ecr'; import * as ecs from 'aws-cdk-lib/aws-ecs'; import { Construct } from 'constructs'; import { FargateRunner } from 'waitcondition-hook-for-aws-fargate-task'; import { Queue } from 'aws-cdk-lib/aws-sqs'; export class FargateRunnerStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // Define the VPC const vpc = new Vpc(this, 'MyVpc') // Define the Fargate Task const taskDefinition = new ecs.FargateTaskDefinition(this, 'MyTask', {}); // Import exiting ecr repo const repo = ecr.Repository.fromRepositoryName(this, 'MyRepo', 'RepoName'); // Add a container to the task taskDefinition.addContainer('MyContainer', { image: ecs.ContainerImage.fromEcrRepository(repo), }); // Create the Fargate runner const myFargateRunner = new FargateRunner(this, 'MyRunner', { fargateTaskDef: taskDefinition, timeout: `${60 * 5}`, vpc: vpc, }); // Create the SQS queue const myQueue = new Queue(this, 'MyQueue', {}); // Add dependency myQueue.node.addDependency(myFargateRunner); } }
Cloud architect

Synth and launch the CDK application.

  1. To generate the assets and CloudFormation template, run the following command in your CDK root path:

    cdk synth

  2. After the synth command is successful, run the following command to deploy the resources:

    cdk deploy

The waitcondition-hook-for-aws-fargate-task construct runs the Fargate task.

Cloud architect

Run the WaitCondition hook for AWS Fargate tasks construct

TaskDescriptionSkills required

Create the CDK project.

Create a CDK project using the language that you prefer. This pattern uses TypeScript. To create a CDK project using TypeScript, run the following command:

cdk init app —language typescript

Cloud architect

Install the package.

Execute npm install on the root path of your CDK project. After the CDK library has been installed, run the following command to install waitcondition-hook-for-aws-fargate-task:

yarn add waitcondition-hook-for-aws-fargate-task

Cloud architect

Build your CDK application and Amazon ECS components.

Build your CDK project. An Amazon ECS task definition resource is required. For information about creating a task definition, see Amazon ECS task definitions in the Amazon ECS documentation.

The following example uses this construct:

import * as cdk from 'aws-cdk-lib'; import { Vpc } from 'aws-cdk-lib/aws-ec2'; import * as ecr from 'aws-cdk-lib/aws-ecr'; import * as ecs from 'aws-cdk-lib/aws-ecs'; import { Construct } from 'constructs'; import { FargateRunner } from 'waitcondition-hook-for-aws-fargate-task'; import { Queue } from 'aws-cdk-lib/aws-sqs'; export class FargateRunnerStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // Define the VPC const vpc = new Vpc(this, 'MyVpc') // Define the Fargate Task const taskDefinition = new ecs.FargateTaskDefinition(this, 'MyTask', {}); // Import exiting ecr repo const repo = ecr.Repository.fromRepositoryName(this, 'MyRepo', 'RepoName'); // Add a container to the task taskDefinition.addContainer('MyContainer', { image: ecs.ContainerImage.fromEcrRepository(repo), }); // Create the Fargate runner const myFargateRunner = new FargateRunner(this, 'MyRunner', { fargateTaskDef: taskDefinition, timeout: `${60 * 5}`, vpc: vpc, }); // Create the SQS queue const myQueue = new Queue(this, 'MyQueue', {}); // Add dependency myQueue.node.addDependency(myFargateRunner); } }
Cloud architect

Synth and launch the CDK application.

  1. To generate the assets and CloudFormation template, run the following command in your CDK root path:

    cdk synth

  2. After the synth command is successful, run the following command to deploy the resources:

    cdk deploy

The waitcondition-hook-for-aws-fargate-task construct runs the Fargate task.

Cloud architect
TaskDescriptionSkills required

Clean up resources.

To clean up the resources provisioned from the previous step, run the following command:

cdk destroy
Cloud architect

Clean up

TaskDescriptionSkills required

Clean up resources.

To clean up the resources provisioned from the previous step, run the following command:

cdk destroy
Cloud architect

Troubleshooting

IssueSolution

General CloudFormation stack failure

To help troubleshoot general CloudFormation stack failures, add the --no-rollback flag as shown in the following example:

cdk deploy --no-rollback

This command will pause the CloudFormation stack from rolling back, which gives you resources to troubleshoot. For more information, see Choose how to handle failures when provisioning resources in the AWS CloudFormation documentation.

AWS Step Functions failure

An AWS Step Functions state machine might fail to execute for different reasons. With —disable-rollback configured, use the following steps to troubleshoot:

  1. Sign in to the AWS Management Console, enter Step Functions in the Search field, and then choose the Step Functions service.

  2. In the left navigation pane, choose State machines and then select the state machine that is provisioned by the CloudFormation stack.

  3. In Executions, choose the name of the execution that failed unexpectedly.

  4. In the Event view, choose the failed step.

For more information, see Troubleshooting issues in Step Functions and Viewing execution details in the Step Functions console in the AWS Step Functions documentation.

AWS Lambda function failure

This construct provisions two Lambda functions: CallbackFunction and ErrorhandlerFunction. They can fail for various reasons such as unhandled exceptions. Use the following steps to troubleshoot:

  1. Sign in to the AWS Management Console, enter CloudWatch in the Search field, and then choose the CloudWatch service.

  2. In the left navigation pane, choose Log groups.

  3. In the Search field, enter the name of the Lambda function.

  4. Choose the log group name that’s associated with the Lambda function.

  5. To go to the Lambda function execution result, choose the latest log stream.

For more information, see Troubleshooting issues in Lambda in the AWS Lambda documentation.

Related resources

AWS documentation

Other resources

PrivacySite termsCookie preferences
© 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved.