Frappe Helm Charts

The Frappe/ERPNext Helm Chart is designed to deploy a frappe-bench-like environment on Kubernetes. It orchestrates various components including web servers, workers, schedulers, and background jobs to provide a full Frappe or ERPNext stack.

Key architectural components include:

• Web & Proxy: gunicorn (application server), nginx (static assets and reverse proxy), and socketio (real-time communication).
• Background Processing: scheduler for scheduled tasks, and three types of workers: worker-d (default), worker-l (long), and worker-s (short).
• Storage: Persistent Volume Claims (PVCs) for erpnext (sites and config) and erpnext-logs (logs).
• Networking: Supports both standard ingress and Gateway API httproute resources, which can be dynamically generated via helm template.
• Scaling: HorizontalPodAutoscalers (HPA) are provided for gunicorn, nginx, socketio, and all worker types.

For a simple evaluation setup, you can create an in-cluster NFS server to provide a storage class with ReadWriteMany (RWX) capabilities. This is required for the ERPNext deployment.

1. Set up the NFS Provisioner:

   • Create an nfs namespace.
   • Add the nfs-ganesha-server-and-external-provisioner repository.
   • Install the provisioner with vers=4.1 mount options and persistence enabled.

2. Install ERPNext:

   • Create an erpnext namespace.
   • Add the frappe Helm repository.
   • Install the frappe-bench release using the nfs storage class for the worker persistence and enabling the MariaDB StatefulSet.

# 1. Setup NFS Provisioner
kubectl create namespace nfs
helm repo add nfs-ganesha-server-and-external-provisioner https://kubernetes-sigs.github.io/nfs-ganesha-server-and-external-provisioner
helm upgrade --install -n nfs in-cluster nfs-ganesha-server-and-external-provisioner/nfs-server-provisioner --set 'storageClass.mountOptions={vers=4.1}' --set persistence.enabled=true --set persistence.size=8Gi

# 2. Install ERPNext
kubectl create namespace erpnext
helm repo add frappe https://helm.erpnext.com
helm upgrade --install frappe-bench --namespace erpnext frappe/erpnext --set persistence.worker.storageClass=nfs --set mariadb-sts.enabled=true

The Helm chart includes a suite of Kubernetes Jobs to perform administrative tasks on your Frappe/ERPNext sites. These jobs allow you to manage the lifecycle of sites, migrations, and backups directly from the cluster.

Site Lifecycle & Configuration

• create-site: Create a new site.
• create-multiple-sites: Create multiple new sites.
• drop-site: Drop an existing site.
• drop-multiple-sites: Drop multiple existing sites.
• bench-conf: Configure database host, Redis hosts, and SocketIO port.
• vol-fix: Fix volume permissions by changing uid and gid to 1000:1000.

Maintenance & Backups

• migrate: Migrate an existing site.
• migrate-multiple-sites: Migrate multiple existing sites.
• backup-push: Backup an existing site and optionally push it to S3.
• backup-multiple-sites: Backup multiple existing sites.
• clear-cache: Clear the cache (typically used after an upgrade).
• custom: Run custom additional commands and configurations.

In Stage 1, you upgrade your Helm release to provision the new built-in StatefulSet while keeping the old Bitnami database active.

1. Create a Full Backup

Before proceeding, create and verify a complete backup of your site(s) using the built-in backup job:

# Replace <release-name> and <your-site-name> with your current values
helm template <release-name> frappe/erpnext \
  -f your-values.yaml \
  --set jobs.backup.enabled=true \
  --set jobs.backup.siteName=<your-site-name> \
  -s templates/job-backup.yaml | kubectl apply -f -

2. Update values.yaml for Upgrade

Modify your values.yaml to enable the new built-in StatefulSet.

CRITICAL: If you did not previously explicitly set mariadb.enabled: true in your values.yaml, you must add it now to ensure the old database remains active during the migration. Your existing configuration (either mariadb.enabled: true or mariadb-subchart.enabled: true) must remain enabled.

# your-values.yaml

# Keep the classic Bitnami subchart enabled
mariadb:
  enabled: true # Or mariadb-subchart.enabled: true

# Enable the new built-in StatefulSet and configure it
mariadb-sts:
  enabled: true
  persistence:
    # storageClass: "default" # or your preferred storage class
    size: 8Gi

3. Upgrade the Helm Chart

Perform the upgrade to create the new, empty mariadb-sts StatefulSet. Your site will remain operational and connected to the old Bitnami database.

helm upgrade <release-name> frappe/erpnext --version <new-chart-version> -f your-values.yaml

Stage 2 involves moving data from the old database to the new one and switching the application connection. This stage requires downtime.

1. Backup and Restore Data

1. Take a fresh backup from your site while it is still connected to the old database.
2. Retrieve credentials for the new mariadb-sts database from the Kubernetes secret:

   kubectl get secret <release-name>-mariadb-sts -o jsonpath='{.data.mariadb-root-password}' | base64 -d

3. Restore the backup into the new database using bench restore from within a pod. Point the command to the new database service (<release-name>-mariadb-sts).

2. Update values.yaml for Switchover

Modify your values.yaml to disable the old Bitnami subchart. This triggers the configure job to update common_site_config.json to point to the new database.

# your-values.yaml

# Disable the classic Bitnami subchart
mariadb:
  enabled: false
mariadb-subchart:
  enabled: false

# Keep the new built-in StatefulSet enabled
mariadb-sts:
  enabled: true
  persistence:
    # storageClass: "default"
    size: 8Gi

3. Final Helm Upgrade

Run the final upgrade to delete the old Bitnami deployment, update the database host, and restart application pods.

helm upgrade <release-name> frappe/erpnext --version <new-chart-version> -f your-values.yaml

# Retrieve credentials for the new database
kubectl get secret <release-name>-mariadb-sts -o jsonpath='{.data.mariadb-root-password}' | base64 -d

# Example bench restore command from within a pod
bench --site <your-site-name> restore /path/to/your/backup.sql \
  --with-private-files /path/to/your/private-files.tar \
  --with-public-files /path/to/your/public-files.tar \
  --db-host <release-name>-mariadb-sts \
  --db-port 3306 \
  --db-root-username root \
  --db-root-password <password-from-secret

By default, the chart configures service hosts automatically based on the Helm release name. To use external databases (like AWS RDS) or external Redis instances, disable the in-cluster components and provide the external connection strings.

Configuration:

# Disable in-cluster databases and caches
mariadb-sts:
  enabled: false
valkey-cache:
  enabled: false
valkey-queue:
  enabled: false

# Configure external services
dbHost: "db-instance.123456789012.us-east-1.rds.amazonaws.com"
dbPort: 3306

externalRedis:
  cache: "redis://redis-cache.7abc2d.0001.usw2.cache.amazonaws.com:6379"
  queue: "redis://redis-queue.7abc2d.0001.usw2.cache.amazonaws.com:6379"

jobs:
  configure:
    enabled: true

*Note: If jobs.configure.fixVolume is set to true, the job runs as root to change file/directory ownership in the volume.

Execution:

1. Generate the YAML:

helm template frappe-bench -n erpnext frappe/erpnext -f custom-values.yaml -s templates/job-configure-bench.yaml > job-configure-bench.yaml

2. Apply the resource:

kubectl apply -f job-configure-bench.yaml