Upgrading ERPNext on Kubernetes: when to move and which path is supported
A platform team should move a self-hosted ERPNext release on Kubernetes when the current version is near or past end of life, or when a feature needs a newer release, and it should take each major step in order, one version at a time. Per Frappe's supported versions page, ERPNext and Frappe Framework version 14 reached end of life on January 31, 2026, version 15 is planned to be supported until the end of 2027, and version 16 until the end of 2029. A cluster still on v14 is therefore outside Frappe's support window, and the choice is usually between landing on v15 or going straight to v16. Confirm the current support dates on the Frappe supported versions page before you fix a target, because the plan depends on them.
The major path is sequential. Each major release is a separate image build, a separate migrate run per site and a separate round of retesting for custom apps and customizations, so a jump from v14 to v16 has to pass through v15 with its own backup and validation. Frequent minor releases are the other half of the plan. Per the ERPNext releases page, v16.51.1 shipped on October 15, 2026 and v15.123.0 on October 14, 2026, so both supported lines move often. Set a regular cadence for bumping the image tag within a supported major version, using a staging cluster with a copy of production data, rather than waiting for an end-of-life deadline to force a large change.
Frappe's warranty coverage does not apply to a self-hosted Kubernetes cluster. Per Frappe's supported versions policy, warranty requires a listed version and a matching Frappe Cloud support plan, so a team running the frappe/helm chart on its own infrastructure carries the upgrade risk itself. Ask your internal owners to confirm which support contract, if any, covers your release, and record the end-of-life dates in your change calendar. The frappe/helm chart supplies the migrate and cache-clearing jobs, but it does not decide which version is safe for your sites.
What changes between versions and what each change asks of your team
This table lists the changes that recur when a new ERPNext release goes through the frappe/helm chart, with the impact of each and the action your team should plan. Read it as a checklist to run before and after every image bump. Release-specific breaking changes are not covered here, so confirm them on the GitHub releases page for your target version before you start.
| Change | Impact | Action needed |
|---|---|---|
| Image tag bump | The release runs new ERPNext and Frappe code against the same database, so the running pods must match the target version. | Pin the image tag in your Helm values to the target release, and confirm the app versions baked into that image on the GitHub releases page. |
| Migrate job per site | The chart runs a migrate job for an existing site or several sites, and schema changes apply only when that job completes for each site. | Review the migrate job for every site on the release, check its logs, and treat a failed job as a stop point before traffic is restored. |
| Cache clearing after upgrade | Cached metadata from the previous version can serve stale DocType definitions and pages after the code changes. | Confirm the chart's cache clear job runs after migration, and test a key form and report on the upgraded site before opening it to users. |
| App version pinning alongside ERPNext | Companion apps must match the ERPNext branch, so a mismatched app can break the migrate job or behave differently after upgrade. | Pin each app's version next to the ERPNext tag in your image build, and record the pairs in version control. |
| Companion apps split in major releases | Apps that move out of ERPNext in a major release, such as Frappe HR, Lending or Payments, must be present in the image or the site loses those features. | Check the release notes for app splits, add the required apps to the image build, and install them before running migrate. |
| Server script default change in version 15 | From version 15, Server Scripts are disabled by default and must be enabled with the server_script_enabled setting, so existing scripts may stop running. | Inventory your Server Scripts, enable the setting only where your policy allows it, and retest each script on a staging site before production. |
| Site-specific configuration | Each site on a shared release carries its own configuration and apps, so one site can pass migration while another fails. | Run the upgrade against a staging copy of every site, and keep a per-site checklist for sign-off. |
What to back up and inventory before touching the chart
A Helm upgrade is quick to start and slow to reverse once a migrate job has changed the schema. The cards below cover what you capture, what you record and where you test, so a failed step can be rolled back to a known state.
Full database and private files backup
Take a complete backup of each site's database and its private files directory before the migrate job runs. The migrate job changes the schema and rewrites records, so a database dump alone is not enough, because attachments and generated files live in the private files area. Confirm you can restore both into a separate namespace and that the restored site loads and shows recent records.
Inventory of custom apps and customizations
List every custom app, the branch or tag each one is pinned to, and every custom field, property setter, client script and server script on each site. Compare this list against the target ERPNext version, since a custom app that has not been updated is the most common reason a migrate job fails. Record the exact commit used so the image can be rebuilt identically.
Server scripts disabled by default
From version 15, Server Scripts are disabled unless the server_script_enabled setting is turned on. A site that relied on them can load after an upgrade with document events silently not firing. Record which sites enable Server Scripts, decide whether the target release keeps that setting, and test one scripted workflow end to end on staging before cutover.
Pinned staging cluster that mirrors production
Run the upgrade first on a staging namespace that uses the same chart version, image tags, database engine, Redis setup and site list as production. Pin every chart and image version so the staging result can be repeated. Ask your platform team to confirm the storage class, ingress and secret handling match production, because differences there often show up only after go-live.
S3 backup push from the chart
The frappe/helm chart includes a backup job that can optionally push backups to S3. Enable it before the upgrade so a pre-upgrade snapshot exists outside the cluster, and confirm the bucket, retention rule and credentials with your storage team. Test a restore from the bucket rather than assuming the copy is usable, since an upload that completes can still produce an unreadable archive.
The upgrade sequence: image, migrate per site, cache and verification
The sequence moves a tested ERPNext image through staging, migrates every site on the release, and promotes to production only after the workers, Socket.io and smoke tests confirm the new version works. Each state-changing step has a rollback point so the team can restore data and revert the image tag if a check fails.
Confirm the target version and app matrix
Before touching the cluster, the platform owner confirms the target ERPNext and Frappe versions, the matching tag for every companion app, and that the chart release supports that combination. Confirm the version against Frappe's supported versions page and check the chart's README at frappe/helm for the values keys used by the release. Record the current image tag, chart version and the list of sites on the release. The output is a written change record that the staging and production runs will follow.
Take a backup and verify it restores
Run the chart's backup job for every site on the release, and push copies off-cluster, either to S3 (if you configure the optional upload) or to storage you control. Treat this as the first rollback point: no state-changing step runs until the backup exists. Confirm the backup files are present, record their checksums, and restore one copy to a scratch database to prove it loads. Your database administrator should own the restore test, since it is the only evidence that rollback will work.
Bump the image tag in staging values
On the staging environment, change the image tag in the Helm values to the target release and apply the release with helm upgrade. The old pods keep serving until the new ones are ready, but the schema has not changed yet. Rollback here is simple: set the previous image tag back and apply the release again, because no site data has been altered. Confirm the new pods pull the expected image digest and that the rollout completes without crash loops.
Run the migrate job for each site
Run the chart's migrate job once per site on the release, so each site's schema and fixtures move to the new version. This step changes data, so it is the point of no return for that site: reverting the image alone will not undo it. Watch the job logs for each site separately, and record which sites completed. If a site fails, stop, keep the job logs, and restore that site's database from the backup taken earlier before retrying.
Clear cache after the migration
Run the chart's cache clearing job after every site has migrated, so stale metadata and cached DocType definitions are not served to users. Confirm the job completes for each site and reload a few forms and reports in a browser to verify they render from the new version. Cache clearing does not change data, so it can be repeated safely if a later check shows stale behavior.
Check Socket.io and worker pods
Confirm the background worker pods, the scheduler and the Socket.io pods are running the new image and are ready. Workers process queued jobs such as emails and reports, and Socket.io carries real-time updates to the desk. Check the worker logs for errors on the first scheduled and queued jobs after the rollout, and confirm a test notification reaches a user. Failing pods here usually mean a mismatched app version, so compare each pod's image tag with the change record.
Run smoke tests on staging
Run a scripted set of checks against each staging site: log in with a test account, open a sales order, post a journal entry in a test company, run a stock ledger report, generate a print format, and send a test email. Compare results with the pre-upgrade baseline recorded in staging. Every failure must be classified as a blocker or an accepted known issue with a named owner. The output is a signed-off test record that promotion depends on.
Promote to production with a fresh backup
Repeat the sequence in production in the same order, starting with a fresh backup taken immediately before the change. Apply the image tag, run the migrate job per site, clear cache, check the pods and run the smoke tests again. If any production check fails, restore the affected sites from the fresh backup and revert the image tag to the previous value, then re-verify. Keep the staging and production change records together so the next upgrade starts from the same evidence.
How multiple sites on one release change the migrate order
When a release holds a single site, the migrate order is simple: the new image goes out, the migrate job runs once against that site, and the cache is cleared afterward. There is no ordering question between sites, so the work is about making sure the one run is complete and verifiable before users return. The frappe/helm chart includes a job to migrate an existing site and a job to clear cache after an upgrade, so both steps map directly onto the rollout. Even here, the migrate run is the step that changes database schema, so it should be treated as the point of no easy return.
- Backup first: take a database and files backup before the image changes, using the chart's backup job or your own snapshot process.
- Single migrate run: run the migrate job once for the site and read its logs to completion rather than assuming success from pod status.
- Cache clear after migrate: run the cache clear job only after the migrate job has finished.
- Smoke test before users: log in, open a few documents and run a report on the upgraded site.
- Rollback plan: know which backup restores the pre-upgrade state and who can run the restore.
Before go-live, confirm with your platform team that the backup restore path has been rehearsed on a copy of the database.
When several sites share one release, each site has its own database and its own migrate state, even though they run the same image. The chart's migrate job can cover multiple sites, but that does not mean one failure is harmless. Each site must be migrated on its own, and a failing site should not stop the others from being checked. Run the migrate step per site, record the result for each, and only then decide whether the rollout is complete. Treat the set of sites as a list of independent units with a shared image rather than one unit.
- One migrate run per site: each site gets its own migrate execution so its result is recorded separately.
- Isolated failures: if one site fails, record it, keep the others moving through verification, and hold only that site back.
- Ordered verification: check the sites in a fixed order your business owners agreed, with the most critical site first.
- Per-site backups: back up each site's database before the upgrade, since a restore for one site must not touch another.
- Shared cache step: confirm whether cache clearing is needed per site or once for the release, and document which you ran.
Confirm with the chart documentation how the migrate and cache jobs are parameterized for multiple sites in your version of the chart.
The hardest case is a release where sites do not share the same app set. Sites on one release can differ in which companion apps are installed or which versions of those apps they run, for example after a site was added later or an app was pinned for a customer. Migrating such sites with one image is risky because the migrate step depends on the apps present in each site. All sites on a release need a compatible app set, so the first task is an inventory of installed apps and their versions for every site, before the image is built.
- Inventory per site: list each site's installed apps and versions before building the release image.
- Matching app set: align every site to one compatible set of apps, or split the release so incompatible sites move separately.
- Install before migrate: companion apps must be present in the image for the migrate step to run cleanly.
- Custom apps retested: custom apps built against the target version need a test migrate on a copy of each site that uses them.
- Stop rule: if a site cannot match the app set, hold it on its current release rather than forcing it through the upgrade.
Ask your Frappe partner or the frappe/helm maintainers to confirm the supported combinations of ERPNext and companion apps for your target version.
Why the frappe/helm chart still needs a human-run test before production
The frappe/helm chart automates the mechanical parts of an upgrade: it includes jobs to migrate an existing site or several sites, to back up and optionally push backups to S3, and to clear cache afterward. What it does not decide is whether the new version is the right target, whether your installed apps support it, or whether your data still means what it did before. Those judgments stay with your team, and a migrate job that completes without errors only tells you the schema change ran, not that accounting, stock and production behave correctly. Before you rely on any job in the chart, read the frappe/helm README for your chart version and confirm which values control image tags, which jobs run by default, and how backup and migrate ordering works.
Treat the migrate job as one step in a rehearsal, not the upgrade itself. Restore a recent production backup into a non-production namespace, point it at the target image, and run the migrate job for each site on the release. Then check the things the chart cannot see: custom apps built against the old framework, Server Scripts and client scripts, print formats, reports, and integrations such as LDAP or Social Login Key. Confirm the apps you run have a branch matching the target ERPNext version, because a successful migrate does not prove a custom app still loads. Record which checks passed and who signed off, so the production run repeats a tested sequence.
Plan the data checks and the rollback before the production window opens. Compare document counts and totals for ledgers, open invoices, stock balances and work orders between the source and the upgraded copy, and decide in advance which differences block go-live. For multi-site releases, run the checks per site, since one site can migrate cleanly while another carries a customization that fails. Confirm that your backup job produced a restorable copy, not just a file, and that the restore path has been exercised. Ask your platform team and any implementation partner to write the acceptance criteria and the rollback trigger down before the rehearsal, so the decision to proceed is made against evidence rather than the chart's job status.
What makes a Kubernetes ERPNext upgrade take longer
This table lists the factors that most often extend an ERPNext upgrade on Kubernetes with the frappe/helm chart, with the reason each one adds work and what to request from your team or a partner before agreeing on scope. Read each row as a question to answer for your own release before the migrate job is scheduled, since most delays come from work discovered late.
| Driver | Why it adds effort | What to ask for |
|---|---|---|
| Number of sites and their data size | Each site on the release runs its own migrate step, so more sites and larger databases lengthen the job and widen the rollback window. | A site inventory with database size per site, and a rehearsal timing on a copy of the largest site. |
| Custom apps and their maintenance state | Every custom app must install and migrate against the target version, and apps without a maintained branch block the image build. | A list of custom apps with their supported Frappe versions, last commit date and owner. |
| Server and client scripts to re-test | Scripts run on document events and can break silently after a version change, and server scripts need explicit enabling from version 15 onward. | An export of all scripts and the test cases that cover each one, with a named owner for sign-off. |
| Frappe HR and other split-out apps | Apps split from ERPNext, such as Frappe HR, must be on a matching branch and installed in the image before migrate runs, or the upgrade stops partway. | The version pairing for each companion app and confirmation that it is in the image build. |
| Storage and database sizing | Upgrade migrations rewrite schemas and generate backups, so limited volume space or database capacity can fail the job or force a restore. | Current volume and database capacity, free space headroom, and the backup target used by the chart's backup job. |
| Number of environments before production | Each environment needs its own image, values file and migrate run, and findings from a test pass must be fixed and retested in the next one. | A written path from development to staging to production, with the environment each site will be tested in before go-live. |
Questions teams ask before upgrading ERPNext on Kubernetes
What drives the cost of upgrading ERPNext on Kubernetes?
The cost is driven by how many sites and custom apps the release carries, how much testing the business needs, and how much cluster work sits underneath the upgrade. Cost has two parts: the upgrade engagement itself, which is usually fixed-scope and quoted in writing, and the infrastructure you run for test and production environments, which you pay your cloud or data center provider for directly. Ask any partner to split the quote into planning, cluster and chart changes, per-site migration and testing, and handover, so you can see which parts scale with your footprint. Whether a one-time project or an ongoing retainer fits depends on how often you expect to upgrade and patch.
How long does an ERPNext upgrade on Kubernetes take?
Duration depends on the number of sites, the size of each database, the number and age of custom apps, and how many version hops separate your current release from the target. Each major step needs a staged migrate run on a copy of production, followed by functional testing of accounting, stock and production flows. Engagements are fixed-scope, so the timeline is agreed in writing before work starts rather than estimated from a generic figure. Ask for the timeline to name the environments, test cycles and sign-off points it depends on.
What does the internal team need to provide for the upgrade?
The upgrade needs people who own the business processes and people who own the platform. Business owners for accounting, stock and production must confirm which reports, print formats and workflows matter and must sign off on test results. Platform engineers need access to the cluster, the Helm release values, the database and object storage used for backups, and the registry where custom images are built. Someone must also own DNS, TLS certificates and any secrets used by the release. Confirm these access paths and approvers before the scope is signed.
Can our own team upgrade ERPNext on Kubernetes without a partner?
Yes, a team with Kubernetes and Frappe experience can run the upgrade internally, provided it has a test environment, a tested backup and a clear rollback plan. The work is mostly disciplined sequencing: bump the image, run the migrate job per site, clear cache and verify each site. The harder parts are custom app compatibility, data checks between hops and the cluster prerequisites that the Frappe chart depends on. A partner adds value when several sites, several custom apps or a regulated change window are involved. Whichever route you take, ask the chart maintainers and your own engineers to review the release notes for each target version first.
Does Frappe Cloud support cover a self-hosted ERPNext cluster?
No. Frappe Cloud support plans apply to sites hosted on Frappe Cloud. Frappe's supported versions policy says customers must be on a listed version and subscribed to a matching Frappe Cloud support plan to receive warranty coverage from Frappe. Self-hosting ERPNext is free under its open-source license, so a self-hosted cluster is supported by your own team, a partner, or a support retainer you arrange separately. Check the support versions page for the currently listed releases before you choose a target version.
How do minor ERPNext updates differ from a major upgrade?
A minor update stays on the same major version and receives fixes and small changes, while a major upgrade moves the site to a new major version with breaking changes, app splits and schema migrations. Frappe publishes frequent minor releases for supported majors, such as v15.123.0 and v16.51.1 released in October 2026, so minor updates are routine maintenance. A major upgrade on Kubernetes needs a new image, a migrate job per site, cache clearing and retesting of customizations. Read the release notes for each major step before you plan the change window.
What does a rollback look like after a failed ERPNext upgrade?
A rollback restores the pre-upgrade state, which means a database backup taken before the migrate job and the previous image tag and chart values. The Helm chart includes backup jobs, and they can push backups to S3 if you configure that option, but you must test restores before the change window rather than assume them. Because a migrate job changes the schema, rolling back the image alone is not enough once the database has moved forward. Ask any partner to show the restore procedure, the time it needs on your data, and who approves the decision to roll back.
What should we ask a partner for in an upgrade quote?
Ask for a written scope that lists the source and target versions, every site and custom app in the upgrade, the environments that will be built and tested, and the acceptance criteria for each site. The quote should name deliverables such as the updated chart values, the migration runbook, the test results and the rollback procedure, plus the handover to your team. Ask how the partner handles the Kubernetes prerequisites, backup verification and secrets, and which items are excluded. Confirm whether support after go-live is included or offered as a separate retainer.
Kubernetes version and control plane readiness before the ERPNext change
Before you change the ERPNext image, confirm that the Kubernetes cluster is on a supported footing and that its own upgrade rules have been followed. The version skew policy requires kube-apiserver to move one minor version at a time and to be upgraded before kube-controller-manager, kube-scheduler and kubelets. Kubelets may run up to three minor versions older than the API server, so a node pool that lags behind the control plane is allowed, but it is still a state you should record and plan to close. Check the current supported minor versions on the Kubernetes releases page, and confirm which minor version your distribution ships and when it reaches end of life, since your distribution vendor may patch on a different schedule than upstream.
Take an etcd snapshot before any cluster-level change. Kubernetes stores cluster state in etcd, and the operating etcd documentation describes etcdctl snapshot save for backups and etcdutl for restores. Store the snapshot off the control plane nodes, test that you can restore it in a non-production cluster, and record the exact etcd version alongside it. Also confirm that your Secrets are encrypted at rest, because the Helm release stores ERPNext and database credentials as Kubernetes Secrets, and those values are unencrypted in etcd by default.
Keep the cluster change and the ERPNext change in separate change windows with separate rollback plans. A Kubernetes upgrade touches the control plane, nodes and admission behavior, and a failed ERPNext migrate job is easier to diagnose when the cluster is known to be stable. Before you start the ERPNext window, confirm that all nodes are Ready, that the Helm release and the frappe/helm chart version you intend to use support the target Kubernetes minor version, and that the cluster has a tested restore path. Ask your platform team or distribution vendor to confirm these points in writing for your environment.
How DeployOpen scopes, delivers and supports an ERPNext upgrade on Kubernetes
DeployOpen plans and runs ERPNext upgrades on Kubernetes inside your own clusters, cloud accounts or data centers, starting from a written scope. The work covers the image bump, the per-site migrate jobs, cache clearing and the checks that show each site is ready for users again.
How we scope
- Inventory every site on the release, its installed apps and custom code before setting target versions.
- Agree in writing which ERPNext and companion app versions the upgrade targets and which sites are in scope.
- Confirm backup storage, S3 use, maintenance window and rollback expectations with your platform and business owners.
How we build
- Build a versioned Helm values set and custom image on a staging cluster that mirrors production sites and data.
- Run the migrate job for each site in sequence, recording logs, errors and any app-specific steps for review.
- Test business-critical flows such as invoicing, stock movements and reports on the staging copy before production.
How we hand over
- Deliver the upgrade runbook with image tags, job order, cache steps and the rollback path for your team.
- Document the verification checklist used on each site, so your operators can repeat it for later minor releases.
- Walk your platform and ERP owners through the Kubernetes objects, secrets and backup jobs that changed.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer if you want DeployOpen to carry future releases.
- Review each new minor release against your custom apps and Helm values before it reaches production sites.
- Confirm with your team which support scope and response arrangements apply, as set out in the retainer terms.
