Creating an Acorn Service for MongoDB Atlas

by | Jun 13, 2023

Spread the word

Last week, Acorn 0.7 introduced the new Acorn Services functionality which allows developers to easily provision cloud components such as databases or message queues so applications can utilize them. The idea behind Acorn Services is that anyone can create services that can be reused as often as needed to create, configure and incorporate instances of cloud services into apps running on Kubernetes. In this article we will detail how to build and then use an Acorn Service for MongoDB Atlas database, the SaaS solution powered by MongoDB, Inc.

Prerequisites

First we need a Kubernetes cluster with Acorn 0.7+ as the Service functionality was made available in Acorn 0.7.0.

We also need a MongoDB Atlas account and an organization/project within this one. You can refer to https://www.mongodb.com/cloud to get more details. In this example we will use an organization named Techwhale containing the project webhooks.

Once we are logged in with our Atlas account, we create a public/private api key pair at the organization level.

Organization api keys

Next we create a project and get its ID:

Getting project ID

For the example detailed in this article, we define the following environment variables to store the public/private keys and the project ID:

  • MONGODB_ATLAS_PUBLIC_API_KEY
  • MONGODB_ATLAS_PRIVATE_API_KEY
  • MONGODB_ATLAS_PROJECT_ID

In a next part we will use these environment variables so our Service can communicate with the MongoDB Atlas API.

Definition of the Acorn Service for MongoDB Atlas

Let’s now see how we can define an Acorn Service. To keep things clean we will consider the 3 following files:

  • Acornfile
  • Dockerfile
  • render.sh

The Acornfile contains the definition of the Service as follows

This file contains the 4 top level keys:

  • args
  • service
  • jobs
  • secrets

Let’s explore these keys in more details:

The args key defines the default values the Service will use to create a MongoDB Atlas cluster. We specify we want a M0 size cluster created on AWS infrastructure in the EU_WEST_1 region. These args can be superseded at runtime should we want to create an Atlas cluster with other specifications. 

Note: when creating a MongoDB Atlas clusters, we need to specify:

  • the infrastructure it will be deployed on among AWS, GCP and Azure
  • the region in which it will run, this one depending upon the available regions of the selected cloud provider
  • its size (M0, M10, … M700), this one depending upon the RAM, storage and CPUs requirements

The services key specifies that a Service named atlas will be generated by an Acorn Job named create-mongo-atlas-service

The jobs key defines the create-mongo-atlas-service Job, this one contains all the logic to create an Atlas cluster (more on that in a bit).

The secrets key defines several Acorn Secrets:

  • internal-db-creds is used to generate a username / password pair on the fly, these values are provided to the create-mongo-atlas-service Job via environment variables so it can create a database user with those credentials
  • db-creds is a Secret generated by the Job, it contains the credentials of the db user
  • atlas-creds defines an external Secret containing the credentials to connect to the Atlas account. This Secret must exist in the Acorn project before the Service can be used.

The Job runs within a container built with the following Dockerfile:

It basically contains the Atlas cli and executes the render.sh script to perform all the Atlas related actions.

The render.sh file contains the logic to create / delete an Atlas cluster. It also creates a default database user and ensures the database is accessible via the current IP address. This script generates the file /run/secrets/output which is an Acornfile containing the details of the Service: the address to use to access the MongoDB Atlas cluster generated and the user’s credentials:

Running the Service

Before running the Service we first need to create the atlas-creds Secret. This Secret contains the Atlas public and private keys as well as the Atlas project ID we want the MongoDB cluster to be created in.

Note: the following example uses environment variables already defined in the current shell

Next we run the Service as we would do with a standard Acorn application:

Notes regarding Atlas cluster:

  • by default the Service creates a M0 cluster, this size is available for free in Atlas but only has limited specifications in terms of CPU, RAM and storage
  • only one M0 cluster can be created in each Atlas project
  • for cluster other than M0 tier, billing information needs to be provided in Atlas

In a few tens of seconds a new Atlas cluster will be up and running.

Cluster created

Once we verified the Service is running fine we can go ahead and remove the application, doing so will also delete the associated Atlas cluster:

We have defined the Service and tested it to make sure it creates a MongoDB Atlas cluster. Now, let’s publish the Service and start using it with Acorn applications.

Publishing the Acorn Service for MongoDB Atlas

First we need to build an image of the Service:

Next we log to the DockerHub (the registry we will push the image to)

Next we push the image:

Once the image is in the registry we have an Acorn Service for MongoDB Atlas that we can use with other applications.

Using the Acorn Service for MongoDB Atlas with a simple container

The following Acornfile defines an application which:

  • uses the atlas Service
  • container app using this Service. This container regularly tries to connect to the database until it manages to do so. It uses the MONGODB_URL environment variable set from the Service’s properties

Lets run the application with the following command:

As we’ve done before, we could go to the Atlas dashboard and notice a MongoDB cluster was automatically created.

Also, from the app container logs we can see the connection was successful after a few tens of seconds.

We can now delete the Acorn app and remove the Atlas cluster from the dashboard:

In this part we used the Atlas Service from a simple application, let’s now use a more interesting microservice application.

Using the Atlas Service with a microservice application

The Webhooks application (live version available on https://webhooks.app/) is a microservice application that provides a webhook (HTTP POST endpoint) on the fly, which I like to use to test and demonstrating software.

Note: if you want to know more about this sample application, feel free to check the source code in https://gitlab.com/web-hook.

Each time a change is done in one of the application’s microservice, the entire app is built and pushed as an Acorn image to the Docker Hub (https://hub.docker.com/r/lucj/webhooksapp/tags).

Recently the application’s Acornfile has been modified so it allows this application to use the Atlas Service if the –atlas flag is provided when the app is launched.

Let’s run the Webhooks app using this flag:

After a few tens of second we can see an Atlas cluster is created, this can be verified from the Atlas dashboard:

Also, a HTTP endpoint is returned, in the current example the endpoint is http://default-webhook-a1a950fb.awawu9.oss-acorn.io. Using this endpoint we can access the application and make sure it’s working fine.

Let’s now use a the MongoDB Compass client to connect to the Atlas cluster created by the Service and verify the payloads are stored there.

First we get the connection string from the Atlas dashboard (this can also be retrieved using the Atlas cli)

In the current example, the connection string is the following one (password is not visible here):

mongodb+srv://wjc98wds:<password>@test.b7wdadc.mongodb.net/

Next we get the user credentials generated during the MongoDB creation process

We can then use MongoDB Compass to connect to the database with the following connection string:

mongodb+srv://wjc98wds:[email protected]/

Once connected we can verify a single webhook exists in the database (the one automatically created when we launched a browser using the endpoint returned by Acorn), it contains the dummy payload we sent:

We can then remove the application and the associated components:

Key takeaways

In this article we explained how the Acorn Service for MongoDB Atlas has been created and published. Then we illustrated how this Service can be used with a single container and with the webhooks application.

The code used in this article is available in GitHub so you can create your own Atlas Service if you feel like it. This Atlas Service is still a work in progress, additional functionalities will be added soon. 

Learn more on Acorn Services with the Acorn documentation.

In the next article of this micro series we will create a NATS Service and illustrate its usage with the same webhooks application.

Luc Juggery is a software engineer with 18+ years of experience and co-founder of 2 startups located in Sophia-Antipolis, southern France. You can chat with him on Twitter, read more of his work on Medium, find his tutorials on YouTube, or take one of his Docker or Kubernetes training courses on Udemy.

Header Image Photo by Joakim Honkasalo on Unsplash


Spread the word