Managing Frappe and ERPNext on Kubernetes with Frappe Operator

Frappe Cloud
1

If you’re running Frappe in a Kubernetes environment, there’s a fair bit of work involved in setting things up properly — wiring up databases, managing site creation, configuring workers, and keeping everything in sync as you scale. Frappe Operator is a Kubernetes operator that handles this by letting you declare what you want and leaving the reconciliation to Kubernetes.

This post walks through what Frappe Operator is, how it works, and when you’d want to use it.

What is a Kubernetes Operator?

A Kubernetes operator extends the Kubernetes API with custom resources and a controller that watches those resources and acts on them. Instead of running imperative commands to set things up, you write a YAML manifest describing the desired state, and the operator continuously works to match reality to that description.

Frappe Operator does exactly this for Frappe deployments — it introduces Frappe-aware custom resources and manages the lifecycle of benches, sites, backups, and jobs on your behalf.

The custom resources

Frappe Operator adds four custom resource types to your cluster:

FrappeBench — represents the shared infrastructure that one or more Frappe sites run on. This includes the nginx frontend, background workers, Redis, and the app images. Think of it as the platform layer that sites share.

FrappeSite — represents an individual Frappe site. Each site gets its own database, its own credentials (auto-generated and stored as Kubernetes secrets), and its own set of installed apps.

SiteBackup — defines a backup job for a site. Supports one-time and scheduled (cron-based) backups, with options for file inclusion, compression, and retention.

SiteJob — runs an arbitrary bench command against a site as a Kubernetes Job, without needing to exec into a pod.

Installing the operator

The recommended way is via Helm:

helm repo add frappe-operator https://vyogotech.github.io/frappe-operator/helm-repo
helm install frappe-operator frappe-operator/frappe-operator \
  --namespace frappe-operator-system \
  --create-namespace

Or with kubectl directly:

kubectl apply -f https://github.com/vyogotech/frappe-operator/releases/latest/download/install.yaml

Prerequisites: Kubernetes 1.19+, at least 2 CPU cores and 4GB RAM. For production you’ll also want an ingress controller, cert-manager for TLS, and dynamic storage provisioning.

Deploying your first site

Once the operator is running, deploying a Frappe site looks like this:

# 1. Create a MariaDB instance
kubectl apply -f examples/mariadb-shared-instance.yaml

# 2. Create a bench (shared infrastructure)
kubectl apply -f examples/basic-bench.yaml

# 3. Create a site on that bench
kubectl apply -f examples/basic-site.yaml

# 4. Watch the resources come up
kubectl get frappebench,frappesite -w

# 5. Retrieve the auto-generated admin password
kubectl get secret basic-site-admin -o jsonpath='{.data.password}' | base64 -d

# 6. Access the site locally
kubectl port-forward svc/basic-bench-nginx 8080:8080
# Open http://localhost:8080

The operator handles site creation, database provisioning, credential generation, and app installation — all triggered by applying those manifests.

Features worth knowing about

Multi-tenancy. A single FrappeBench can serve multiple FrappeSite resources. Each site is isolated at the database level with its own credentials, which makes this pattern practical for running many tenant sites on shared infrastructure.

Site-specific app installation. You can specify which apps to install per site in the FrappeSite manifest. If an app fails to install, the operator degrades gracefully rather than failing the whole site.

Autoscaling. Worker scaling is supported through KEDA (queue-length-based scaling) or standard HPA. Scale-to-zero is also supported, useful for non-production environments to reduce resource usage when idle.

Zero-downtime updates. Bench and site updates use rolling update strategies, so sites stay available during upgrades.

Automated backups. The SiteBackup resource lets you schedule backups with a cron expression and configure retention, file inclusion, and output paths — all declaratively.

External database support. The operator supports connecting to external databases like RDS or Cloud SQL, so you’re not limited to in-cluster MariaDB.

OpenShift compatibility. The operator is tested against OpenShift’s restricted-v2 security context constraints. There is a dedicated OpenShift installation guide in the docs.

Multi-architecture. Images are available for both AMD64 and ARM64.

When to use it

Frappe Operator is most useful when:

  • You’re already running Kubernetes and want a consistent, declarative way to manage Frappe deployments

  • You need to run multiple Frappe sites on shared infrastructure

  • You want Kubernetes-native lifecycle management — scaling, updates, backups — without writing custom automation around it

  • You’re running Frappe as a managed service for multiple teams or customers

If you just need a quick local environment for development or trialling ERPNext, Frappista is the simpler starting point. Frappe Operator is aimed at production and multi-site scenarios on Kubernetes.

Resources

:point_right: github.com/vyogotech/frappe-operator

Happy to answer questions below. If you run into something not covered in the docs, feel free to open a discussion on GitHub.

1 Like