How to Deploy MongoDB Atlas With the Atlas Kubernetes Operator
Rate this tutorial
Kubernetes, a container orchestration tool, enables developers to automate the deployment, scaling, and management of their containerized applications. Kubernetes is popular among developers for its security benefits and the fact that it comes in many different flavors, including AWS' EKS, Microsoft Azure's AKS, and Google Cloud’s GKE. MongoDB Atlas enables developers to seamlessly integrate Atlas into their current Kubernetes deployment pipeline through our MongoDB Atlas Kubernetes Operator.
The Atlas Kubernetes Operator enables customers using Kubernetes to create and manage Atlas resources in one of the supported public clouds with exactly the same tools and processes that they use for their existing services in Kubernetes. The operator works by extending the Kubernetes API to support custom resources, enabling developers to manage MongoDB resources as native Kubernetes objects, even though Atlas is running outside of the cluster. Developers can create and apply custom resources into Kubernetes to define Atlas configuration, and the Atlas Kubernetes Operator automates the application of that configuration via the Atlas Admin API.
There are many ways to get started with the Atlas Kubernetes Operator, such as via the Atlas CLI or through a Helm Chart. This tutorial will walk you through how to get started using the MongoDB Atlas Kubernetes Operator Quick Start. Let’s get started!
- A MongoDB Atlas account
- A running Kubernetes cluster with nodes running processors with the x86-64, AMD64, or ARM64 architecture — you can use some like Minikube to test with
First, you will need to install the operator into a running Kubernetes cluster. Make sure that it’s running processors with the x86-64, AMD64, or ARM64 architecture. In this example, we are running a Kubernetes cluster using Minikube and Docker, and using Kubectl to apply commands.
Once you have logged into your Atlas account, you will first create API keys for use by the operator.
In the top left-hand corner, click on the “Access Manager” drop-down and the API keys tab. Click on “Create API Key.”
Note: If you want the Atlas Kubernetes Operator to create a new Atlas project to work in, you will need to create and use the API keys for an organization. For an existing project, you will need to create them for a project. For this example, we’ll be creating a new Atlas project. For either type of project, it is best practice to configure an API access list.
Here, you will input a name for your API keys (for example, AKO/Vector Search Keys) and select the organization role. You must assign the API key the Organization Project Creator organization role or higher.
From there, you will find a set of unique API keys generated for you. Be sure to save these somewhere secure. Once you leave this page, you will not be able to recover them!
Next, we will install/deploy the operator into the Kubernetes cluster you have running.
Once deployed, the Atlas Kubernetes Operator can monitor resources and events across a single or multiple Kubernetes namespaces. This capability allows the operator to manage MongoDB Atlas custom resources comprehensively across the entire Kubernetes cluster or specific designated namespaces.
For this example, we’ll set up the operator to watch all namespaces in our cluster, but you can learn how to set up the operator to watch a single namespace in our documentation.
Use the following command in your terminal:
1 kubectl apply -f https://raw.githubusercontent.com/mongodb/mongodb-atlas-kubernetes/v2.3.1/deploy/all-in-one.yaml
Make sure to replace the
<version> with the latest update in the following format: “v2.x.x”.Next, we’ll create a secret in Kubernetes. A Kubernetes secret is an object used to store and manage sensitive information, such as passwords, OAuth tokens, and SSH keys, securely within a Kubernetes cluster. In this case, it will be the API keys you created earlier.
If you use external secret storage, you don't need to put sensitive information directly into Kubernetes secrets. To learn more, see Configure Secret Storage.
Input the following command and replace
<atlas_organization_id> with your organization ID, <atlas_api_public_key> with your public API key, and <atlas_api_private_key> with your private key.Troubleshooting: If the following command produces an error, try to run the command without quotes (eg.
--from-literal=orgId=<atlas_organization_id> \)1 kubectl create secret generic mongodb-atlas-operator-api-key \ 2 --from-literal="orgId=<atlas_organization_id>" \ 3 --from-literal="publicApiKey=<atlas_api_public_key>" \ 4 --from-literal="privateApiKey=<atlas_api_private_key>" \ 5 -n mongodb-atlas-system
Next, use the following command to label your secret:
1 kubectl label secret mongodb-atlas-operator-api-key atlas.mongodb.com/type=credentials -n mongodb-atlas-system
Projects allow you to isolate different database environments (for instance, development/qa/prod environments) from each other, as well as users/teams. Here, we’ll use the operator to create a project in the Atlas UI through an Atlas project custom resource.
Input the following command in your terminal.
1 cat <<EOF | kubectl apply -f - 2 apiVersion: atlas.mongodb.com/v1 3 kind: AtlasProject 4 metadata: 5 name: my-project 6 spec: 7 name: Test Atlas Operator Project 8 projectIpAccessList: 9 - cidrBlock: "0.0.0.0/0" 10 comment: "Allowing access to database from everywhere (only for Demo!)" 11 EOF
Note: The above commands will add the CIDR 0.0.0.0/0 to your IP access list if input as is. This CIDR allows any client to connect to the Atlas cluster. Do not use this IP address in production.
If you are working off an existing project in Atlas, be sure to change
name: my-project to the name of your project in Atlas, and update the cidrBlock to your current IP address.After entering this command, check your Atlas UI. You should see a project created in the Atlas UI called “Test Atlas Operator Project.”
Deployments are instances of MongoDB running on a cloud provider. This custom resource will create a free tier M0 cluster, but you can always adjust the size of your cluster depending on your workload needs in the custom resource. In your terminal, enter this command:
1 cat <<EOF | kubectl apply -f - 2 apiVersion: atlas.mongodb.com/v1 3 kind: AtlasDeployment 4 metadata: 5 name: my-test-cluster 6 spec: 7 projectRef: 8 name: my-project 9 deploymentSpec: 10 clusterType: REPLICASET 11 name: test-atlas-operator-project 12 replicationSpecs: 13 - regionConfigs: 14 - regionName: US_EAST_1 15 providerName: TENANT 16 backingProviderName: AWS 17 electableSpecs: 18 instanceSize: M0 19 nodeCount: 3 20 EOF
Now, within Projects in the Atlas UI, you should see “1 Cluster” created under the Clusters column.
Next, you’ll want to create a secret for your password.
Input the following command. Make sure to replace
P@@ssword% with a password of your choice.1 kubectl create secret generic the-user-password --from-literal="password=P@@sword%"
Next, use the following command to label your password.
1 kubectl label secret the-user-password atlas.mongodb.com/type=credentials
With the cluster configured, we’ll create a AtlasDatabaseUser custom resource using the following command. Make sure to replace the password you defined before in the code line that says
the-user-password.1 cat <<EOF | kubectl apply -f - 2 apiVersion: atlas.mongodb.com/v1 3 kind: AtlasDatabaseUser 4 metadata: 5 name: my-database-user 6 spec: 7 roles: 8 - roleName: "readWriteAnyDatabase" 9 databaseName: "admin" 10 projectRef: 11 name: my-project 12 username: theuser 13 passwordSecretRef: 14 name: the-user-password 15 EOF
You will need to keep running the following command until you get a
True response. This may take some time and you may need to run it multiple times before you get the correct response.1 kubectl get atlasdatabaseusers my-database-user -o=jsonpath='{.status.conditions[?(@.type=="Ready")].status}'
Finally, you’ll need to retrieve the secret that the operator created. Getting your connection string to the newly created database can also be done through Kubernetes. For this step, you will need to have jq (version 1.6 or higher) installed.
Input the following command after you’ve replaced the following parts of the code with what is in the metadata from the custom resources you applied before:
my-project: Specify the value of the metadata field of your AtlasProject Custom Resource (in this example,my-project).my-atlas-cluster: Specify the value of the metadata field of your AtlasDeployment Custom Resource (in this example,my-test-cluster).my-database-user: Specify the value of the metadata field of your AtlasDatabaseUser Custom Resource (in this example,my-database-user)
1 kubectl get secret {my-project}-{my-atlas-cluster}-{my-database-user} -o json | jq -r '.data | with_entries(.value |= @base64d)';
Next, run this command to obtain a connection string. Make sure to input the password and username you had before next to the fields where you see
“password” and “username”.1 { 2 "connectionStringStandard": "mongodb://theuser:P%40%40sword%25@test-cluster-shard-00-00.peqtm.mongodb.net:27017,test-cluster-shard-00-01.peqtm.mongodb.net:27017,test-cluster-shard-00-02.peqtm.mongodb.net:27017/?ssl=true&authSource=admin&replicaSet=atlas-pk82fl-shard-0", 3 "connectionStringStandardSrv": "mongodb+srv://theuser:P%40%40sword%25@test-cluster.peqtm.mongodb.net", 4 "password": "P@@sword%", 5 "username": "theuser" 6 }
Your connection strings will look different from the connection string in this example.
Finally, you can consume the secret as an environment variable with your application:.
1 containers: 2 - name: test-app 3 env: 4 - name: "CONNECTION_STRING" 5 valueFrom: 6 secretKeyRef: 7 name: test-atlas-operator-project-test-cluster-theuser 8 key: connectionStringStandardSrv
With that, you have successfully leveraged the Atlas Operator to create and connect to a new Atlas cluster, via Kubernetes!
To learn more about the Atlas Kubernetes Operator, you can go to the Atlas Operator documentation. If you are using MongoDB Enterprise Advanced instead of Atlas, we have the Enterprise Kubernetes Operator available for running MongoDB within your own Kubernetes environment.
Top Comments in Forums
There are no comments on this article yet.