Kubernetes installation

This guide covers installing Deephaven in a Kubernetes environment using Helm. Commands are shown for running in a Unix-like environment. The installation can be customized by setting the Helm values described in the Kubernetes configuration settings page.

If you are trying out Deephaven in a minimal capacity for testing purposes and do not plan on ingesting a lot of data, see the Quickstart guide. Before continuing further, make sure you have read the planning guide to help determine how much memory and storage to configure for the system.

Prerequisites

You must meet the following prerequisites to deploy Deephaven with Kubernetes:

• A Kubernetes cluster on a supported provider and version — Deephaven currently supports GKE (Google Kubernetes Engine), EKS (Amazon Elastic Kubernetes Service), and AKS (Azure Kubernetes Service). For supported Kubernetes versions, see the version support matrix. A dedicated namespace must be created for the Deephaven installation.
• kubectl, docker, and helm command line tools. Verify that your kubectl client version is close to your cluster's server version — a large skew can cause unexpected failures. Run kubectl version to compare.
• A username and password for the repo.deephaven.io image repository URL in order to create an image pull secret.
  • As an alternative, Deephaven can provide images as a tar file and you can push them to your own internal repo.
• A TLS webserver certificate and the private key that corresponds to it. The webserver and certificate must meet Deephaven's requirements. The Deephaven installation includes a LoadBalancer service (Envoy) that is the entry point for the application. A DNS entry for the hostname associated with this certificate must be created after the installation.
• 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 bundled deephaven-etcd and deephaven-nfs Helm charts used to deploy etcd and shared storage.
• Access to the deephaven_etcd image at repo.deephaven.io/deephaven_etcd. Your cluster pulls it using an image pull secret you create from credentials provided by your Deephaven associate (see Install the etcd Helm chart), or you may mirror the image into your own repository.

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.

Kubernetes resource requirements

Before deploying Deephaven, ensure your Kubernetes cluster has sufficient resources to support the deployment. The requirements below are for a deployment with default configuration settings.

Minimum cluster resources

A minimal cluster requires:

Resource breakdown by component

The default Helm chart configuration allocates resources across multiple pods:

• etcd cluster: 3 pods with memory and CPU requests.
• Deephaven infrastructure services: Web API, Configuration Server, Authentication Server, etc.
• Persistent Query Controller: Manages query execution.
• Envoy proxy: Handles ingress traffic (requires one External IP).
• Worker pods: For Code Studio sessions and Persistent Queries (scale based on usage).

Storage requirements

Deephaven data and configuration storage falls into three categories, each with different requirements:

Your cluster must also provide:

• Persistent volumes for etcd: the deephaven-etcd chart provisions one RWO data volume per etcd pod (8Gi by default), and etcd backups are written to a shared RWX volume (provided by the deephaven-nfs chart or your own storage).
• A storage class appropriate for your Kubernetes provider (e.g., premium-rwo for GKE, gp2 for EKS, managed-csi for AKS).

Define deployment variables

Define these shell variables once before starting. They are referenced throughout this guide — replace the example values with names appropriate for your environment.

Set the namespace for your Kubernetes context

Start by creating your Kubernetes namespace and setting it to the default for your kubectl context if you have not already done so.

Unzip the Deephaven Helm chart

Unpack the deephaven-helm package:

Deephaven images

Create image pull secret

Deephaven publishes the application container images to its image repository at repo.deephaven.io. By default your cluster pulls them directly from there, so there is no separate load-and-push step. Create an image pull secret in your namespace using the username and password provided by your Deephaven associate - the same secret is also used for the deephaven_etcd image:

The Deephaven Helm chart references these images through image.repositoryUrl (set to repo.deephaven.io) and the pull secret through imagePullSecrets; both are configured in Install the Deephaven Helm chart.

Managing your own images

If you are not pulling the Deephaven images from repo.deephaven.io, you will need to load and push them yourself - see this section below.

Push the Deephaven images to your own repository

If you prefer to host the Deephaven images in your own artifact repository - for example, because you want to build customized images yourself, or your cluster cannot reach repo.deephaven.io - you can load and push them yourself. Deephaven provides pre-built images as a tar file (deephaven-containers-2026.01.055.tar.gz), or you can build your own with the dockerfiles provided in the deephaven-helm-2026.01.055.tgz distribution.

Use pre-built imagesBuild your own images

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.
• For Legacy workers, use the --customer-jar flag.
• 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.

Note

The deephaven_etcd image is separate from the application images and is not handled by pushAll.sh. If your cluster cannot reach repo.deephaven.io, mirror deephaven_etcd:VAR:DH_ETCD_IMAGE_VERSION into your own repository and point --repository at it in Install the etcd Helm chart.

Change directory

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

Configure shared storage

The Deephaven deployment requires read-write-many (RWX) Persistent Volumes for data that must be shared across pods. This storage is used for historical table data (/db/Systems and /db/Users) and etcd backups.

The table below summarizes the distinct PVs and PVCs in a Deephaven Kubernetes deployment:

You have two options for providing this shared storage:

1. Create a new NFS deployment — Install the provided deephaven-nfs helm chart to deploy an NFS server within your Kubernetes cluster.
2. Use pre-existing PVCs — Configure Deephaven to use existing RWX persistent volume claims that you have already created in your environment.

Choose one of the following approaches:

Install the etcd Helm chart

The setup-deephaven-etcd.sh script in the setupTools directory of the deephaven-helm package installs the deephaven-etcd Helm chart. The command below creates a 3-node etcd deployment (--replica-count defaults to 3; it must be odd). Note the etcd installation name (--etcd-name), as it will be needed when configuring the Deephaven Helm chart.

By default the script also creates a backup PVC/PV for etcd on the Deephaven NFS server (using its etcd-backup export) and enables periodic snapshots. It therefore assumes the deephaven-nfs service from the Configure shared storage step is running; the script locates it automatically or you can pass --nfs-ip. To use your own RWX volume for backups instead, pass --existing-pvc-name <pvc>; to skip backups entirely (non-production only), pass --no-backup.

The --pv-prefix value is prepended to the names of the etcd backup snapshot PV and PVC (e.g. dh-dev1-etcd-backup-snapshot-pv), making them unique across installations since PV names are cluster-scoped. It does not affect the etcd data volumes, which are created and named by the deephaven-etcd StatefulSet. It can be any short arbitrary string such as dh-dev1, dhqa, etc. To see all options, run setupTools/setup-deephaven-etcd.sh --help.

The deephaven_etcd:VAR:DH_ETCD_IMAGE_VERSION image (overridable with --etcd-image-tag) is pulled from repo.deephaven.io/deephaven_etcd using the repo-deephaven-io-imgpull pull secret created in Deephaven images. Install etcd, passing the image repository and that pull secret. (If you mirrored the image into your own repository, use that location for --repository instead.) If you are providing your own ReadWriteMany (RWX) pvc for backups, pass --existing-pvc-name <my-pvc-name>.

It will take a minute for the etcd pods to start up and become ready. You can check the status of the pods with this command, and should eventually see all pods with a 1/1 container ready status (note that the exact pod names will depend on the helm installation name):

Verify etcd cluster health

Once all pods show 1/1 Running and the auth Job has completed, verify the cluster is healthy before proceeding. A healthy etcd cluster is required for the Deephaven installation to succeed.

A healthy cluster reports each endpoint as true under the HEALTH column.

Reinstalling a broken etcd cluster

If you need to reinstall etcd from scratch, uninstall the Helm release and remove its PVCs and PVs first. The setupTools/delete-deephaven-etcd.sh script automates this; the equivalent manual steps are:

For a full etcd backup and restore procedure, see the Kubernetes etcd backup and recovery guide.

Install cert-manager (optional)

If you wish to run Deephaven services using TLS within the cluster for intra-cluster communication, you need to install cert-manager. This is optional but recommended for production environments.

Check if cert-manager is already installed

To see if cert-manager is installed on your cluster already, run:

If you see a message saying error: the server doesn't have a resource type "clusterissuer", then cert-manager is not installed.

Install cert-manager

There are several ways to install cert-manager. Full instructions are provided at the cert-manager installation page. The most straightforward way is to do the default static install listed there. The cert-manager project also provides a Helm chart that may be used to install cert-manager.

Configure the issuer

The setupTools/ca-bootstrap-issuer.yaml file in your Helm distribution will create:

• A ClusterIssuer for the entire Kubernetes cluster that creates a self-signed root CA certificate.
• An Issuer in your target Kubernetes namespace that will issue certificates with the root CA in the certificate chain.

You may create a new YAML file defining an Issuer configuration that is not self-signed if there is infrastructure to support it in your organization. For example, you may define an issuer that is configured to use HashiCorp Vault or an external provider. Details for these configurations may be found in the cert-manager issuer configuration docs.

Using an existing ClusterIssuer

If a ClusterIssuer is already present in your cluster, you can copy the second and third sections from ca-bootstrap-issuer.yaml (Certificate and Issuer definitions) to a new file, and update them for the names of your ClusterIssuer and namespace. Then apply the new file using kubectl apply -f.

Creating the default self-signed cluster issuer

To create the default self-signed cluster issuer:

1. Edit setupTools/ca-bootstrap-issuer.yaml and replace occurrences of <your-namespace> with your target Kubernetes namespace.
2. Apply the configuration:

Create a Kubernetes secret for the TLS certificate

With the TLS certificate and private key stored as files named tls.crt and tls.key, respectively, run this command to create a deephaven-tls secret from them:

Create Roles and RoleBindings

Deephaven relies on Kubernetes role-based access control (RBAC) to grant certain pods the ability to add new objects to the Kubernetes cluster. This is used for two purposes:

• The Helm install hook adds Kubernetes Secrets and ConfigMaps that are used by various components of the Deephaven platform.
• The query dispatcher pod adds additional pods, services, and other Kubernetes objects to allow new persistent queries and code studios to start.

Verify that the user running the Helm installation is able to create Kubernetes Roles, RoleBindings, and ServiceAccounts. You can check this with the kubectl auth can-i command:

The output should be "yes" three times:

If the output is "yes" for all three permissions, then you may proceed with the installation. If not, please see Configuring roles, role bindings, and service accounts for details on how an administrator can manually create these objects before performing the installation with Helm as described below.

Permissions required to install, upgrade, and administer the chart

Installing, upgrading, and administering Deephaven — through helm, kubectl, and the bundled admin scripts (dh_helm, setupTools/scaleAll.sh, restartAll.sh) — creates and manages a broad set of Kubernetes objects. These operations run with the credentials of whoever runs the command, not the chart's ServiceAccounts.

If you must run as a least-privilege identity (for example, an automated CI/CD or GitOps service account), you have two options:

• Have a cluster administrator create a ServiceAccount, grant it the permissions listed below, and run the installation and administration as that ServiceAccount. See Configuring roles, role bindings, and service accounts.
• Grant the permissions listed below directly to your installing identity.

Detailed permissions for a least-privilege installer

The RBAC Roles created above grant the running Deephaven pods the access they need at runtime — for example, the dispatcher creating worker pods. They do not grant the permissions needed to install, upgrade, or administer the deployment. That installing identity is an interactive user in many environments, but a ServiceAccount (for example, an automated CI/CD or GitOps service account) in others.

Helm applies (and, on helm uninstall, removes) every object the chart renders using this identity. Therefore, it requires full management of the following resource types:

• the pre-install/upgrade hook Job
• the chart's own ServiceAccounts, Roles, and RoleBindings
• cluster-scoped PersistentVolumes

The earlier kubectl auth can-i check for roles, role bindings, and service accounts only covers part of this list.

Namespaced resources (in the install namespace) — These need get, list, watch, create, update, patch, and delete:

API group	Resources	Created / used by
apps	deployments	Helm creates the infra Deployments (dis, las, envoy, webapi, etc.); scaleAll.sh scales them
apps	statefulsets, statefulsets/scale	Helm creates the core-service StatefulSets (aclwriter, authserver, configuration-server, controller); scaleAll.sh scales them via kubectl scale
""	services	Helm creates all service objects
""	configmaps	Helm creates config maps (cluster config, envoy, worker templates, etc.)
""	secrets	Helm creates chart secrets; the manual TLS-secret step also creates one
""	persistentvolumeclaims	Helm creates PVCs; dh_helm gets/patches/deletes them
""	serviceaccounts	Helm creates the chart's service accounts
""	pods, pods/exec, pods/log	restartAll.sh deletes pods to recycle them; dh_helm waits on, execs into, and copies files to pods (also the NFS setup step)
rbac.authorization.k8s.io	roles, rolebindings	Helm creates the chart's RBAC objects (runtime and hook)
batch	jobs	Helm creates the pre-install/pre-upgrade hook Job
cert-manager.io	certificates	Only when the cert-manager integration (certmgr.enabled) is used

Cluster-scoped resources — These are not namespaced, so they require a ClusterRole:

API group	Resources	Needed for
""	persistentvolumes	The chart creates PersistentVolumes for shared/system storage and the hook PVC (get, list, watch, create, update, patch, delete)
""	namespaces	Creating the install namespace, if the installer does it (create, get)

In most clusters, this identity is a human administrator with broad (often cluster-admin) rights, so no extra setup is needed. For a least-privilege or ServiceAccount-based installer, the simplest complete grant is to bind the built-in admin ClusterRole within the namespace (a namespaced RoleBinding to admin covers every namespaced resource above), plus a small ClusterRole for the cluster-scoped persistentvolumes (and namespaces, if the installer creates it).

You can confirm the identity has what it needs with kubectl auth can-i. Each command should print "yes":

This full set belongs to the installing/administering identity. The chart's runtime ServiceAccount intentionally holds only a small, fixed slice of it (for example, a limited statefulsets/statefulsets/scale grant reserved for potential in-cluster use). We do not recommend extending the runtime ServiceAccount with the broader create/delete permissions above to work around an under-privileged installer.

Install the Deephaven Helm chart

You can now configure deployment settings in the Deephaven Helm chart. An example configuration YAML file is shown here, with comments providing more details. You can save this as something like deephaven-override-values.yaml, and its values will override the defaults defined in the chart.

Override values YAML example

You can now install the Deephaven Helm chart using your override YAML file:

The installation takes a couple of minutes. You can see progress by tailing the install job's log output with the command kubectl logs -f job/${DH_NAME}-pre-release-hook.

Create a DNS entry for the application

You need a DNS entry for the hostname referenced by the TLS certificate, using the external IP address of the Envoy service. How this is done varies with your Kubernetes provider and/or infrastructure. This example uses a Google Cloud Platform environment.

Set a password for the admin user

Run this command to use the Deephaven deployment’s management shell pod to run a command that sets up the user dh_admin with a password. In this example, the password is adminpw1, though you are encouraged to provide your own.

Set up resource monitoring and notifications

Each enterprise has a different way of setting up Kubernetes monitoring, metrics, and notifications using tools like Prometheus/Grafana, Datadog, or your cloud provider's offering, such as Cloud Monitoring in GKE. In a production Deephaven system, it is very important to set up notifications around persistent volume utilization so that action can be taken (e.g., expand storage, remove data) before a volume fills up, potentially stopping services and/or preventing data ingestion.

Log in

You can now access the application at a URL similar to https://yourhost.domain.com:8000/iriside, using the hostname that matches your webserver TLS certificate.

Autoscaling disruptions

Autoscaling solutions like Karpenter and Cluster Autoscaler add and remove nodes based on demand, and will also move pods between nodes to consolidate resources and drain a node so it can be removed. Since Deephaven pods are typically used continuously throughout their lifetimes, it is undesirable to allow an autoscaler to disrupt them to drain a node. Deephaven pods can be annotated to exempt them from autoscaler disruption. Check the details of your particular autoscaler for the required annotations, if it is not one of the options below.

Add the relevant annotation section to your values.yaml to mark Deephaven pods as protected from autoscaler disruption.

• Karpenter on Amazon EKS:

• Cluster Autoscaler on Azure AKS, or Google GKE Autopilot:

EKS specific information

Amazon Load Balancers

The default Amazon EKS setup uses the in-tree Kubernetes load balancer controller, which provisions Classic Load Balancers. The default Classic Load Balancer settings terminate connections after 60 seconds of inactivity. This results in Deephaven workers being killed when their controlling connection is closed. It is possible to manually configure the timeout, but Deephaven recommends installing the AWS Load Balancer Controller add-on, which uses a Network Load Balancer. Additionally, the AWS Load Balancer Controller supports annotations for configuring the service. The complete set of annotations that are suitable for your network is beyond the scope of this document (e.g., subnet and IP allocation), but the section below provides some recommendations for common configurations.

AWS NLB without Karpenter

The following annotations (specified in your Deephaven values.yaml file) instruct the controller to create a suitable Network Load Balancer:

AWS NLB with Karpenter

Karpenter provides autoscaling features for Kubernetes, deploying additional nodes when needed for new pod resources, and consolidating and removing nodes that are no longer needed. Karpenter interacts with the AWS NLB because the default instance target type routes NLB traffic through the ENIs (Elastic Network Interfaces) of cluster nodes. Karpenter is unaware of the NLB's use of the nodes, so it is possible that Karpenter will remove a node while the NLB is using it for a client session. There are two configuration options to address this:

1. Use ip target type. This configures the load balancer to connect directly to target IPs, rather than routing through node ENIs.

2. If ip targets are not usable -- for example, if Cilium is in use, which is largely incompatible with ip targets -- then it will be necessary to configure the NLB to use labelled nodes that are known to be persistent in the cluster and not subject to sudden removal by Karpenter.

Manually configuring a Classic Load Balancer Timeout

When using a Classic Load Balancer, a manual workaround is to identify the AWS load balancer that the Kubernetes system allocated and increase the connection timeout using the AWS command-line tool.

To identify the load balancer, first run kubectl to find the external name of the load balancer:

In this example, the load balancer is identified by a89229d6c7c3a43fbba5728fb8216c64. The load balancer attributes can be queried with:

To adjust the connection idle setting to 900 seconds, run:

Minimal memory changes needed for EKS and AKS

When deploying to AKS (Azure) or EKS (Amazon Web Services), the default memory requests and limits for some services need to be modified. The settings are detailed in the troubleshooting guide.

Verifying Kubernetes API access

The Kubernetes HTTPS API must be accessible from within Pods of the Deephaven cluster. This is typically enabled by default, but could be blocked or disabled by DNS misconfiguration, network policies, or CNI configuration.

Access to the API can be checked by running this command from within any Pod that has curl available:

The result should be similar to this:

If the command times out or fails, Deephaven will not be able to run in this environment. Deephaven uses the Kubernetes API to set up the cluster during installation and upgrade, and also to create and manage Pods and PVCs for Deephaven Workers.

Related documentation

• Certificate requirements
• Installation planning
• Kubernetes configuration settings
• Kubernetes quickstart
• Kubernetes upgrade guide
• Kubernetes etcd backup and recovery
• Supported versions