MongoDB StatefulSet in Kubernetes

In this article, We will see how we can deploy a MongoDB replica set into the Kubernetes as a StatefulSet. There is a brief understanding of StatefulSet is required before deploying MongoDB into the Kubernetes.

Image for post
Image for post

What is StatefulSet?

In stateful application, the N-replicas of master nodes manages several worker nodes under a cluster. So, if any master node goes down the other ordinal instances will be active to execute the workflow. The master node instances must be identified as a unique ordinal number known as StatefulSet.

StatefulSet design applies to all kinds of stateful applications such as MongoDB, Redis Cache, Kafka, and any other database management system that runs under a cluster.

Design of StatefulSet

The StatefulSet will create N-replica Pods define under .spec.replicas. The Pod identity starts from 0 to N-1 ordinal set.


N = 3 (replicas)

Name of StatefulSet = mongod

Pod Identity = [ mongod-0, mongod-1, mongod-2 ]

Network Identity

  • The Pods that are defined under a StatefulSet will have a hostname construct with $(statefulset name)-$(ordinal). So, hostnames will be [mongod-0, mongod-1, mongod-2].
  • The domain name is known as connection string for database connectivity will be identified as
 $(service name).$(namespace).svc.cluster.local

The service will run as a Headless Service to manage the domain of a Pod. In general understanding of Headless Service, there is no need for LoadBalancer or a kube-proxy to interact directly with Pods but using a Service IP, so the Cluster IP is set to none.

  • The StatefulSet domain for each Pod will look like
$(statefulset name)-$(ordinal).$(service name).$(namespace).svc.cluster.local





Each StatefulSet domain will work as a DNS subdomain depending on the configuration of DNS for a Cluster.

Deployment and Scaling of StatefulSet

  • Pods are deployed in {0..N-1} order for a StatefulSet of N-replicas.
  • The termination of Pods is performed in reverse {N-1..0}.
  • The execution of a Pod depends on other ordinal index Pods to be running and active.
  • The termination of a Pod also required other ordinal index Pods has to be terminated before.

Deploying MongoDB as Kubernetes StatefulSet

The deployment will follow as creating a Headless Service and StatefulSet with N=3 replicas under a cluster. We will also see how to set up the MongoDB administrator for a container that runs under a cluster.

Create Headless Service

YAML: mongodb-service.yaml

$ kubectl apply -f mongodb-service.yaml

Deploy MongoDB StatefulSet

YAML: mongodb-statefulset.yaml

$ kubectl apply -f mongodb-statefulset.yaml

The StatefulSet requires at least 1GB of persistent storage that can be achieved through StorageClass, PersistentVoulmeClaim while deploying the StatefulSet.

Setup the ReplicaSet and Administrator

We can create an Administrator for any single Pod among N-replicas.

$ kubectl exec -it mongod-0 -c mongod-container-app bash
root@mongod-0:/# hostname -f
root@mongod-0:/# mongod-0.mongodb-service.default.svc.cluster.local

Type the following command to generate the replica set.

Create the Administrator for the MongoDB

Verify MongoDB StatefulSet Setup from minikube dashboard

Type the following command to navigate to the Kubernetes dashboard in the browser.

$ minikube dashboard
Image for post
Image for post
Workload Status
Image for post
Image for post
mongod StatefulSet
Image for post
Image for post
MongoDB StatefulSet Metadata
Image for post
Image for post
MongoDB StatefulSet Pods
Image for post
Image for post
MongoDB Headless Service
Image for post
Image for post
MongoDB Persistent Volume Claims 1GB storage capacity for each Pod
Image for post
Image for post
MongoDB StatefulSet Events

So, this covers the overview of understanding Kubernetes StatefulSet and deploying a stateful application like MongoDB as StatefulSet in the minikube environment.

Please also check the project on Kubernetes at my Github.

I hope you find this article useful :)


Written by

Working on various software development projects, [Android, Go, Blockchain, Node.js, MongoDB, JavaScript, Kubernetes, Docker]

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store