Build containerized applications for Amazon DocumentDB that run on Amazon ECS on AWS Fargate

As organizations modernize their applications, they are increasingly choosing containerization as their preferred approach. Containerization decouples applications from the underlying host infrastructure. Each container that you run is repeatable, and the standardization from dependencies included means that you get the same behavior wherever you run it. In this post, we explore the fundamentals of building containerized applications for Amazon DocumentDB (with MongoDB compatibility) using Quarkus with the Panache ORM library. We cover the processes of containerizing your code, building an image, and deploying it using Amazon Elastic Container Service (Amazon ECS) with AWS Fargate.

Amazon DocumentDB is a fully managed native JSON document database that makes it straightforward and cost-effective to operate critical document workloads at virtually any scale without managing infrastructure. You can use the same application code written using the MongoDB API (versions 3.6, 4.0, and 5.0) compatible drivers and tools to run, manage, and scale workloads on Amazon DocumentDB without worrying about managing the underlying infrastructure. As a document database, Amazon DocumentDB makes it straightforward to store, query, and index JSON data.

Amazon ECS is a fully managed container orchestration service that helps you more efficiently deploy, manage, and scale containerized applications. AWS Fargate is a serverless, pay-as-you-go compute engine that lets you focus on building applications without managing servers. Amazon ECS can schedule containers onto Fargate to automatically scale, load balance, and optimize container availability through managed scheduling, providing a straightforward way to build and operate containerized applications.

Quarkus lets Java developers to create applications for a modern, cloud-centered world. Quarkus is a Kubernetes-focused Java framework.

Solution overview

In this post, we create a container image of a sample application using the Quarkus framework and publish the image to the repository in Amazon Elastic Container Registry (Amazon ECR). We use Amazon ECS to deploy and manage the containerized application. This involves creating an ECS cluster, building an ECS task definition for the Docker image to run on Fargate, and setting up an ECS service to launch two tasks based on the task definition. Once everything is in place, we use a public IP to test API calls and interact with Amazon DocumentDB.

The following diagram illustrates the solution architecture.

Prerequisites

Launch the provided AWS CloudFormation stack to create an Amazon DocumentDB cluster with required network components and an Amazon Elastic Compute Cloud (Amazon EC2) instance to build the Docker image. This CloudFormation template only works in the US East (N. Virginia) us-east-1 AWS Region because Amazon Machine Images (AMIs) in Amazon EC2 are Region specific.

Enter a stack name and other required parameters on the Specify stack details page.

Deployment takes about 20 minutes. When the stack creation is complete, navigate to the Outputs tabs for the stack on the AWS CloudFormation console and note the values for subsequent use. The exports are used by the next template we run after the manual steps.

Resources created can incur costs in your AWS accounts.

Create a Docker image

To generate a Docker image from sample code, refer to the instructions in the accompanying GitHub repo. Use the instance and Amazon DocumentDB cluster you created in previous steps.

Register the Docker image to Amazon ECR

After you build the Docker image, you need to register it with Amazon ECR. For more information, see Pushing a Docker image to an Amazon ECR private repository. To register the image, complete the following steps:

On the Amazon ECR console, choose Repositories in the navigation pane.
Choose Create repository, as shown in the following screenshot.
For Visibility settings, select Private.
For Repository name, enter docdb-sample-repository (do not change the name of the repository—if you do, it will break the automation).
Choose Create repository, as shown in the following screenshot.
Copy the repository URI and note it down for later use. The following screenshot shows where to find the URI.
Next, you configure the AWS Command Line Interface (AWS CLI) to be able to interact with Amazon ECR.
Check that the Docker image is available locally by using the following command:
```
docker image ls
```
Take note of the image ID.
Tag your local image with the ECR registry by using the following command:
```
docker tag <<docker_image_id>> <<repository_URI>>:latest
```

Get the login password and log in to Amazon ECR:

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <<aws_account_id>>.dkr.ecr.us-east-1.amazonaws.com

Push the image to the registry:
```
docker push <<repository_URI>>:latest
```
You can confirm if the image is uploaded on the Amazon ECR console, as shown in the following screenshot.

Create an ECS cluster on Fargate

To create an ECS cluster on Fargate, complete the following steps:

Launch the following CloudFormation stack to create an ECS task running an application with the image you uploaded in the previous step.
For Stack name, enter a name.
For ServiceName, enter DocumentDBECS.
Choose Next and create the stack, as shown in the following screenshot.

Deployment takes about 20 minutes.

After the CloudFormation completes the deployment, you can navigate to the Amazon ECS console and locate the cluster DocDbECSCluster. On the Tasks tab, choose the service you created, as shown in the following screenshot.

Locate the two running tasks, shown in the following screenshot.

You can choose one of the tasks to find the public IP address of the ECS task, as shown in the following screenshot.

Test the application

You can test the application using the set of curl commands in the sample code. You have to replace the value for localhost with the public IP of your running ECS task.

Clean up

Complete the following steps to clean up your resources:

Conclusion

In this post, we showed you how to create a Docker image from a sample Kubernetes-centered Java application to connect to Amazon DocumentDB and deploy two instances of it in an ECS Fargate cluster. When you package your applications in containers and deploy them using Amazon ECS running on Fargate, you no longer have to provision, configure, or scale clusters of virtual machines to run containers. This removes the need to choose server types, decide when to scale your clusters, or optimize cluster packing.

For more information about how to make this solution resilient and scalable for a production system, refer to Automatically scale your Amazon ECS service. To uniformly balance the traffic, refer to Use load balancing to distribute Amazon ECS service traffic.

Leave your thoughts and questions in the comments.

About the Authors

Sourav Biswas is a Senior Amazon DocumentDB Specialist Solutions Architect at AWS. He has been helping Amazon DocumentDB customers successfully adopt the service and implement best practices around it. Before joining AWS, he worked extensively as an application developer and solutions architect for various NoSQL vendors.

Varma Gottumukkala is a Senior Database Specialist Solutions Architect at AWS based out of Dallas – Fort Worth. Varma works with the customers on their database strategy and architects their workloads using AWS purpose-built databases. Before joining AWS, he worked extensively with relational databases, NOSQL databases, and multiple programming languages for the last 22 years.

AWS Database Blog