FerretDB Operator

A Kubernetes operator for managing FerretDB instances.

FerretDB is a truly open-source MongoDB alternative that acts as a proxy between MongoDB clients and PostgreSQL databases, translating MongoDB wire protocol queries to SQL.

Overview

This operator provides a declarative way to manage FerretDB instances in Kubernetes. It handles:

• Deployment Management: Automatic creation and management of FerretDB Deployments
• Service Management: Automatic creation of Kubernetes Services for FerretDB
• Configuration Management: Automatic ConfigMap generation for FerretDB settings
• Status Tracking: Real-time status updates for FerretDB instances

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    FerretDB Operator                        │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              FerretDB Controller                     │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │   │
│  │  │ Deployment  │  │   Service   │  │ ConfigMap  │ │   │
│  │  │  Reconciler │  │  Reconciler │  │ Reconciler │ │   │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬─────┘ │   │
│  └─────────┼─────────────────┼────────────────┼────────┘   │
└────────────┼─────────────────┼────────────────┼─────────────┘
             │                 │                │
             ▼                 ▼                ▼
      ┌──────────┐    ┌─────────────┐   ┌──────────┐
      │Deployment │    │  Service    │   │ConfigMap │
      └────┬─────┘    └──────┬──────┘   └────┬─────┘
           │                  │                │
           ▼                  ▼                ▼
┌──────────────────────────────────────────────────────────────┐
│                     Kubernetes Cluster                        │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐   │
│  │                   FerretDB Pod                          │   │
│  │  ┌─────────────────────────────────────────────────┐   │   │
│  │  │              FerretDB Container                  │   │   │
│  │  │  MongoDB Protocol ──────────────────────────────│───│───┐
│  │  │                  :27017                          │   │   │
│  │  └─────────────────────────────────────────────────┘   │   │
│  └────────────────────────────────────────────────────────┘   │
│                            │                                 │
└────────────────────────────┼─────────────────────────────────┘
                             │
                             ▼
                    ┌───────────────┐
                    │   PostgreSQL  │
                    │   Database    │
                    └───────────────┘

Installation

Prerequisites

• Kubernetes cluster (v1.28+)
• kubectl configured
• Docker (for building images)

Quick Start

1. Clone the repository:

git clone https://github.com/ferretdb/ferretdb-operator.git
cd ferretdb-operator

2. Build and push the operator image:

export IMG=ghcr.io/ferretdb/ferretdb-operator:v0.1.0
make docker-build docker-push IMG=$IMG

3. Deploy the operator:

make deploy IMG=$IMG

4. Create a FerretDB instance:

kubectl apply -f config/samples/ferretdb_v1alpha1_ferretdb.yaml

Usage

Creating a FerretDB Instance

Create a FerretDB custom resource:

apiVersion: ferretdb.io/v1alpha1
kind: FerretDB
metadata:
  name: my-ferretdb
  namespace: default
spec:
  # FerretDB container image
  image: ghcr.io/ferretdb/ferretdb:latest
  
  # Number of replicas
  replicas: 1
  
  # PostgreSQL backend configuration
  postgresql:
    url: postgres://user:password@postgres.default.svc.cluster.local:5432/ferretdb
    # Optional: Secret containing the PostgreSQL password
    # secretRef: postgres-secret
  
  # MongoDB protocol port (default: 27017)
  port: 27017
  
  # Backend handler: pg or sqlite
  handler: pg
  
  # Enable authentication (default: true)
  auth: true
  
  # Log level (default: info)
  logLevel: info
  
  # Telemetry (default: undecided)
  telemetry: "false"

Configuration Options

Field	Type	Default	Description
image	string	ghcr.io/ferretdb/ferretdb:latest	FerretDB container image
replicas	int32	1	Number of replicas
postgresql.url	string	Required	PostgreSQL connection URL
postgresql.secretRef	string	-	Secret containing password
port	int32	27017	MongoDB protocol port
debugPort	int32	8088	Debug/metrics HTTP port
handler	string	pg	Backend handler (pg or sqlite)
auth	bool	true	Enable authentication
logLevel	string	info	Log level
telemetry	string	undecided	Telemetry setting
serviceType	string	ClusterIP	Service type

Checking Status

# Get all FerretDB instances
kubectl get ferretdb

# Get specific instance status
kubectl get ferretdb my-ferretdb -o yaml

# Describe instance
kubectl describe ferretdb my-ferretdb

# View pods
kubectl get pods -l ferretdb.io/service=my-ferretdb

# View logs
kubectl logs -l ferretdb.io/service=my-ferretdb -c ferretdb

Scaling

# Scale via kubectl
kubectl scale ferretdb my-ferretdb --replicas=3

# Or update the spec
kubectl patch ferretdb my-ferretdb -p '{"spec":{"replicas":3}}' --type=merge

TLS Configuration

To enable TLS:

spec:
  tlsCertPath: /etc/ferretdb/tls/tls.crt
  tlsKeyPath: /etc/ferretdb/tls/tls.key
  tlsCAPath: /etc/ferretdb/tls/ca.crt

Resource Limits

spec:
  resources:
    limits:
      cpu: "2"
      memory: "2Gi"
    requests:
      cpu: "100m"
      memory: "256Mi"

Development

Prerequisites

• Go 1.22+
• Docker
• Kubernetes cluster (kind, k3s, or real cluster)

Building

# Build the operator
make build

# Run tests
make test

Running Locally

# Run operator locally
make run

# In another terminal, create a sample FerretDB
kubectl apply -f config/samples/ferretdb_v1alpha1_ferretdb.yaml

Project Structure

ferretdb-operator/
├── api/v1alpha1/           # API types
│   ├── ferretdb_types.go   # FerretDB CRD types
│   └── ferretdb_webhook.go # Webhook logic
├── controllers/            # Controller logic
│   └── ferretdb_controller.go
├── config/                 # Kubernetes manifests
│   ├── crd/              # CRD definitions
│   ├── rbac/             # RBAC manifests
│   ├── manager/          # Manager deployment
│   ├── samples/          # Example resources
│   └── default/          # Kustomize overlay
├── hack/                  # Utility scripts
└── main.go               # Entry point

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

Licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Related Links

• FerretDB - The main FerretDB project
• Operator SDK - Operator SDK
• Kubebuilder - Kubernetes API patterns