Skip to main content

How to run and deploy FerretDB in Kubernetes using Pulumi

· 12 min read
Alexander Fashakin
FerretDB Team

How to run and deploy FerretDB in Kubernetes using Pulumi

Setting up a scalable, reliable, and highly performant database application is essential for all production environments. But before then, you still need robust testing environments for your operations and teams.

Running your databases on Kubernetes can be a way to quickly provision, test, and drop databases using a CI/CD pipeline.

Pulumi, an Infrastructure as Code (IaC) platform, can be quite useful in building, managing, and deploying infrastructure in your favorite programming language and on numerous public clouds or cloud-native platforms, including Kubernetes. That also means you can use Pulumi to deploy and manage your FerretDB databases.

FerretDB is an open-source document database that adds MongoDB compatibility to relational databases like Postgres and SQLite. With Postgres as your backend, you can use Pulumi to set up FerretDB on top of StackGres – a fully-featured platform for running Postgres on Kubernetes.

In this guide, you'll learn to set up FerretDB with StackGres on Kubernetes using Pulumi.

Pulumi as your IaC tool

Pulumi empowers DevOps professionals and developers to manage infrastructure using different programming languages. Let's take a look at some of the key benefits of Pulumi.

  • Language support: Perhaps, this is the best advantage of Pulumi. Rather than learn a new vendor-specific language with its own strict schema and syntax, Pulumi lets you use manage infrastructure with programming languages like Python, JavaScript, Go, Java, and C#, among others.
  • Multi-cloud support: Pulumi supports multiple cloud providers and SaaS offerings, including AWS, Google Cloud, Microsoft Azure, DigitalOcean, Kubernetes, Docker, ConfluentCloud, and DataDog.
  • Open source: Pulumi is fully open source under the Apache 2.0 license. Being open-source means the community is a huge part of Pulumi. They help in building and supporting Pulumi providers, components, and configurations while also creating educational resources about Pulumi.


Set up a Kubernetes Cluster

Before deploying FerretDB using Pulumi, you need to have a Kubernetes cluster running, along with command line tools kubectl. If these tools are not installed, please see their respective documentation.

This guide uses minikube to create a cluster. minikube is a local Kubernetes setup that makes it easy to learn, experiment, and develop for Kubernetes. Check out the minikube setup on how to get started and create a cluster.

Please also ensure that your cluster is set as the current context.

To list all available contexts available to kubectl:

kubectl config get-contexts

The current context is marked with an asterisk (*) in the output. Use the kubectl config use-context command with the name of your desired context to switch the current context to the specified cluster.

kubectl config use-context <your-desired-context>

Start the setup by creating a ferretdb namespace within the cluster. That way, you can isolate, group, and manage your resources, access controls, and other configurations.

kubectl create namespace ferretdb

Installing the StackGres Operator

Here, you will need to install the StackGres operator on a Kubernetes cluster. To do that,

Install the operator with the following command:

kubectl create -f

This will install all the necessary resources, and also add the operator to a new namespace stackgres.

It may take some time for the operator to be ready. If you want to wait until the operator is ready, run the following command:

kubectl wait -n stackgres deployment -l --for=condition=Available

The pod status should be set to running once they are ready:

% kubectl get pods -n stackgres
stackgres-operator-6f7c75bff4-mwchl 1/1 Running 1 (6m38s ago) 8m28s
stackgres-restapi-77c978b5dc-2lzm6 2/2 Running 0 6m17s

The next to do is to create a Secret in the ferretdb namespace. The Secret will contain a random password generated using the SQL command in the following script.



# Secret name

PASSWORD=$(openssl rand -base64 12)

kubectl -n $NAMESPACE create secret generic $SECRET_NAME --from-literal=sql="CREATE USER ferretdb WITH PASSWORD '${PASSWORD}';" --dry-run=client -o yaml | kubectl apply -f -

Save the script as or whatever you prefer. Make this executable by running this in the directory terminal:

chmod +x ./

Then execute the script and create a unique password.


Create Pulumi project

Pulumi will be used to orchestrate our entire setup. With our cluster now available, let's go ahead to set up the Pulumi project. But before setting up the project, ensure to install Pulumi (find the installation guide here).

Create a directory for the project. This will hold the configuration and particular project details for Pulumi. Since you already have kubectl configured, Pulumi will use the same configuration settings.

mkdir ferretdb-pulumi && cd ferretdb-pulumi
pulumi new kubernetes-python

You will be prompted to enter a project name, description, and stack. Go ahead and press ENTER to confirm the default values, or you can specify your own.

Once this is complete, the project will initialize a new Pulumi project using the Kubernetes Python template and this will generate a couple of files:

  • Pulumi.yaml contains the project definition.
  • contains the initialized stack configuration values.
  • is the main Pulumi program that defines the resources in your stack.

Deploy StackGres Cluster with FerretDB on Kubernetes using Pulumi

Here, you'll use Pulumi to provision and orchestrate all the resources. This will include setting up the connection pooling, creating the Postgres database, deploying the Stackgres, and finally, setting up FerretDB.

Start by deleting the existing content in the file. Then add the following to the file.

import pulumi
from pulumi_kubernetes.core.v1 import Namespace, Service
from pulumi_kubernetes.apps.v1 import Deployment
from pulumi_kubernetes.apiextensions import CustomResource
from pulumi import ResourceOptions

# SGPoolingConfig Creation
sg_pooling_config = CustomResource(
"name": "sgpoolingconfig1",
"namespace": "ferretdb"
"pgBouncer": {
"pgbouncer.ini": {
"pgbouncer": {
"ignore_startup_parameters": "extra_float_digits,search_path"

# SGScript Creation
sg_script = CustomResource(
"name": "createuserdb",
"namespace": "ferretdb"
"scripts": [
"name": "create-user",
"scriptFrom": {
"secretKeyRef": {
"name": "createuser",
"key": "sql"
"name": "create-database",
"script": "create database ferretdb owner ferretdb encoding 'UTF8' locale 'en_US.UTF-8' template template0;"

# Stackgres Cluster Creation
stackgres_cluster = CustomResource(
"namespace": "ferretdb",
"name": "postgres"
"postgres": {
"version": "15"
"instances": 1,
"pods": {
"persistentVolume": {
"size": "1Gi"
"configurations": {
"sgPoolingConfig": "sgpoolingconfig1"
"managedSql": {
"scripts": [
{"sgScript": "createuserdb"}

# FerretDB Deployment
ferretdb_deployment = Deployment(
"name": "ferretdb-deployment",
"namespace": "ferretdb"
"replicas": 1,
"selector": {"matchLabels": {"app": "ferretdb"}},
"template": {
"metadata": {"labels": {"app": "ferretdb"}},
"spec": {
"containers": [{
"name": "ferretdb",
"image": "ferretdb/ferretdb:latest",
# Update this URL with the correct connection string
"env": [{
"value": "postgres://ferretdb:PASSWORD@postgres.ferretdb.svc.cluster.local:5432/ferretdb"
"ports": [{"containerPort": 27017}]

# FerretDB Service
ferretdb_service = Service(
"name": "ferretdb-service",
"namespace": "ferretdb"
"ports": [{"port": 27017, "targetPort": 27017}],
"selector": {"app": "ferretdb"},
"type": "ClusterIP"

pulumi.export('ferretdb_service_ip', ferretdb_service.metadata.apply(lambda meta:

The resources:

  • SGPoolingConfig: Defines a CustomResource config for connection pooling, particularly to customize PgBouncer settings. Normally, FerretDB will attempt to configure the search_path parameter in PostgreSQL during startup. However, PgBouncer does not support this. So this will customize PgBouncer behavior to ignore this parameter.
  • SGScript: Creates a StackGres script resource for initializing the user and the ferretdb database. The user password is sourced from the Secret created earlier.
  • Stackgres Cluster: Deploys a PostgreSQL database cluster managed by StackGres. This will help to deploy, scale, and manage Postgres clusters and also apply the custom resource for SGPoolingConfig and SGScript.
  • FerretDB deployment and service: There are two additional resources. One contains the deployment specifications for FerretDB and configures it to connect to a ferretdb database created with StackGres. It specifies the FERRETDB_POSTGRESQL_URL environment variable, which points to the Postgres database defined by the StackGres cluster.
  • FerretDB Service: This exposes the FerretDB deployment within the cluster on port 27017, making it accessible to other services within the same cluster.

This setup should provide us with a fully managed, scalable FerretDB deployment in Kubernetes environments.

Run pulumi up to tie and deploy all the resources.

% pulumi up
Previewing update (dev)

View in Browser (Ctrl+O):

Type Name Plan
+ pulumi:pulumi:Stack ferretdb-pulumi-dev create
+ ├─ sg-pooling-config create
+ ├─ createuserdb create
+ ├─ stackgres-cluster create
+ ├─ kubernetes:apps/v1:Deployment ferretdb-deployment create
+ └─ kubernetes:core/v1:Service ferretdb-service create

ferretdb_service_ip: "ferretdb-service"

+ 6 to create

Do you want to perform this update? yes
Updating (dev)

View in Browser (Ctrl+O):

Type Name Status
+ pulumi:pulumi:Stack ferretdb-pulumi-dev created (42s)
+ ├─ sg-pooling-config created (0.92s)
+ ├─ createuserdb created (0.36s)
+ ├─ stackgres-cluster created (0.86s)
+ ├─ kubernetes:apps/v1:Deployment ferretdb-deployment created (22s)
+ └─ kubernetes:core/v1:Service ferretdb-service created (10s)

ferretdb_service_ip: "ferretdb-service"

+ 6 created

Duration: 44s

The postgres pods might take a few minutes to be ready. To be sure the pods are running, run kubectl get pods -n ferretdb.

% kubectl get pods -n ferretdb
ferretdb-deployment-69bc74d967-2xss7 1/1 Running 0 2m6s
postgres-0 6/6 Running 0 2m5s

Connect via mongosh

Let's launch a temporary mongosh pod in the ferretdb namespace.

kubectl -n ferretdb run mongosh --image=rtsp/mongosh --rm -it -- bash

This should open up a mongosh shell in your terminal, and you can use it to connect to FerretDB.

FerretDB exposes the Postgres database created previously with SGScript and allows you to interact with it as if you were using MongoDB.

Connect using the following format:

mongosh 'mongodb://ferretdb:<password>@<host-address>:27017/ferretdb?authMechanism=PLAIN'

You will need the host address for the FerretDB Service and password credential for the Postgres database.

Run kubectl -n ferretdb get svc to get the address and port exposed by the FerretDB Service ( in the example below):

% kubectl -n ferretdb get svc
ferretdb-service ClusterIP <none> 27017/TCP 11m

You can also access the password by running:

kubectl -n ferretdb get secret createuser --template '{{ printf "%s\n" (.data.sql | base64decode) }}'

Connect to FerretDB:

# mongosh 'mongodb://ferretdb:<password>@<host-address>:27017/ferretdb?authMechanism=PLAIN'
Current Mongosh Log ID: 65d02c968660cd7b3c7ad89e
Connecting to: mongodb://<credentials>@
Using MongoDB: 7.0.42
Using Mongosh: 2.1.4
For mongosh info see:
The server generated these startup warnings when booting
2024-02-17T03:48:39.213Z: Powered by FerretDB v1.19.0 and PostgreSQL 15.5.
2024-02-17T03:48:39.213Z: Please star us on GitHub:
2024-02-17T03:48:39.213Z: The telemetry state is undecided.
2024-02-17T03:48:39.213Z: Read more about FerretDB telemetry and how to opt out at

Awesome! With Pulumi, you've been able to run and deploy FerretDB in a Kubernetes cluster. So you can just go right ahead to run a couple of MongoDB operations.

Insert documents

Let's insert documents showing single-day stock data for a fictional company.

symbol: 'ZTI',
date: new Date('2024-02-17'),
tradingData: {
open: 250.75,
high: 255.5,
low: 248.25,
close: 254.1,
volume: 1200000
metadata: {
analystRating: 'Buy',
sector: 'Technology'
symbol: 'ZTI',
date: new Date('2024-02-18'),
tradingData: {
open: 254.1,
high: 260.0,
low: 253.0,
close: 258.45,
volume: 1500000
metadata: {
analystRating: 'Strong Buy',
sector: 'Technology'

Run db.stocks.find() to see the documents.

Query Document

Find stock data indicating where the volume was greater than 1,200,000.

db.stocks.find({ symbol: 'ZTI', 'tradingData.volume': { $gt: 1200000 } })


_id: ObjectId('65d030d38660cd7b3c7ad8a0'),
symbol: 'ZTI',
date: ISODate('2024-02-18T00:00:00.000Z'),
tradingData: {
open: 254.1,
high: 260,
low: 253,
close: 258.45,
volume: 1500000
metadata: { analystRating: 'Strong Buy', sector: 'Technology' }

You can go ahead and try more MongoDB commands.

View data in Postgres

Since FerretDB adds MongoDB compatibility to your Postgres database, you can view the stored data in your Postgres instance.

Connect to Postgres by running this command:

kubectl -n ferretdb exec -it postgres-0 -c postgres-util -- psql ferretdb

Once you're in, set the search_path to the ferretdb database and then check out the tables in the database. FerretDB stores the data as JSONB.

ferretdb=# SET SEARCH_PATH TO ferretdb;
ferretdb=# \dt
List of relations
Schema | Name | Type | Owner
ferretdb | _ferretdb_database_metadata | table | ferretdb
ferretdb | stocks_5fb3a312 | table | ferretdb
(2 rows)

ferretdb=# SELECT * from stocks_5fb3a312;
{"$s": {"p": {"_id": {"t": "objectId"}, "date": {"t": "date"}, "symbol": {"t": "string"}, "metadata": {"t": "object", "$s": {"p": {"sector": {"t": "string"}, "analystRating": {"t": "string"}}, "$k": ["analystRating", "sector"]}}, "tradingData": {"t": "object", "$s": {"p": {"low": {"t": "int"}, "high": {"t": "int"}, "open": {"t": "double"}, "close": {"t": "double"}, "volume": {"t": "int"}}, "$k": ["open", "high", "low", "close", "volume"]}}}, "$k": ["_id", "symbol", "date", "tradingData", "metadata"]}, "_id": "65d030d38660cd7b3c7ad8a0", "date": 1708214400000, "symbol": "ZTI", "metadata": {"sector": "Technology", "analystRating": "Strong Buy"}, "tradingData": {"low": 253, "high": 260, "open": 254.1, "close": 258.45, "volume": 1500000}}
{"$s": {"p": {"_id": {"t": "objectId"}, "date": {"t": "date"}, "symbol": {"t": "string"}, "metadata": {"t": "object", "$s": {"p": {"sector": {"t": "string"}, "analystRating": {"t": "string"}}, "$k": ["analystRating", "sector"]}}, "financials": {"t": "object", "$s": {"p": {"dividendPayout": {"t": "double"}}, "$k": ["dividendPayout"]}}, "tradingData": {"t": "object", "$s": {"p": {"low": {"t": "double"}, "high": {"t": "double"}, "open": {"t": "double"}, "close": {"t": "double"}, "volume": {"t": "int"}}, "$k": ["open", "high", "low", "close", "volume"]}}}, "$k": ["_id", "symbol", "date", "tradingData", "metadata", "financials"]}, "_id": "65d030d38660cd7b3c7ad89f", "date": 1708128000000, "symbol": "ZTI", "metadata": {"sector": "Technology", "analystRating": "Buy"}, "financials": {"dividendPayout": 0.5}, "tradingData": {"low": 248.25, "high": 255.5, "open": 250.75, "close": 254.1, "volume": 1200000}}
(2 rows)

Clean up

Pulumi provides a way to clean up and de-provision all the resources created with Pulumi from your project's directory. Then delete the cluster along with other resources created and managed outside of Pulumi.

pulumi destroy
minikube delete


So far, you've been able to leverage the power of Pulumi for infrastructure as code, to run, deploy, and manage a scalable FerretDB database in Kubernetes. Pulumi orchestrates all the resources using Python, deploys a Postgres database using StackGres, and adds MongoDB compatibility to it with FerretDB. But you can still choose to use any other language of your choice.

FerretDB, due to its open-source nature, offers complete control over your data without any fear of vendor lock-in.

To get started with FerretDB, check out our quickstart guide.