Deploying ERPNext on Kubernetes with the frappe/helm chart: when it fits
Choose the Kubernetes route when a platform team already runs production clusters, has the tooling for them (GitOps, monitoring, backup, ingress, secrets) and wants ERPNext to run alongside other workloads under the same controls. The frappe/helm chart deploys ERPNext as a set of Kubernetes objects: Deployments for the web tier, socket.io and background workers, plus Jobs for site creation and migrations. It expects you to bring your own MariaDB and Redis, and it needs shared storage that multiple pods can mount at once. ERPNext itself is licensed under GPL-3.0, while the underlying Frappe Framework is MIT-licensed, so the chart carries no licensing cost beyond the infrastructure you run. Confirm the chart's current values and supported ERPNext versions in the chart repository before you pin anything, because the chart tracks Frappe releases on its own schedule.
The chart is a deployment pattern, not a managed service. Nobody upgrades the site, rotates the database credentials, restores a backup or patches the base images on your behalf. Your team owns the Helm values, the container image build (if you use custom apps), the Kubernetes version and the surrounding platform. If that ownership is not already staffed, a single-server route is usually easier to operate: the frappe_docker Compose setup, the bench production install on Ubuntu, or the Easy Install script all keep fewer moving parts. Frappe Cloud is the option when you want the vendor to run the hosting. Compare these alternatives against your own staffing before committing to Kubernetes, not after the first outage.
Before you start, answer three questions in writing. Does your cluster offer a storage class that supports ReadWriteMany for the shared sites volume, and who supports it when it fails? Will MariaDB and Redis be managed outside the cluster, and who restores them? And does your change process cover Helm upgrades that run database migrations against a live site? If any answer is unclear, a pilot on a non-production cluster will expose the gaps faster than design review. Ask a partner to write the scope against those answers, so the work, the handover and the recurring operations are agreed before the first release.
Chart configuration choices and when each one fits
This table compares the main frappe/helm chart configuration choices and what each one commits your team to run. Read each row as a decision: the option that fits a small or fast-moving team is often different from the one a regulated team with its own database and storage platform will choose. The main takeaway is that bundled components lower the first install effort but move ongoing backup, upgrade and failover work onto the same cluster that runs ERPNext.
| Decision | When it fits | What it commits your team to operate |
|---|---|---|
| Bundled MariaDB | Pilot, test or small single-company environments where the chart's database is acceptable and the team accepts its backup scope | Backups, restores, patching, storage expansion and failover for the database pod, which the chart does not treat as a managed database service |
| External MariaDB | Organizations with an existing database platform, DBA practice and tested backup and restore routines | Provisioning the database, network access, credentials, parameter tuning for ERPNext and the same monitoring and recovery standards as other production databases |
| Bundled Redis | Non-production environments or workloads where cache and queue data loss on restart is acceptable | Persistence settings, memory limits and the operational knowledge to recover queued background jobs after a Redis failure |
| External Redis | Teams that already run a managed or shared Redis service with monitoring, eviction policy and failover | Network policy, authentication settings in the chart values, capacity planning for the queue and cache, and coordination with the platform team |
| ReadWriteMany storage class | Multi-pod deployments where web, worker and scheduler pods must share the same site files | Confirming that the chosen storage class supports ReadWriteMany, its latency and throughput limits, snapshot and backup coverage, and vendor support for the cluster version |
| Ingress controller and TLS handling | Clusters with a standard ingress controller and certificate manager already in use | Certificate issuance and renewal, ingress class and annotation maintenance, and upgrades of the controller alongside the cluster |
| Fixed worker replicas | Stable, predictable background job volume such as scheduled reports, batch imports and nightly tasks | Right-sizing replica counts by observation, since over- or under-provisioning is found only through queue depth and job timing |
| Autoscaled worker replicas | Spiky job load, such as month-end close or large imports, where extra capacity is needed for a limited window | Metrics for queue depth or resource use, scaling thresholds that do not conflict with long-running jobs, and testing of scale-down behavior on in-flight work |
Why ReadWriteMany storage and an external MariaDB change the design
The frappe/helm chart runs several ERPNext pods that must read and write the same site files, and it leaves the database and cache choices to you. Each card below is a decision that shapes the rest of the deployment, from the storage class to who restores data after a failure.
Shared site files need ReadWriteMany
ERPNext web, worker and scheduler pods mount the same sites directory, which holds uploaded attachments, private files and generated files. A volume that allows only one node to mount it at a time will not serve that pattern. Confirm which storage class in your cluster offers ReadWriteMany, whether it is NFS-backed, a CSI driver or a managed file service, and that the chart's volume settings match it before you install.
Storage performance must be tested
A ReadWriteMany volume can meet the access mode and still be slow for ERPNext, especially for many small file reads during report generation and attachment handling. Ask your provider for measured latency and throughput at the sizes you expect, and run a load test with real attachments before go-live. Treat the figures from a vendor brochure as a starting point, not as proof.
Database and cache run outside the chart
Most teams point the chart at an external MariaDB service and an external Redis instead of the bundled ones. A managed or separately operated database gives you its own backup schedule, restore tests, patching window and sizing decisions, and it keeps the Helm release replaceable without touching business data. Confirm the MariaDB version and character set requirements for your ERPNext release with the Frappe documentation before provisioning.
Backups are your responsibility
Moving the database out of the chart does not move the backup duty to the chart. Your team must schedule database dumps, back up the shared files volume, and test restores of both together so they match the same point in time. Document who owns each backup job, where copies are stored and how long they are kept, since no default retention period is supplied for this setup.
Connection and access settings
The external database needs a dedicated account with the privileges ERPNext requires, reachable from the cluster network and restricted to the namespace that runs ERPNext. Store its credentials as Kubernetes Secrets and confirm that encryption at rest is configured for etcd, because Secrets are stored unencrypted there by default. Review who can read those Secrets through RBAC.
Agree responsibilities in writing
Storage, database, cache and backup work sit across the platform team, the database team and the ERPNext owner. Before the build starts, record in the scope who provisions each service, who holds the restore runbook, and who responds when storage latency rises. A clear split prevents gaps during an incident and makes a fixed-scope quote easier to compare.
Setup sequence for ERPNext on Kubernetes
This sequence takes a cluster from a supported Kubernetes version to a verified ERPNext site, with each step closed by a check so that storage, database, image, configuration and routing problems surface before users log in. It is the order we would expect a platform team to follow when running the frappe/helm chart against infrastructure they control.
Confirm cluster version and support window
Your platform team confirms that the cluster runs a Kubernetes minor version still maintained by the project, using the releases page and the version skew policy as the reference. Check the ERPNext version you plan to run against Frappe's supported versions page, because ERPNext 14 has reached end of life and only listed versions are covered by Frappe warranty terms. Confirm that the kubectl client and kube-apiserver versions are within the allowed skew before any chart is installed. Done when the cluster version, the ERPNext major version and the support dates are written down with a named owner and an agreed upgrade date.
Provision shared storage and external services
Provision a ReadWriteMany volume that all ERPNext pods can mount for the site files, and a MariaDB server and Redis instance outside the chart so that their lifecycle, backups and sizing are owned separately. Ask your storage team to confirm that the chosen storage class supports ReadWriteMany under your load, since many chart pods share the same files. Create credentials for the database and Redis with least-privilege access, and store them as Kubernetes Secrets encrypted at rest or in an external secret store. Done when a test pod can read and write the shared volume from two nodes and can connect to both the database and Redis with the chosen credentials.
Build the custom image with required apps
Build an image that contains the ERPNext version you selected along with every companion app your sites need, such as Frappe HR or India Compliance, pinned to exact tags or commits. Your CI pipeline should run the build from a reviewed application list, push the image to a registry your cluster can pull from, and keep the tag immutable for each release. Do not install apps into running pods, because a restart would lose them and the site would not match the image under review. Done when the image starts locally, lists the expected apps, and its digest is recorded in the change record for this environment.
Configure values for the chart
Set the chart values for your image repository and tag, the external MariaDB and Redis endpoints, the shared volume claim, resource requests for each worker queue, and the ingress host. Reference secrets by name rather than writing passwords into the values file, and keep the file in version control with review. Render the manifests with a template command and check that each deployment, job and service points at the intended endpoints and that no default database or Redis pod is created. Done when the rendered output matches the reviewed design and a diff against the previous release shows only the changes you expected.
Run the site creation job
Run the configurator and site creation jobs that the chart provides, which create the site on the external database and install the apps listed in the image. Watch the job logs and confirm that the migration completed without errors, and check that the site is registered with the expected name. Confirm that the database user was created with the privileges the job needs and no broader ones. Done when the job reports success, the site appears in the bench site list inside a web pod, and a second run of the job is idempotent without changing data.
Configure ingress and TLS
Create the ingress for the site hostname, attach a certificate from your certificate authority or cert-manager, and confirm that the controller forwards to the frontend service with the correct host header. Make sure the ingress passes websocket upgrade traffic, because real-time updates in ERPNext depend on Socket.io. Check that the Frappe site configuration uses the public HTTPS address, so generated links and redirects do not point at internal names. Done when the hostname resolves, the certificate chain validates from a client outside the cluster, and a browser completes a login over HTTPS without mixed-content warnings.
Verify login, background jobs and scheduler
Sign in as an administrator and open a document, then confirm that a background job such as a report or an email queued from the desk completes in the worker pods. Check that the scheduler job is running and that scheduled events fire on their expected cadence, since a stopped scheduler silently stops recurring tasks. Review worker and scheduler logs for errors, and confirm that queue depths return to normal after the test. Done when login, a queued background task, a scheduled event and a socket update all work from the public address, and the results are recorded as the baseline for monitoring and the upgrade runbook.
Scaling workers, web pods and the scheduler
Web pods serve the ERPNext interface and API requests through gunicorn workers, and socket.io pods handle real-time updates to open browser sessions. Both are stateless from Kubernetes' point of view, so they are the most natural candidates for horizontal scaling behind the ingress. Scaling them adds request capacity, but it does not speed up background jobs or reports that run in the queue workers.
- Request-driven signals: Watch response times, error rates and CPU on web pods during month-end and peak data entry, since these reflect the load that replicas absorb.
- Socket.io sizing: Keep socket.io replicas separate in your planning, because a small number of real-time connections can be handled by fewer pods than the web tier needs.
- Session affinity: Confirm with your ingress controller how it routes socket.io upgrades and whether sticky sessions are required for your deployment.
- Connection budget: Each web replica opens database connections, so every added replica raises pressure on MariaDB.
- Resource requests: Set CPU and memory requests so the scheduler can place pods predictably and autoscaling decisions use accurate baselines.
Before changing replica counts, check the chart's values for web and socket.io and confirm the autoscaling method you plan to use with your platform team.
Queue workers run the asynchronous work in ERPNext, such as document events that are processed in the background, report generation, email sending and bulk operations. The chart separates workers by queue type, so the short, default and long queues can be sized independently. Scale these workers when queues build up, not when the web tier is busy, because a backlog is the signal that work is waiting.
- Queue-specific scaling: Add replicas to the queue that is backing up. Long queue workers often handle reports and imports, so they need different sizing from short queue workers.
- Backlog as the trigger: Use queue length or job wait time from your monitoring as the scaling input, and confirm how your chosen autoscaler can read that metric.
- Scale-down behavior: Workers that are mid-job can be interrupted when pods terminate, so review termination grace periods and whether long jobs can resume safely.
- Memory limits: Long-running jobs can grow memory use, so set limits with headroom and watch for restarts caused by out-of-memory events.
- Ordering assumptions: Parallel workers can process jobs out of the order users expect, so test workflows that depend on sequence.
Run a representative batch import or report during load testing and observe how long jobs wait before a worker picks them up.
The scheduler triggers periodic ERPNext jobs, such as recurring tasks and scheduled reports. Its purpose is to create jobs at fixed intervals, so running more than one scheduler instance can enqueue the same job more than once. For that reason, the scheduler should run as a single instance, while the workers that execute its jobs can scale.
- One replica only: Keep the scheduler deployment at a single replica and avoid autoscaling it, even when the rest of the release scales.
- Restart behavior: Confirm that Kubernetes restarts the scheduler pod quickly after a node failure, since scheduled jobs will pause until it returns.
- Rollout strategy: Review how the deployment strategy handles upgrades so that two scheduler instances do not run together during a rollout.
- Job overlap: Check which scheduled jobs are heavy, and whether they might still be running when the next interval starts.
- Ownership in documentation: Record which component owns scheduled jobs in your runbook so on-call staff know where to look when a job does not run.
Ask the chart maintainers and your ERPNext version's documentation how the scheduler is expected to be deployed for the release you are using.
Scaling web pods and workers does not add database or cache capacity by itself. Every web replica, worker and scheduler connects to MariaDB and Redis, so the total number of connections and the Redis memory and throughput become the shared ceiling. Many scaling problems that appear to be application problems start here, and they are visible only when the components are measured together.
- Connection totals: Calculate the maximum number of database connections from replica counts multiplied by per-pod settings, and compare the result with the limit configured on your external MariaDB service.
- Redis roles: Redis carries both cache and queue traffic, so heavy queue activity can affect cache latency for web users.
- Redis memory: Monitor memory use and eviction behavior, because queued jobs must not be dropped under memory pressure.
- Database sizing: Watch slow queries and lock waits during peak batch work, since more workers can increase contention rather than throughput.
- Ceiling tests: Increase replicas in steps during load testing and stop when database latency or queue wait times stop improving.
Before approving a replica plan, ask your database and Redis providers for their connection limits, memory limits and failover behavior, and load test the full configuration.
Security controls for ERPNext on a shared cluster
An ERPNext release on Kubernetes touches cluster secrets, the etcd data store, pod permissions, network paths and the way users sign in. Each control below closes a different gap, and they only hold together when the namespace, the database and the identity provider are designed as one system. Work through them before the first production site goes live.
Secrets for database and admin credentials
The chart needs the MariaDB root or site database credentials and the Administrator password available to its jobs and pods. Keep these in Kubernetes Secrets created outside the Helm values file, so they never land in version control or a rendered manifest copied into a ticket. Confirm which secret keys the chart version you deploy reads, and rotate the Administrator password after the first login. The Kubernetes secrets guidance also notes that Secrets are stored unencrypted in etcd by default, which is the next control.
Encryption at rest for etcd
Kubernetes Secrets sit in etcd, and etcd snapshots carry them too. Configure encryption at rest on the API server so Secret objects are encrypted before they are written, and confirm that etcd backups inherit the same protection. If your cluster runs a managed control plane, ask the provider how encryption keys are stored and rotated, and who can access them. Verify encryption is active by reading a test Secret directly from etcd after the change.
Least-privilege RBAC for the release
Bind the ERPNext release's service accounts only to the verbs they need in the ERPNext namespace. The migration and configuration jobs usually need more access than the web and worker pods, so give them their own accounts rather than sharing a broad one. Restrict list and watch on Secrets, since those verbs expose every value in a namespace. Review bindings with kubectl auth can-i --list for each service account after every chart upgrade.
Pod Security Standards for the namespace
Apply the Pod Security Standards to the ERPNext namespace using the restricted level where the chart allows it, and the baseline level where a component needs more. Check each pod for privilege escalation, host networking and writable root filesystems, and document any exception with its reason. Because the chart runs database and cache dependencies alongside the application, test every workload against the enforced level in a staging namespace first, not in production.
Network policies between pods and the database
On a shared cluster, any pod can reach the MariaDB and Redis endpoints unless a network policy says otherwise. Allow ingress to the database only from ERPNext web, worker, scheduler and job pods, and allow Redis only from the same set. Deny other namespaces by default. If MariaDB runs outside the cluster, write the egress rule against the database address and port your team confirms with the network owner. Your CNI plugin must enforce network policies, so confirm that before relying on them.
LDAP or Social Login Key for sign-in
Decide early how users sign in, because local ERPNext passwords are the weakest option for a shared deployment. LDAP login can use Active Directory or OpenLDAP with SSL or TLS options, and ERPNext maps LDAP groups to roles at each login. Social Login Key can use Google, Microsoft, GitHub, Facebook, Frappe or a custom OAuth or OpenID Connect endpoint. Keep the local Administrator account as a break-glass login with a strong password stored in your vault, and confirm which method your identity team will support.
Server Scripts disabled by default
Server Scripts run Python on document events or as API endpoints, which makes them a code execution path inside the application. From version 15 they are disabled by default and must be enabled with the server_script_enabled setting. Keep them disabled unless a reviewed change needs them, and record who enabled them and why. Frappe Cloud public shared benches do not allow Server Scripts, so a team moving from there should plan for custom apps instead.
Keeping the Kubernetes cluster and ERPNext versions in step
Plan the Kubernetes and ERPNext upgrades as two tracks that have to meet at a known-good point. Kubernetes ships roughly three minor releases a year on a cycle of about 14 weeks, and the project maintains only the three most recent minors. Per the Kubernetes releases page, 1.37 is supported until October 28, 2027, 1.36 until June 28, 2027 and 1.35 until February 28, 2027, so a cluster on an older minor is already outside support. The version skew policy sets the order: upgrade kube-apiserver one minor at a time, then kube-controller-manager and kube-scheduler, then kubelets, which may trail the API server by up to three minors. Confirm which minor your managed or distribution control plane supports before you touch the chart.
ERPNext is the tighter constraint. Frappe's supported versions page lists version 14 as end of life since January 31, 2026, so any cluster still running it needs a major upgrade before anything else. Version 15 is planned for support until the end of 2027 and version 16 until the end of 2029. Both supported lines receive frequent minor releases; the releases page shows v16.51.1 and v15.123.0 released within a day of each other in October 2026. Do not chase every tag. Pin the image tag in your values file, test each minor in a non-production namespace with a restored database copy, and promote only after the migrate job completes cleanly. Ask your Frappe support provider or implementation partner which minors they will validate for your apps.
Limits to confirm before committing to Kubernetes
The frappe/helm chart is a workable route to ERPNext on Kubernetes, but several constraints sit outside the chart itself. Confirm them in your environment before you commit budget and architecture, because each one changes the design or the support position.
Chart and image version compatibility
Match the chart version, the ERPNext image tag and the Frappe version to one another before you pin anything. ERPNext v15 and v16 both receive frequent minor releases, so the image you test with should be the image you promote. Ask the team that will run it which tags they will track, how they will test a new tag against your custom apps, and where the pinned values file lives in version control.
Frappe support eligibility
Confirm that the Frappe major version you plan to run is still listed as supported, and check the support status of your chosen version before go-live. Frappe's policy ties warranty coverage to running a listed version and holding a matching Frappe Cloud support plan. Self-hosting on your own cluster is possible without that plan, so decide now whether you need vendor warranty or only community support and internal expertise.
ReadWriteMany storage performance
The chart's shared storage for site files must support ReadWriteMany, so several web and worker pods can read and write the same sites directory. Measure the storage class you plan to use under realistic upload, backup and report load, not only its availability. Ask your storage team whether the class is network file storage with acceptable latency, and how it behaves during node failure and backup windows.
Data import volume limits
Plan data migration as a sequence of batches. The ERPNext Data Import tool accepts CSV, Excel and public Google Sheets files, and the documentation advises importing only a few thousand records at a time. Cluster autoscaling does not shorten a migration that is limited by import batch size, so estimate the number of batches per DocType and schedule them with finance and stock owners before cutover.
Kubernetes distribution conformance
Confirm that the distribution you plan to use is CNCF Certified Kubernetes conformant. Conformance means the distribution supports the required Kubernetes APIs, which the chart depends on for jobs, deployments and services. Also confirm the distribution's supported minor versions, its upgrade path, and whether your team can operate its control plane, etcd backups and node image updates.
Questions teams ask before running ERPNext on Kubernetes
Is running ERPNext on Kubernetes free?
The software is free, but running it on Kubernetes is not. ERPNext and the Frappe Framework are open source, and the pricing page states that self-hosting ERPNext is free. The costs that remain are the cluster itself, persistent storage that supports ReadWriteMany access, a managed or self-run MariaDB and Redis, backups, monitoring, networking and load balancing, and the people who build and operate all of it. Each of these recurs every month, and the largest variable is usually staff time. Ask any partner for a quote that lists each infrastructure component, who pays for it, and which items are one-time versus recurring.
What makes the cost of a Kubernetes deployment go up or down?
Cost moves with the number of users and sites, the data volume, how many workers you run, how demanding your storage and database requirements are, and how many environments you keep (development, test, production, disaster recovery). Your existing platform also matters: a team already running Kubernetes with a storage class, backups and identity in place has far less new work than one starting from nothing. Customizations, custom apps and integrations add build and test effort on top. Ask for the quote to separate platform work from ERPNext work so you can see which part your team already covers.
How long does it take to deploy ERPNext on Kubernetes?
Duration depends mostly on how mature your platform already is. If you have a working cluster, approved storage, a database service and a CI pipeline, the work is mainly chart configuration, secrets, ingress, testing and data migration. If you need to build the cluster, identity integration and backup procedures first, the platform work can take longer than the ERPNext work. No fixed timeline is safe to assume before a written scope exists. Ask for a plan with milestones for platform readiness, a staging environment, data import rehearsals and cutover.
What does our team need to provide before the work starts?
Plan to provide the following:
- A Kubernetes cluster you control, with a version that is still in support, and a namespace and RBAC model for ERPNext
- A storage class that supports ReadWriteMany for the shared site files, plus a backup target
- A MariaDB and Redis plan, either as managed services or self-run components with owners
- DNS names, TLS certificates, ingress controller choice and network policy rules
- Access to identity sources such as LDAP or an OpenID Connect provider, if users must sign in through them
- Named owners for approvals, change windows and on-call escalation
The exact list depends on your environment, so confirm each item during scoping.
Can an internal team deploy ERPNext on Kubernetes without a partner?
Yes, a capable internal platform team can do it, provided it has experience with Kubernetes operations, databases and Frappe's bench and job model. The harder part is ongoing operation: upgrades between ERPNext major versions, scheduler and worker health, database tuning, backup restores and security patching. Be honest about the skills you have in each area. A partner can take on the build, handover documentation and runbooks, and optional support, while your team keeps ownership of the running system.
When do Frappe Cloud support plans matter for warranty coverage?
Frappe Cloud support plans matter when you want warranty coverage from Frappe itself. Frappe's supported versions policy says customers must be on a listed version and subscribed to a matching Frappe Cloud support plan to receive that warranty. Self-hosting on your own Kubernetes cluster does not change the software license, which is GPL-3.0 for ERPNext and MIT for the Frappe Framework, but it does affect whether Frappe's warranty applies. Check the current support versions page before you choose a version, and confirm with Frappe which plan matches your deployment. DeployOpen does not provide that warranty.
Which ERPNext version should we pick for a new Kubernetes deployment?
Pick a version that is still supported for the full life of the project. The supported versions page lists version 14 as end of life since January 31, 2026, with version 15 planned for support until the end of 2027 and version 16 until the end of 2029. Both supported major versions receive frequent minor releases, so plan a regular patch cadence in your change process. Pinning a specific release in the chart values and testing each upgrade in staging keeps the rollout controlled.
What operational work continues after go-live?
Expect recurring work in several areas: applying ERPNext minor releases, keeping the chart and Kubernetes versions in support, monitoring scheduler and worker queues, watching database growth and performance, testing restores from backups, rotating secrets, and reviewing access. Kubernetes releases come about three times per year, so the platform itself also needs regular upgrades. Ask your partner which of these items are included in handover, which are optional retainers, and which remain with your team.
How DeployOpen works on this
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including the cloud accounts, data centers or air-gapped networks you control. For ERPNext on Kubernetes, we start by agreeing on the Helm chart, Kubernetes platform, database and storage model before any cluster change is made.
How we scope
- We confirm the target ERPNext and Frappe version against the supported versions list before any work starts.
- The written scope names the Kubernetes distribution, cluster topology, storage class, ingress and external MariaDB and Redis services.
- We agree which apps, custom images, sites and worker queues are in and out, so the quote follows from defined work.
How we build
- We deploy the frappe/helm chart into a non-production cluster first, then document every value we change from defaults.
- We verify ReadWriteMany storage behavior, job ordering for site creation and migration, and worker scaling under a test load.
- We set up secrets handling, RBAC, encryption at rest for Secrets and network policy to match your security requirements.
How we hand over
- You receive version-pinned values files, manifests or Helm releases, and a runbook covering install, upgrade and rollback steps.
- Backup and restore of the database and site files are tested and documented, with the restore procedure shown to your team.
- Your operators receive a walkthrough of deployments, jobs, scheduler behavior and the monitoring points we configured.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped in writing alongside the initial work.
- Upgrade plans follow the ERPNext release notes and the chart's own changes, with a staging run before production.
- Kubernetes version changes are planned against the upstream version skew policy and the supported release window you run.
