# Coordinate resource dependency and task execution by using the AWS Fargate WaitCondition hook construct
*Stan Fan, Amazon Web Services*
## 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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html) 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](https://docs.aws.amazon.com/cdk/v2/guide/cli.html) in the AWS CDK documentation.
+ Node package manager (npm), installed on a local workstation and configured for the [AWS CDK in TypeScript](https://docs.aws.amazon.com/cdk/v2/guide/work-with-cdk-typescript.html). For more information, see [Downloading and installing Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) in the npm documentation.
+ Yarn installed on a local workstation. For more information, see [Installation](https://yarnpkg.com/getting-started/install) 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](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/). For specific endpoints, see [Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html), 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`:
1. `WaitCondition` and `WaitConditionHandler` are provisioned to listen to the response from the AWS Lambda functions.
1. Depending on the result of the task, either the `CallbackFunction` or the `ErrorHandlerFunction` is triggered by the finish of the Fargate task.
1. The Lambda function sends a SUCCEED or FAILURE signal to `WaitConditionHandler`.
1. `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:
1. An Amazon Relational Database Service (Amazon RDS) instance is provisioned.
1. 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.
1. 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)](https://docs.aws.amazon.com/cdk/v2/guide/home.html) is a software development framework that helps you define cloud infrastructure in code and provision it through CloudFormation.
+ [CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) 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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) 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)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) is a fast and scalable container management service that helps you run, stop, and manage containers on a cluster.
+ [AWS Fargate](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html) 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)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) helps you securely manage access to your AWS resources by controlling who is authenticated and authorized to use them.
+ [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) 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](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html) 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)](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) 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](https://docs.npmjs.com/about-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](https://yarnpkg.com/) 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](https://github.com/aws-samples/waitcondition-hook-for-aws-fargate-task) repository.
## Best practices
+ When building your AWS CDK app, follow the [Best practices for developing and deploying cloud infrastructure with the AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/best-practices.html) in the AWS CDK v2 documentation.
+ For the AWS Fargate task, follow the [Best practices for Amazon ECS container images](https://docs.aws.amazon.com/AmazonECS/latest/bestpracticesguide/application.html) in the Amazon ECS documentation.
## Epics
### Set up the AWS CDK
| Task | Description | Skills 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](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) is the process of preparing an [environment](https://docs.aws.amazon.com/cdk/v2/guide/environments.html) 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 |
### Run the WaitCondition hook for AWS Fargate tasks construct
| 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:
`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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) 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. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/use-the-aws-fargate-waitcondition-hook-construct.html)The `waitcondition-hook-for-aws-fargate-task` construct runs the Fargate task. | Cloud architect |
### Clean up
| Task | Description | Skills required |
| --- | --- | --- |
| Clean up resources. | To clean up the resources provisioned from the previous step, run the following command:cdk destroy
| Cloud architect |
## Troubleshooting
| Issue | Solution |
| --- | --- |
| 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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stack-failure-options.html) in the 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:[See the AWS documentation website for more details](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/use-the-aws-fargate-waitcondition-hook-construct.html)
For more information, see [Troubleshooting issues in Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/troubleshooting.html) and [Viewing execution details in the Step Functions console](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-view-execution-details.html#exec-details-intf-step-details) 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: [See the AWS documentation website for more details](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/use-the-aws-fargate-waitcondition-hook-construct.html)
For more information, see [Troubleshooting issues in Lambda](https://docs.aws.amazon.com/lambda/latest/dg/lambda-troubleshooting.html) in the AWS Lambda documentation. |
## Related resources
**AWS documentation**
+ [AWS CDK Construct API Reference](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html)
+ [Getting started with the AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html)
+ [Learn how to create and use Amazon ECS resources](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/getting-started.html)
+ [Learn how to get started with Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/getting-started-with-sfn.html)
+ [What is AWS CDK?](https://docs.aws.amazon.com/cdk/v2/guide/home.html)
**Other resources**
+ [Waitcondition Hook for AWS Fargate task](https://pypi.org/project/waitcondition-hook-for-aws-fargate-task/) (npm)
+ [waitcondition-hook-for-aws-fargate-task 1.0.6](https://pypi.org/project/waitcondition-hook-for-aws-fargate-task/) (pypi.org)