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.

The diagram shows the workflow of waitcondition-hook-for-aws-fargate-task
:
WaitCondition
andWaitConditionHandler
are provisioned to listen to the response from the AWS Lambda functions.Depending on the result of the task, either the
CallbackFunction
or theErrorHandlerFunction
is triggered by the finish of the Fargate task.The Lambda function sends a SUCCEED or FAILURE signal to
WaitConditionHandler
.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.

The example workflow uses the waitcondition-hook-for-aws-fargate-task
construct to perform a database migration, as follows:
An Amazon Relational Database Service (Amazon RDS) instance is provisioned.
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.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
Best practices
When building your AWS CDK app, follow the Best practices for developing and deploying cloud infrastructure with the AWS CDK in the AWS CDK v2 documentation.
For the AWS Fargate task, follow the Best practices for Amazon ECS container images in the Amazon ECS documentation.
Epics
Task | Description | Skills required |
---|---|---|
Install the AWS CDK. | To install the AWS CDK on your local machine or other environment, run the following command:
| 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:
This command creates a CloudFormation stack named | Cloud architect |
Task | Description | Skills 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:
| Cloud architect |
Install the package. | Execute
| 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:
| Cloud architect |
Synth and launch the CDK application. |
The | Cloud architect |
Task | Description | Skills required |
---|---|---|
Clean up resources. | To clean up the resources provisioned from the previous step, run the following command:
| Cloud architect |
Troubleshooting
Issue | Solution |
---|---|
General CloudFormation stack failure | To help troubleshoot general CloudFormation stack failures, add the
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
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:
For more information, see Troubleshooting issues in Lambda in the AWS Lambda documentation. |
Related resources
AWS documentation
Other resources