Helm
Install Hotdata on your own Kubernetes cluster (amd64 or arm64) with one Helm chart from Hotdata's private registry, registry.hotdata.dev.
This guide installs on Amazon EKS with managed AWS services. To try Hotdata on a laptop or test cluster first, see Local development.
Prerequisites
- An EKS cluster with an IAM OIDC provider, a default StorageClass, and outbound HTTPS to
registry.hotdata.dev. kubectlaccess with rights to create a namespace, and Helm 3.8 or later.- In the same VPC as the cluster:
- Amazon RDS for PostgreSQL, with a database and a user that can create tables in it.
- Amazon ElastiCache for Redis, with in-transit encryption.
- An Amazon S3 bucket in the cluster's region.
- Room for the engine: 1 vCPU and 4 GiB of memory requested, up to 2 vCPU and 8 GiB, plus a 100 GiB volume.
Hotdata is built around cloud object storage, so query performance and some caching features depend on it. Managed services also give you backups and high availability.
Step 1: Get your credentials
Hotdata sends you these values through a one-time secure link:
| Value | Example (yours differ) | Used as |
|---|---|---|
| Username | robot$acme | The login name. It always starts with robot$. |
| Token | 4fHq9ZrT2mWbX8nKc1LpV6sYdE3gJ0aU | The password. |
| Version | The version Hotdata sends with each release | The chart version to install. |
Set them once in your shell:
export HOTDATA_USER='robot$acme'
export HOTDATA_TOKEN='4fHq9ZrT2mWbX8nKc1LpV6sYdE3gJ0aU'
export HOTDATA_VERSION='<version>'
echo "$HOTDATA_USER" # must print robot$acme, not robot
If you received a JSON file (robot$acme.json) instead, load the two values from it (needs jq):
export HOTDATA_USER=$(jq -r .name 'robot$acme.json')
export HOTDATA_TOKEN=$(jq -r .secret 'robot$acme.json')
Store the token in your secret manager. If it leaks, ask Hotdata for a new one. The old token stops working as soon as the new one is issued.
Step 2: Log in
-
Log Helm in to the registry, so it can download the chart:
printf '%s' "$HOTDATA_TOKEN" | helm registry login registry.hotdata.dev \ -u "$HOTDATA_USER" --password-stdinExpected output:
Login Succeeded. -
Create the namespace and a pull secret, so your cluster can download the engine image:
kubectl create namespace hotdata kubectl -n hotdata create secret docker-registry hotdata-registry \ --docker-server=registry.hotdata.dev \ --docker-username="$HOTDATA_USER" \ --docker-password="$HOTDATA_TOKEN"
The steps below use namespace hotdata and release name hotdata-core. You can use other names, but the Service name follows the release name.
Step 3: Install
-
Create an IAM role for the
hotdata-coreservice account in namespacehotdata(IRSA), with read and write access to your bucket. Hotdata uses this role for S3, so you store no AWS keys. -
Store the RDS password and the ElastiCache URL in the namespace:
kubectl -n hotdata create secret generic hotdata-postgres \ --from-literal=password='<rds password>' kubectl -n hotdata create secret generic hotdata-redis \ --from-literal=url='rediss://:<auth token>@<primary endpoint>:6379/0' -
Write
hotdata-values.yaml:image: pullSecrets: [hotdata-registry] runtimedb: auth: allowUnauthenticated: true # private network only; see below postgres: mode: external external: host: hotdata.abc123.us-east-1.rds.amazonaws.com database: hotdata user: hotdata # needs rights to create tables existingSecret: hotdata-postgres sslMode: require redis: mode: external external: existingSecret: hotdata-redis storage: mode: external bucket: acme-hotdata region: us-east-1 external: useIrsa: true serviceAccount: annotations: eks.amazonaws.com/role-arn: arn:aws:iam::<account id>:role/<role name> -
Install:
helm install hotdata-core oci://registry.hotdata.dev/hotdata/hotdata-core \ --version "$HOTDATA_VERSION" --namespace hotdata -f hotdata-values.yaml
Authentication. The chart refuses to install without an authentication choice:
allowUnauthenticated: truelets anyone who can reach the Service query it. The chart creates an internalClusterIPService and no ingress.- To validate tokens instead, set
runtimedb.auth.mode: required,jwksUrlto your identity provider's JWKS URL, andworkspaceIdto the value Hotdata gives you. Contact Hotdata to set this up.
To see every setting, run helm show values oci://registry.hotdata.dev/hotdata/hotdata-core --version "$HOTDATA_VERSION".
kubectl -n hotdata get secret hotdata-core-env \
-o jsonpath='{.data.RUNTIMEDB_SECRET_KEY}' | base64 -d
Step 4: Verify
The first start takes a few minutes while Hotdata sets up its database.
Wait until every pod is Running and ready, then run the chart's test:
kubectl -n hotdata get pods -w
helm test hotdata-core -n hotdata # Phase: Succeeded
The API listens on port 3000 of the hotdata-core Service, inside your cluster.
Local development (optional)
To try Hotdata on a laptop (Docker Desktop, kind, minikube) or a test cluster, one command runs Postgres, Redis and S3-compatible object storage inside the release. Do Steps 1 and 2 first, then:
helm install hotdata-core oci://registry.hotdata.dev/hotdata/hotdata-core \
--version "$HOTDATA_VERSION" \
--namespace hotdata \
--set 'image.pullSecrets[0]=hotdata-registry' \
--set runtimedb.auth.allowUnauthenticated=true
This setup needs about 2 vCPU, 5 GiB of memory and 325 GiB of disk. It pulls the bundled service images from Docker Hub.
Some caching features are off without cloud object storage, so expect slower queries than in production.
Upgrades and uninstall
To upgrade, set HOTDATA_VERSION to the new version and run:
helm upgrade hotdata-core oci://registry.hotdata.dev/hotdata/hotdata-core \
--version "$HOTDATA_VERSION" --namespace hotdata -f hotdata-values.yaml
Back up your Postgres database before an upgrade: a new version can change its schema.
To remove Hotdata:
helm uninstall hotdata-core -n hotdata
Uninstall deletes the engine's volume. Your data stays in RDS and S3.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
403 ... accepts only Hotdata robot accounts | The username lost its robot$ prefix, usually because the shell expanded $. Quote the username in single quotes. |
401 Unauthorized at login | Wrong or revoked token. Copy it again without spaces, or ask Hotdata for a new one. |
helm install says the chart version is not found | Check the version Hotdata sent. Run helm registry login again: a new shell may not have the login. |
Engine pod in ImagePullBackOff | The pull secret is missing, in another namespace, or has an old token. Check with kubectl -n hotdata describe pod <pod>, then recreate hotdata-registry. |
| Install stops with a StorageClass error | The cluster has no default StorageClass. Set one, or name one with --set runtimedb.persistence.storageClass=<name> and the same setting under postgres.bundled, redis.bundled and storage.bundled. |
| Install stops with an auth error | No authentication choice was made. Set runtimedb.auth.allowUnauthenticated=true or configure JWT validation. |
PVC stays Pending | The StorageClass cannot provision the size asked for. Check kubectl -n hotdata describe pvc. |
Engine logs an io_uring error at start | A seccomp profile blocks io_uring. Allow it for the engine pod. |
| Engine restarts during first start | It cannot reach Postgres, Redis or storage. Read kubectl -n hotdata logs deploy/hotdata-core. |
For anything else, send Hotdata support the output of kubectl -n hotdata get pods and the engine logs. Never include your token.