---
title: Kubernetes
---

This guide covers how to get started with Deephaven quickly in a Kubernetes environment. The commands in this guide are for a Unix-like environment.

> [!NOTE]
> This installation is intended for trial use only. This document uses system defaults throughout, which are not suitable for many production environments. For complete coverage of the Deephaven Kubernetes installation, see the [Kubernetes installation guide](../sys-admin/kubernetes/kubernetes-install-guide.md).

## Prerequisites

Before deploying Deephaven Enterprise with Kubernetes, you need the following:

- A Kubernetes cluster, with a dedicated namespace created for the Deephaven installation.
- `kubectl` and `helm` command-line tools.
- Permission to create `Roles`, `RoleBindings`, and `ServiceAccounts` in the namespace. The Deephaven Helm chart creates these by default; see [Create `Roles` and `RoleBindings`](../sys-admin/kubernetes/kubernetes-install-guide.md#create-roles-and-rolebindings) to check your permissions.
- A `deephaven-helm` package with the Helm charts (including the bundled `deephaven-etcd` and `deephaven-nfs` charts) and support scripts. This guide uses version `VAR::COREPLUS_DHE_VERSION` as an example, though yours may differ.
- A username and password for the `repo.deephaven.io` image repository, used to create an image pull secret. Deephaven's container images (including `deephaven_etcd`) are pulled directly from `repo.deephaven.io`.
  - Alternatively, Deephaven can provide the application images as a `deephaven-containers` package that you push to your own artifact repository (which then also requires `docker` and access to that repository). See [Managing your own images](../sys-admin/kubernetes/kubernetes-install-guide.md#managing-your-own-images). The `deephaven-containers` package does not include the `deephaven_etcd` image, so you still pull it from `repo.deephaven.io` or mirror it separately.
- A TLS webserver certificate and the private key that corresponds to it. The webserver and certificate must meet [Deephaven's requirements](../sys-admin/security/tls-certificates.md#tls-certificate-requirements). The Deephaven installation includes a [LoadBalancer](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types) service (Envoy) that is the entry point for the application. You must create a DNS entry for the hostname associated with this certificate _after_ the installation.

## Set the namespace for your Kubernetes context

If you haven't already, create your Kubernetes namespace and set it to the default for your `kubectl` context.

```bash
kubectl create namespace <your-namespace>
kubectl config set-context --current --namespace <your-namespace>
```

## Unpack the Deephaven Helm chart

Deephaven provides the Helm charts and support scripts in a `deephaven-helm` package. Unpack it:

```bash
tar -xzf deephaven-helm-VAR::COREPLUS_DHE_VERSION.tar.gz
```

If you plan to push the images to your own repository instead of pulling from `repo.deephaven.io` (see [Managing your own images](../sys-admin/kubernetes/kubernetes-install-guide.md#managing-your-own-images)), place the `deephaven-containers-VAR::COREPLUS_DHE_VERSION.tar.gz` package in the same directory; leave it zipped for now.

## Change directory

Run the rest of the commands in this guide from the `helm` subdirectory of the unpackaged Helm distribution.

```bash
cd deephaven-helm-VAR::COREPLUS_DHE_VERSION/helm
```

## Create an 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:

```bash
kubectl create secret docker-registry repo-deephaven-io-imgpull \
    --docker-server='repo.deephaven.io' \
    --docker-username='<username>' \
    --docker-password='<password>'
```

The Deephaven Helm chart references these images through `image.repositoryUrl` (set to `repo.deephaven.io`) and the pull secret through `imagePullSecrets`; both are configured when [installing the Deephaven Helm chart](#install-the-deephaven-helm-chart).

## Set up an NFS deployment

The Deephaven deployment needs a [read-write-many (RWX)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) store. This quickstart installs the bundled `deephaven-nfs` chart, which deploys an in-cluster NFS server and automatically creates the directory layout Deephaven expects (`db/Systems`, `db/Users`, and an `etcd-backup` directory). To use an existing RWX volume in your environment instead, see [Configure shared storage](../sys-admin/kubernetes/kubernetes-install-guide.md#configure-shared-storage).

The only required value is a storage class for the backing volume. `premium-rwo` is suitable for a [GKE](https://cloud.google.com/kubernetes-engine) environment; for other providers, use, for example, `gp2` for [EKS](https://aws.amazon.com/eks/) or `managed-csi` for [AKS](https://azure.microsoft.com/en-us/products/kubernetes-service). You can list the available storage classes with `kubectl get storageclass`.

```bash
helm install dh-nfs deephaven-nfs-VAR::DH_NFS_HELM_CHART_VERSION.tgz --set pvc.storageClassName=premium-rwo
```

It may take a minute for the NFS pod to become ready — check with `kubectl get pods`. The chart also creates a `ClusterIP` service named `deephaven-nfs`, which you use for the `nfs.server` value when installing the Deephaven Helm chart below.

## Install the etcd Helm chart

The `setup-deephaven-etcd.sh` script in the `setupTools` directory of the `deephaven-helm` package installs the `deephaven-etcd` chart. The following command creates a single-node etcd deployment named `dh-etcd` without backup snapshots, which is suitable for a trial installation. Note the etcd installation name; you need it when installing the Deephaven Helm chart below.

The `deephaven_etcd` image is pulled from `repo.deephaven.io/deephaven_etcd` using the `repo-deephaven-io-imgpull` pull secret you created in [Create an image pull secret](#create-an-image-pull-secret). Install etcd, passing the image repository and that pull secret:

```bash
./setupTools/setup-deephaven-etcd.sh \
    --etcd-name dh-etcd \
    --repository repo.deephaven.io \
    --image-pull-secret repo-deephaven-io-imgpull \
    --replica-count 1 \
    --no-backup
```

> [!NOTE]
> If you mirrored the `deephaven_etcd` image into your own repository instead, use that location for `--repository` and the corresponding pull secret.

## 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.

```bash
kubectl create secret tls deephaven-tls --cert=tls.crt --key=tls.key
```

## Install the Deephaven Helm chart

Install the Deephaven Helm chart with a command similar to the following:

```bash
helm upgrade --install dh-quickstart deephaven \
    --set etcd.release="dh-etcd" \
    --set global.storageClass="standard-rwo" \
    --set nfs.pvPrefix="dhqs" \
    --set nfs.server=$(kubectl get svc deephaven-nfs --no-headers -o custom-columns='IP:.spec.clusterIP') \
    --set image.repositoryUrl="repo.deephaven.io" \
    --set "imagePullSecrets[0].name=repo-deephaven-io-imgpull" \
    --set image.tag="VAR::COREPLUS_DHE_VERSION" \
    --set envoyFrontProxyUrl="dh-quickstart.mydomain.com" \
    --set "envoy.serviceAnnotations.networking\.gke\.io/load-balancer-type"="Internal" \
    --debug
```

Set these properties for your environment:

- `etcd.release`: The name of the etcd release created earlier.
- `global.storageClass`: An appropriate storage class for your Kubernetes environment that allows for auto-provisioning volumes.
- `nfs.pvPrefix`: A prefix prepended to PVC and PV objects.
- `nfs.server`: The IP address of the NFS server. The example command above looks it up from the `deephaven-nfs` service, so you can leave it as is.
- `image.repositoryUrl`: The container registry that holds the Deephaven Docker images. Use `repo.deephaven.io` to pull directly from Deephaven, or your own repository if you pushed the images there.
- `imagePullSecrets[0].name`: The image pull secret created in the [Create an image pull secret](#create-an-image-pull-secret) step.
- `image.tag`: The tag for the Deephaven Docker images to use. This is the Deephaven version, for example, `VAR::COREPLUS_DHE_VERSION`.
- `envoyFrontProxyUrl`: The hostname (DNS entry) for your Deephaven cluster. It should match the hostname in the TLS certificate created earlier.

> [!NOTE]
> Deephaven's primary point of service is the Envoy service load balancer. You can optionally provide annotations for this service, which can affect how it operates.
>
> - You can add arbitrary annotations to the Envoy service with `envoy.serviceAnnotations.<annotation-key>`.
> - The example command's last `--set` option sets an annotation named `networking.gke.io/load-balancer-type`. This annotation is specific to GKE, where it results in a non-external IP address for the Envoy service; it has no effect with other Kubernetes providers.
> - If you do not use an external IP address, you may need certain firewall rules to access the Envoy service in your Kubernetes cluster.
> - Omitting annotations can result in your cluster allocating an external IP address for the Envoy service.

The installation takes a couple of minutes, and `helm` waits for the install job to finish before it returns. To see progress while `helm` is running, tail the log output of the install job from a separate terminal:

```bash
kubectl logs -f job/dh-quickstart-pre-release-hook
```

## Create a DNS entry for the application

Create a DNS entry for the hostname referenced by the TLS certificate. Use the IP address listed under the `EXTERNAL-IP` column of the `kubectl get svc envoy` output. The process for creating a DNS entry varies depending on your Kubernetes provider and infrastructure.

The following example creates a DNS entry in a GCP environment:

```bash
MY_ENVOY_IP=$(kubectl get svc envoy \
    -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
gcloud dns record-sets create dh-quickstart.mydomain.com \
    --ttl=300 --type=A --zone=myzone \
    --rrdatas=${MY_ENVOY_IP}
```

## Set a password for the admin user

The installation creates an administrative user named `iris`, which belongs to the `iris-superusers`, `iris-acleditors`, and `iris-schemamanagers` groups. It has no password until you set one. The following block contains two shell commands:

- The first command opens a shell in the management shell pod.
- The second command runs the `dhconfig` command to set the password. This example uses `adminpw1`; replace it with a more secure password of your own.

```bash
kubectl exec -it deploy/management-shell -- bash
/usr/illumon/latest/bin/dhconfig acl users set-password \
    --name iris \
    --hashed-password $(openssl passwd -apr1 adminpw1)
```

To create a separate administrative user instead, first add it with `dhconfig acl users add --name <user> --group iris-acleditors iris-schemamanagers iris-superusers`, then run `set-password` for that user.

## 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. Log in as `iris` with the password you set in the previous step.

![The Deephaven login screen](../assets/quickstart/login.png)

## Related documentation

- [Kubernetes installation guide](../sys-admin/kubernetes/kubernetes-install-guide.md)
- [Kubernetes configuration settings](../sys-admin/kubernetes/kubernetes-configuration-settings.md)
- [Customizing your Kubernetes installation](../sys-admin/kubernetes/kubernetes-customizing-installation.md)
- [etcd backup and recovery guide](../sys-admin/kubernetes/kubernetes-etcd-recovery.md)
- [IAP integration](../sys-admin/kubernetes/kubernetes-iap-integration.md)
- [Ingesting Kafka data in a Kubernetes installation](../data-guide/streaming/kubernetes-kafka-ingestion.md)
- [Merge queries in Kubernetes](../legacy/kubernetes/kubernetes-merge-queries.md)
- [Upgrading Deephaven in a Kubernetes environment](../sys-admin/kubernetes/kubernetes-upgrade-guide.md)
- [Troubleshooting a Kubernetes installation](../sys-admin/kubernetes/troubleshooting-kubernetes.md)
