When to upgrade Dify Enterprise on Kubernetes and the supported path
You need to upgrade a Dify Enterprise Helm release when it trails the community version it depends on or when a security fix must reach production. The upgrade is a chart and values change plus a database migration, not a container image swap. The supported path is the one the Dify Enterprise Helm chart documentation describes, and you should read the release notes for each target version before you touch the cluster. In the Helm chart, the APP VERSION is the Dify community version and the CHART VERSION is the Enterprise version, so the two numbers you pin must be read together rather than assumed to move in lockstep. Minor releases arrive roughly monthly. The Dify GitHub releases page shows 1.16.0 on July 17, 2026, 1.17.0 on August 25, 2026 and 1.17.1 on September 10, 2026. A team that upgrades only when a problem appears will fall several releases behind and face a larger, riskier jump each time. Plan a repeatable cycle instead: track new releases, review the notes, schedule a staging upgrade, and promote to production on a fixed cadence that your change process can approve. Confirm with your Dify Enterprise account contact which chart versions correspond to each community release and how long they are supported, because that information is not part of the public release feed.
Each cycle needs named owners and a go or no-go decision recorded before the production window. The platform engineer owns the chart version and values file, the database owner owns the pre-upgrade PostgreSQL backup and the restore test, and the security lead decides whether a release is urgent enough to skip the normal window. Ask your team to write down the current chart version, the app version, the target versions and the rollback point before each run. If the target release changes values for plugin or sandbox components, treat that as a separate review item, since those settings affect how agents execute code and reach external services. Use the staging cluster to measure how long migrations take on a copy of production data, so the production window is based on evidence and not on an estimate.
What changed in 1.16.0 to 1.17.1 that affects chart operators
This table compares the security and release changes we can confirm for Dify 1.16.0 through 1.17.1 and states what each one means for a Dify Enterprise Helm release. Read the Impact column to see where the release can touch chart values, pods or network paths, and use the Action column as the pre-upgrade checklist for each target version. Breaking changes and value renames are not confirmed for every version here, so treat the last row as a required check.
| Change | Impact on the Helm release | Action needed |
|---|---|---|
| Agent sandbox network isolation through a Squid proxy (1.16.1) | Outbound traffic from agent sandboxes may pass through a proxy inside the cluster, which can change egress paths and allowed destinations. | Confirm the proxy settings and egress rules in the chart values, then test an agent tool call that reaches an external endpoint in staging. |
| Token-based API authentication between services (1.16.1) | Internal calls between api, worker and plugin components use tokens, so mismatched secrets across pods can fail requests after the rollout. | Verify that the chart generates or references the inter-service token secret, and confirm that all components roll to the same version together. |
| Sandboxed Jinja2 template rendering (1.16.1) | Workflows that use Jinja2 templates run inside a sandbox, so templates relying on unrestricted features may fail or render differently. | Review workflows and prompts that use templates and test them in a staging release before promoting the chart. |
| Dify 1.17.0 release (August 25, 2026) | Carries its own changes on top of 1.16.x. The facts supplied for this page do not list its breaking changes or chart value renames. | Read the 1.17.0 release notes and the chart changelog for the matching chart version, and diff values.yaml against your current file. |
| Dify 1.17.1 release (September 10, 2026) | Follows 1.17.0 as a further minor release. The facts supplied for this page do not list its breaking changes or chart value renames. | Read the 1.17.1 release notes and chart changelog, and confirm the chart version pairs with app version 1.17.1 before running helm upgrade. |
| Database schema migrations between 1.16.0 and 1.17.1 | Migrations run on upgrade, so a failed rollout can leave the database in a state that a rollback to the old image cannot fix alone. | Take a PostgreSQL backup before each helm upgrade and confirm the restore procedure for the target version. |
| Chart value renames or removed keys | Renamed or removed keys can silently fall back to defaults and change replica counts, resources or sandbox settings. | Confirm in the chart changelog for each target version, then compare your overrides with the new defaults before upgrading. |
Back up PostgreSQL and inventory values before the helm upgrade
The Enterprise chart docs tell operators to back up the database before an upgrade so a failed upgrade can be rolled back and restored. The items below are the preparation that makes that restore usable, and they should be finished before anyone runs helm upgrade on a production release.
Take a PostgreSQL backup first
Take a full PostgreSQL backup immediately before the helm upgrade, not a backup from last week's schedule. Confirm the dump completes, record its size and checksum, and store it outside the cluster. Dify keeps application state, app configuration and workspace data in this database, so a rollback to the previous chart and app version only works if this backup can be restored cleanly. Check that the restore procedure has been run by someone other than the person who took the backup.
Copy the current values and overrides
Save the exact values file that the running release was installed with, along with every override file, secret reference and --set flag used in past installs. Store them in version control with a tag that names the chart and app version. Without this copy, a rollback has to rebuild the configuration from memory, and any environment-specific setting can be lost in the process.
Record chart and app versions
Record the chart version and the app version of the running release. In the Dify Helm chart, the APP VERSION is the Dify community version and the CHART VERSION is the Dify Enterprise version, so the two numbers answer different questions. Write down the target pair as well, and confirm in the release notes that it is a supported combination before you start.
Build a test environment from backup
Restore a recent PostgreSQL backup into a separate namespace or cluster, deploy the target chart and app versions there, and run the upgrade as a rehearsal. Check that logins, workflows, knowledge base queries and scheduled jobs behave as expected. A rehearsal shows how long the migration takes and whether any values need changing, which is the information you need to plan the production window.
Inventory secrets and external services
List every secret the release reads and every external service it depends on, including Redis, the Qdrant vector database and S3-compatible object storage. For each one, record the owner, the location of the secret and the connection settings. Confirm that the upgrade does not rotate these credentials. An upgrade that changes a secret key or endpoint can leave the database and external services out of step, so verify this before the change window opens.
Document sandbox and plugin settings
Record how the sandbox and plugin components are configured in your current values, including resource limits, network isolation and plugin sources. Compare these against the new chart's values before the upgrade, because new components can add keys or change defaults. Note any plugin that must stay at a fixed version so you can confirm it still runs after the upgrade.
Upgrade sequence with checks and rollback points
This sequence moves a Dify Enterprise Helm release to a new version in an order that keeps a known-good database restore point and a tested rollback path at every stage. Each step closes with a check, so the team knows whether to continue, roll back or stop.
Confirm cluster and tooling prerequisites
The platform engineer checks the target cluster against the Dify Enterprise resources checklist: Kubernetes 1.24 or later, Helm 3.14 or later, PostgreSQL 14 or later, Redis 6 or later, a Qdrant vector database and S3-compatible or cloud object storage. Run
kubectl versionandhelm versionand record the output with the change ticket. This step is done when every component meets or exceeds the listed minimum. If a component is below the minimum, stop and schedule the component upgrade first, because a chart upgrade on an unsupported base can fail partway through.Match the chart version to the target app version
The release owner reads the Dify Enterprise Helm chart documentation and selects the target CHART VERSION, which tracks the Dify Enterprise release. Confirm the APP VERSION shown for that chart, which is the Dify community version it packages, and check it against the release notes on the Dify GitHub releases page. Record both values. This step is done when the chart version and app version pair is written down and the release notes have been read for breaking changes, such as plugin or sandbox requirements. If the pair is unclear, ask the Dify Enterprise contact to confirm before proceeding.
Back up PostgreSQL before any change
The database administrator takes a full PostgreSQL backup of the Dify metadata database in the target environment, using the backup tooling your team already runs for PostgreSQL. Store the backup outside the cluster, record its identifier and confirm that a test restore to a scratch instance succeeds. The Dify Helm chart documentation says to back up the database before an upgrade so a failed upgrade can be restored. This step is done when the backup is verified by a restore test. Do not proceed on an unverified backup, since a rollback depends on it.
Diff the values file against new chart defaults
The platform engineer renders the new chart with
helm templateand compares it to the currently deployed values usinghelm get valuesand a diff tool. Pay particular attention to plugin daemon and sandbox settings, new required keys and any defaults that changed. Keep the customized values in version control so the change is reviewable. This step is done when every difference is either intentional and documented or resolved. An unexplained difference in sandbox or plugin configuration blocks the upgrade until the owner signs it off.Run the helm upgrade in staging
The team applies the reviewed values to a staging release with
helm upgradeusing the confirmed chart version, and waits for the rollout to finish. Staging should hold a copy of production data or a representative subset, restored from the production backup, so that migrations run against realistic content. This step is done when the helm release reports a deployed status and the rollout completes without failing pods. If the upgrade fails, runhelm rollbackto the previous revision and restore the staging database from the backup, then fix the cause before retrying.Verify pods, migrations and sign-in in staging
The operations team checks that all pods reach ready state, reviews the API and worker logs for database migration errors, and confirms that the plugin daemon and sandbox services start. Then an administrator signs in through the configured SSO path, opens an existing workspace, runs a test workflow and queries a knowledge base. This step is done when pods are healthy, migrations complete without errors and a test user can sign in and run a workflow. If a migration fails, restore the staging database from the backup and roll back the release, since the schema may be partially changed.
Promote to production with a rollback window
The change owner repeats the same sequence on production in a planned window, starting with a fresh production PostgreSQL backup taken immediately before the upgrade. Keep the previous Helm revision available for
helm rollback. After the upgrade, run the same pod, migration and sign-in checks used in staging. If the checks fail, roll back the release and restore the production database from the backup taken in this window, then record the outcome. This step is done when the production checks pass and the backup identifier, chart version and app version are recorded in the change log.
Why chart and app versions must match on each upgrade
In the Dify Helm chart, the APP VERSION is the Dify community version and the CHART VERSION is the Dify Enterprise version. An upgrade therefore changes two numbers that describe two different things: the application code that runs in the api, worker and web pods, and the Enterprise chart that defines how those pods are deployed, wired together and configured. Neither number tells you the state of the other, so the reader should treat them as a pair. Read the chart version and the app version together every time, and do not assume that a new chart brings a new application image or the reverse.
A mismatch creates failures that are easy to misread. If the chart is moved forward while the app version stays on the older community release, templates may expect environment variables, services or sidecar settings that the running images do not understand, and the rollout can look successful while features fail. The reverse is also risky: a newer application image deployed through an older chart may miss new values for plugin daemon or sandbox components that the release depends on. Because the chart also drives the database layout that the release expects, a half-applied pairing is one of the harder states to reason about during a rollback.
Record both values before and after each release, in the change ticket and in your own values repository, so you can see which pair was running at any point. Then confirm the pairing for the target release in the Dify Enterprise Helm chart documentation before you run helm upgrade, and check the release notes for both the community version and the Enterprise chart. If the docs do not clearly list the matching app version for the chart you intend to install, ask your Dify contact to confirm it in writing before the change window opens.
Checking new values for plugin and sandbox components
Plugins run through the plugin daemon, so the values that configure it are the first place a chart upgrade can change behavior. Compare the new chart's default values with the values you currently deploy, and record every key that differs before you run the upgrade. The public facts do not list the exact plugin daemon value keys, so confirm the key names, defaults and storage settings in the chart values reference for your chart version.
- Diff the defaults: Export your current values and compare them with the new chart's defaults, keeping your overrides and noting any default that changed.
- Storage settings: Confirm where plugin packages are stored and that the volume or object storage target still points where your installed plugins live.
- Plugin install settings: Check the settings that control whether plugins can be installed, from which sources, and whether marketplace access is allowed in your environment.
- Startup after upgrade: Once the release is running, confirm that the plugin daemon starts and that each model and tool plugin you use reports as installed and enabled.
- Test a live call: Run one workflow per plugin category in use, because a daemon that starts can still fail when it loads a plugin.
Before you sign off, keep the diff and the test results with your change record so the next upgrade starts from a known baseline.
Dify 1.16.1 added agent sandbox network isolation through a Squid proxy, which changes how sandboxed code reaches the network. Tools that call internal endpoints, such as an intranet API, a private model server or a database behind your firewall, may stop working even when the chart upgrade itself succeeds. Review the sandbox and egress values with your network team, and confirm the exact key names in the chart values reference.
- Isolation effect: Expect sandboxed tool calls to pass through the proxy, so any destination not allowed by your proxy rules can fail silently inside a workflow.
- Internal endpoints: List every tool and workflow that reaches a private hostname or address, then test each one after the upgrade.
- SSRF_PROXY behavior: Review the SSRF_PROXY settings, which route outbound requests through a proxy that blocks internal and private IP ranges. Confirm which destinations you must allow explicitly and which must remain blocked.
- Allow-list changes: Record each proxy or network policy change as a deliberate decision with an owner, so the block is not loosened by accident.
- Failure test: Run a call to a blocked destination and confirm the error surfaces in logs as an egress block, not as a model or tool fault.
Close this tab only when every internal dependency has a passing test and each allowed destination has a documented reason.
Dify 1.16.1 added token-based API authentication between services. Components that previously trusted each other by network location now need a shared secret or token to call one another. If a component reads a secret that is missing, mismatched or stale, requests between services fail, and the symptoms can look like unrelated timeouts or 401 responses. Confirm which secrets each component reads and that they match across the release.
- Secret inventory: List every inter-service secret the chart creates or expects, including which component reads each one, and compare that list with your existing secret objects.
- Source of truth: Decide whether secrets come from the chart, your external secrets manager or Kubernetes secrets you manage, and make sure the upgrade does not regenerate them.
- Consistency check: Confirm that the api, worker and plugin-related components read the same value where a shared secret is expected.
- SECRET_KEY impact: Do not change SECRET_KEY during the upgrade, because changing it after deployment logs out all users, and confirm it is preserved from your backup.
- Rotation plan: If you rotate inter-service secrets, schedule it as a separate change with its own rollback step.
Before you finish, confirm the secret names and reader components in the chart values reference, and record the check in your upgrade log.
What makes Enterprise chart upgrades take longer
This table lists the factors that stretch a Dify Enterprise Helm chart upgrade and what each one changes in the work. Read each row as a question to answer during planning, because the effort usually grows with the number of values overrides, plugins, environments and dependencies you must verify. The main takeaway is that most of the delay comes from checking and promoting, not from the helm command itself.
| Driver | Effect on the upgrade | What to check |
|---|---|---|
| Custom values and overrides | Every local change to values files must be compared against the new chart defaults, which adds review time and the risk of silent drift. | Diff your values files against the target chart's values, and confirm which overrides are still needed. |
| Installed plugins and their versions | Plugin compatibility with the new app version must be confirmed, and plugin daemon settings may need new keys. | List each installed plugin and version, and confirm the target release supports each one before upgrading. |
| Database size and migration time | Larger PostgreSQL databases take longer to back up and to migrate, and a rollback restore takes longer too. | Measure current database size, time a test backup and restore in staging, and schedule the window around the result. |
| Workspaces and apps to smoke test | More workspaces and published apps mean more workflows, knowledge bases and agents to exercise after the upgrade. | Build a short list of critical apps per workspace, including workflows that call models, tools and knowledge bases. |
| External Qdrant and object storage | Vector store and file storage run outside the chart, so their version and connectivity need separate checks and possibly a separate backup. | Confirm Qdrant and S3-compatible storage remain reachable with current credentials, and back them up on their own schedule. |
| Environments promoted in order | Development, staging and production each need the same chart and app versions, so the upgrade repeats once per environment in sequence. | Agree the promotion order, and confirm each environment runs the same chart version before production starts. |
| Cluster change control windows | Approval cycles and freeze periods can push the production upgrade back, even when staging testing is complete. | Ask your change board for the approved window, required change records and the rollback decision owner. |
Rolling back with a database restore, not only a helm rollback
A helm rollback reverts the Kubernetes objects in the release, such as Deployments, Services and ConfigMaps, to their previous revision. It does not reverse changes the new version made to PostgreSQL. If the upgraded Dify applied schema migrations or rewrote data, the older app version may start against a schema it does not understand. That is why the PostgreSQL backup taken before the upgrade is the real rollback point, and the helm revert is only one step in restoring service. Confirm before the upgrade window that you hold a dump or snapshot that you have checked can be read back, and record the chart and app versions that were running before the change so you know what the rollback target is.
Test the restore in staging before you rely on it in production. Restore the pre-upgrade backup into a staging PostgreSQL instance, deploy the previous chart version against it, and confirm that login, workspace access, a sample workflow run and a knowledge base query all work. Before restoring in production, stop everything that writes to the database: the api, worker and any scheduled jobs, plus external callers using service API keys, so no new rows land between the restore and the rollback. Confirm with your Dify Enterprise support contact which chart version corresponds to the pre-upgrade app version, because the Dify Helm chart docs define the CHART VERSION as the Enterprise version and the APP VERSION as the community version. After rollback, check that helm history shows the expected revision and that the running images and chart version match that pair.
Plan for data loss explicitly. Anything written after the backup was taken, including new conversations, workflow runs, uploaded documents, knowledge base changes, and app edits, is lost when you restore the older database, and it will not come back from the helm rollback. Ask the platform team to quantify the write window from the backup timestamp to the moment you stopped services, and decide whether those records can be recreated from logs or source systems. Note that vector store contents are held separately from PostgreSQL, so confirm how your Weaviate, Qdrant or other vector store and object storage are aligned with the restored database before you declare the rollback complete.
Questions teams ask before upgrading Dify Enterprise on Kubernetes
How much does a Dify Enterprise Helm upgrade cost?
The cost is set by the written scope, which DeployOpen agrees with you before work starts, so there is no standard price to quote here. Most engagements are fixed scope, which covers the agreed upgrade steps, the backup and restore checks, and the handover documentation. Ongoing work such as later upgrades, checks and continuous testing can run as a retainer. Ask for the quote to list one-time work separately from recurring items, and to state what each line includes. Your own costs also count: staff time for cluster and database access, approvals and a test environment. Dify's pricing page says the self-hosted Enterprise edition is custom priced, so confirm license terms with Dify separately from any services quote.
How long does an upgrade take, and what makes it longer?
Duration depends on the size of the gap between your current chart and the target version, the number of customized values, and how much of the platform you run. Upgrades that cross several minor releases need more release-note review and more testing than a single step. The size of your PostgreSQL database affects backup and restore time, and the number of plugin and sandbox settings in use affects validation. Access approvals and the availability of a staging cluster often matter more than the Helm command itself. Ask for a schedule in the written scope that lists these drivers, so you can see which items your team controls. Dify publishes new minor releases roughly monthly, so plan for the cadence as well as the single upgrade.
What does our team need to provide for the upgrade?
Your team needs to provide working access that the upgrade depends on, and decisions that only your organization can make. In practice that means access to the Kubernetes cluster with rights to run Helm and inspect workloads, database access to take and verify a PostgreSQL backup, and a non-production environment that mirrors production as closely as possible. You also need named approvers for the change window, the rollback decision, and any sign-off on new values. Confirm that your Kubernetes is at or above the version the Dify Enterprise resources checklist requires, that Helm meets its minimum, and that Qdrant and object storage are reachable from the cluster. List these items in the written scope so gaps are found before the change window.
Can our internal team run the upgrade without outside help?
Yes, a capable platform team can upgrade Dify Enterprise on its own if it has the Enterprise documentation, a tested database backup, and a written rollback plan. The most important steps are matching the chart version to the Dify Enterprise version, confirming that the app version and chart version are the ones your license covers, and rehearsing a database restore in staging. Outside help is most useful when the team has little Kubernetes or PostgreSQL experience, when many values have been customized, or when the upgrade has to meet an audit calendar. Rehearse the rollback before you rely on it, because a restore that has never been tested is the most common gap in an upgrade plan.
How often do Dify upgrades arrive, and how should we plan for them?
Dify's GitHub releases show minor versions arriving roughly monthly. The releases page lists 1.16.0 on July 17, 2026, 1.17.0 on August 25, 2026, and 1.17.1 on September 10, 2026. Not every release requires a Helm chart change, and not every change affects your deployment, so review the release notes for each target version. Plan a recurring cycle that covers a staging upgrade, a database backup before each production change, and a validation pass for plugin and sandbox settings. A cadence that falls behind can make a later jump larger and riskier, so decide in advance how many releases you will accept per change window.
What does DeployOpen provide beyond the upgrade itself?
DeployOpen can provide the upgrade work, plus the documentation and checks that let your team operate the result. Typical deliverables, all defined in the written scope, include a runbook for the chart and app versions, a backup and restore procedure tested against your database, a review of values for plugin and sandbox components, and a post-upgrade verification checklist. Retainers can cover later upgrades, support and continuous security testing on a recurring basis. These services prepare systems and evidence for your own compliance assessments, but they do not produce audit reports or certifications, which independent auditors and certification bodies issue. Ask for the deliverables to be listed by name in the scope.
How DeployOpen scopes and delivers a Dify Enterprise chart upgrade
DeployOpen plans, implements, backs up, documents and supports self-hosted open-source platforms inside the client's own infrastructure, including Kubernetes clusters. For a Dify Enterprise Helm chart upgrade, we start from the chart and app versions in your cluster, the database backup and rollback path, and the values your plugin and sandbox components depend on.
How we scope
- We record the current chart version, app version, values files and cluster versions before agreeing the upgrade target.
- The written scope names the PostgreSQL backup method, restore test, rollback steps and the environments included.
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we build
- We compare new chart values with your existing overrides, focusing on plugin daemon and sandbox settings and secrets.
- We rehearse the upgrade in a non-production environment, including a database restore to confirm the rollback path works.
- Each change is recorded in version control so the production upgrade can be reviewed and repeated.
How we hand over
- You receive the runbook, the verified backup and restore procedure, and a record of the values changed and why.
- Handover covers the post-upgrade checks we ran, such as login, workflow runs, knowledge base queries and plugin health.
- Your operators walk through the rollback steps so the team can act without relying on the original engineers.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers for teams that take Dify releases regularly.
- A retainer can cover monitoring of new Dify minor releases, chart reviews and rehearsals before each planned upgrade.
- Ask for the support scope, response arrangements and fees in writing, based on the written scope and your environment.
