Upgrading Deephaven in a Kubernetes environment

This guide covers upgrading Deephaven in a Kubernetes environment using Helm. Commands are shown for running in a Unix-like environment. It is very similar to the procedure described in the Kubernetes installation guide, minus some steps.

Note

The kubectl and helm commands shown in this guide do not explicitly set a namespace and assume that your environment is configured to operate in your intended namespace by default.

Before you upgrade

Caution

Take a complete backup before upgrading. If the upgrade causes a critical issue, restoring from a pre-upgrade backup is your only supported recovery path. Downgrading by switching binaries without restoring from backup is not supported and may result in data corruption or an unrecoverable state.

See Backup and restoration for backup instructions, and Reverting an upgrade for the implications of reverting after an upgrade.

Prerequisites

You must meet the following prerequisites to upgrade Deephaven in Kubernetes:

  • An existing Deephaven deployment running in a Kubernetes cluster.
  • kubectl, docker and helm command line tools.
  • An artifact repository to which Docker images can be stored and from which Kubernetes pods may pull them. In this example, my-repo.dev/my-project/images/deephaven-install is used; replace this with your image repository URL.
  • A Deephaven distributable package containing a Helm chart, support scripts, and Dockerfiles, e.g., deephaven-helm-2026.01.055.tar.gz. This package includes the deephaven-etcd and deephaven-nfs charts, should you need to upgrade them (see Upgrading the etcd and NFS charts).

Note

A routine Deephaven application upgrade only upgrades the Deephaven Helm release. It does not modify or restart the separate deephaven-etcd and deephaven-nfs releases, and it does not require re-loading their images. Upgrade those charts only when moving to a Deephaven version whose release notes call for it.

If using Deephaven pre-built images:

  • A Deephaven distributable package containing pre-built Docker images, e.g., deephaven-containers-2026.01.055.tar.gz.

If building your own images:

  • A distributable containing Deephaven Enterprise, e.g., deephaven-enterprise-2026.01.055.tar.gz.
  • A distributable containing Deephaven Core+ worker, e.g., deephaven-coreplus-42.4-2026.01.055.tgz.

Note

You can either use pre-built container images from Deephaven or build your own images. Building images allows for customizing them to make your JARs available to workers or to add plugins.

Unzip the Deephaven helm chart

Unpack the deephaven-helm package:

Push the Deephaven images to your image repository

If you are using Deephaven's pre-built images, load them into your local Docker repository.

To build images from Deephaven Docker files, first change the directory to the docker subdirectory within the unzipped helm distribution and copy the Enterprise and Core+ distributions to the deephaven_base and db_query_worker_coreplus directories, respectively.

  • To build custom JARs into your images and make them available in Persistent Queries and Code Studios, create a zipped tar file containing your JARs, copy it to the deephaven_customer directory, and add a --customer-coreplus-jar flag to the buildAllForK8s.sh command.
  • To build plugin JARs into your images and make them available to non-worker processes, create zipped tar files containing your plugins, copy them to the deephaven_customer directory, and add up to 10 --customer-plugin flags to the buildAllForK8s.sh command.

Change directory

The rest of the commands in this guide must be run from the helm subdirectory of the unpackaged helm distribution.

Upgrading the etcd and NFS charts

The deephaven-etcd and deephaven-nfs charts are independent Helm releases with their own lifecycle. Most Deephaven upgrades leave them untouched. Only upgrade them when a new Deephaven version ships new chart versions and Deephaven recommends it (the release notes will say so).

Caution

Upgrading the deephaven-etcd chart restarts etcd pods. Confirm a recent etcd backup exists (see Kubernetes etcd backup and recovery) and perform the upgrade during a maintenance window with the Deephaven application scaled down.

To upgrade etcd, re-run setupTools/setup-deephaven-etcd.sh with the same --etcd-name, or upgrade the release directly. --reuse-values preserves your existing settings (including the repo.deephaven.io image repository and its pull secret), and --set image.tag (or --etcd-image-tag on the script) selects the new image:

Note

The deephaven_etcd image is pulled from repo.deephaven.io/deephaven_etcd. The image pull secret created at install time must still exist in the namespace. If you re-run setup-deephaven-etcd.sh instead of using --reuse-values, pass --repository repo.deephaven.io and --image-pull-secret repo-deephaven-io-imgpull again.

The post-upgrade auth job re-runs idempotently; the root password is preserved (it is read from the existing Secret), and the etcd data and backup PVCs are left intact.

To upgrade the NFS server, upgrade its release directly. The backing PVC and its data are preserved, and the directory-setup init container is idempotent:

Note

Legacy Bitnami etcd: deployments still using the Bitnami etcd chart are unaffected by a Deephaven application upgrade. See Kubernetes etcd backup and recovery to migrate to the deephaven-etcd chart.

Install the Deephaven helm chart

The Deephaven helm upgrade requires the name of your Deephaven helm installation. Run helm list to find it if you do not know what it is. Substitute your installation name in place of my-deephaven-deployment-name in the commands shown below.

The upgrade also requires the override YAML file used for the last upgrade or installation. If unavailable, you can run helm get values my-deephaven-deployment-name to get the values configured previously. Substitute your override YAML file name for my-override-values.yaml in the commands below.

Note

Properties for a helm chart are typically stored in one or more YAML files. If more than one is provided to the helm command, priority is given to the last (right-most) file specified with -f. Properties can also be provided with --set flags, which will take precedence over YAML settings.

Scale down your deployment and upgrade the Deephaven helm chart using your override YAML file with these commands:

The installation takes a couple of minutes. You can see progress by tailing the log output of the upgrade job with the command kubectl logs -f job/my-deephaven-deployment-name-pre-release-hook.