Kubernetes
This guide covers how to get started with Deephaven quickly in a Kubernetes environment. Commands are shown for running in a Unix-like environment.
Note
This installation is intended for trial use only. System defaults are used throughout this document, which are not suitable for many production environments. For complete coverage of the Deephaven Kubernetes installation, see the Kubernetes installation guide.
Prerequisites
Before deploying Deephaven Enterprise with Kubernetes, you need the following prerequisites:
- A Kubernetes cluster, with a dedicated namespace created for the Deephaven installation.
kubectl
,docker
andhelm
command line tools.- An artifact repository to which Docker images can be stored and from which Kubernetes pods may pull them.
- Two Deephaven distributable packages, one containing a helm chart and another containing Docker images. This guide uses version
1.20240517.344
as an example, though yours may differ. - 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.
Start by creating your Kubernetes namespace and setting it to the default if you have not already done so.
kubectl create namespace <your-namespace>
kubectl config set-context --current --namespace <your-namespace>
Unzip the Deephaven helm chart
There are two tar files required to install Deephaven in Kubernetes. They should have been given to you by a Deephaven team member. Place the two files in the same directory: a deephaven-helm
package and a deephaven-containers
package.
ls *.gz
deephaven-containers-1.20240517.344.tar.gz
deephaven-helm-1.20240517.344.tar.gz
Unpack the deephaven-helm
package only, as it contains some scripts as well as a Docker directory tree with Dockerfiles for users who wish to build their own container images. The deephaven-containers
package will remain zipped up.
tar -xzf deephaven-helm-1.20240517.344.tar.gz
Push the Deephaven images to your image repository
First, load the images to your local Docker repo.
docker image load -i deephaven-containers-1.20240517.344.tar.gz
Next, push the images to your artifact repository using the pushAll.sh
script found in the unzipped deephaven-helm
package.
Note
Keep the full path to your artifact repository handy, as you will need it for another step. This example uses the fake image URL my-repo.dev/my-project/images/deephaven-quickstart
that you will replace with your own.
./deephaven-helm-1.20240517.344/docker/pushAll.sh --source-tag 1.20240517.344 my-repo.dev/my-project/images/deephaven-quickstart 1.20240517.344
Set up an NFS deployment
The Deephaven deployment needs a read-write-many (RWX) store. While that store is not part of the Deephaven helm chart itself (and you may choose to use an available one in your environment), the helm distribution contains the manifest files to easily create an NFS server for this purpose.
The rest of the commands in this guide must be run from the helm subdirectory of the unpackaged helm distribution.
cd deephaven-helm-1.20240517.344/helm
The default storage class defined in setupTools/nfs-server.yaml
is premium-rwo
, which is suitable for a GKE environment. For instance, set the storage class to gp2
for EKS, managed-csi
for AKS.
Once the storage class is set, apply the files to create the deployment.
kubectl apply -f setupTools/nfs-server.yaml
kubectl apply -f setupTools/nfs-service.yaml
It may take a minute to start up the pod. You can check its status with kubectl get pods
. Once it is running, the following commands prepare it for use.
MY_NFS_POD=$(kubectl get pods -l role=deephaven-nfs-server --no-headers -o custom-columns="NAME:.metadata.name")
kubectl cp setupTools/setup-nfs-minimal.sh $MY_NFS_POD:/setup-nfs-minimal.sh
kubectl exec $MY_NFS_POD -- bash -c "export SETUP_NFS_EXPORTS=y && chmod 755 /setup-nfs-minimal.sh && /setup-nfs-minimal.sh"
Install the etcd helm chart
Deephaven depends on a bitnami etcd helm deployment. Set up a deployment named dh-etcd
with these commands.
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install dh-etcd bitnami/etcd --values setupTools/etcdValues.yaml
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.
kubectl create secret tls deephaven-tls --cert=tls.crt --key=tls.key
Install the Deephaven helm chart
You can now install the Deephaven helm chart with the command below.
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="my-repo.dev/my-project/images/deephaven-quickstart" \
--set image.tag="1.20240517.344" \
--set envoyFrontProxyUrl="dh-quickstart.mydomain.com" \
--set "envoy.serviceAnnotations.networking\.gke\.io/load-balancer-type"="Internal" \
--debug
Note
- If you are setting an annotation property with a
.
in the name with--set
, then you must escape them with a\
and enclose the entire value in double quotes. - Deephaven's primary point of service is the Envoy service load balancer. You can optionally provide annotation for this service, which can affect how it operates.
- Omitting annotations can result in your cluster allocating an external IP address for the Envoy service.
- If you do not use an external IP address, you may need certain firewall rules to access the Envoy service.
- You can set arbitrary properties on the Envoy service by prefacing the property with
envoy.serviceAnnotations
. - The example command sets a property named
networking.gke.io/load-balancer-type
. In GKE environments, this results in a non-external IP address for the Envoy service.
You must provide your own values for these properties:
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 that will be prepended to pvc and pv objects.nfs.server
: The IP address of the NFS server. The example below uses a command to find it dynamically and can be left as is.image.repositoryUrl
: The URL of the container registry that holds the Deephaven Docker images.image.tag
: The tag for the Deephaven Docker images to use. This tag was set when the images were pushed.envoyFrontProxyUrl
: The hostname/DNS entry used for your Deephaven cluster. It should match the hostname in the TLS certificate created earlier.
The installation takes a couple of minutes. You can see progress by tailing the log output of the install job with the command:
kubectl logs -f job/dh-quickstart-pre-release-hook
Create a DNS entry for the application
A DNS entry is required for the hostname referenced by the TLS certificate. It should use the IP address listed under the EXTERNAL-IP
column after running kubectl get svc envoy
. The process for creating a DNS entry varies depending on your Kubernetes provider and/or infrastructure.
The following command creates a DNS entry in a GCP environment.
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 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. It sets it toadminpw1
, but you are encouraged to provide your own that is more secure.
kubectl exec -it deploy/management-shell -- bash
/usr/illumon/latest/bin/dhconfig acl users set-password --name iris --hashed-password $(openssl passwd -apr1 adminpw1)
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.
Note
The URL example above uses port 8000
. Use port 8000
for servers with Envoy and port 8123
for servers without Envoy.
Related documentation
- Kubernetes installation guide
- Kubernetes configuration settings
- Customizing your Kubernetes installation
- Etcd backup and recovery guide
- IAP integration
- Ingesting Kafka data in a Kubernetes installation
- Merge queries in Kubernetes
- Upgrading Deephaven in a Kubernetes environment
- Troubleshooting a Kubernetes installation