Getting Started›Helm

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.
  • kubectl access 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:

ValueExample (yours differ)Used as
Usernamerobot$acmeThe login name. It always starts with robot$.
Token4fHq9ZrT2mWbX8nKc1LpV6sYdE3gJ0aUThe password.
VersionThe version Hotdata sends with each releaseThe 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

  1. 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-stdin
    

    Expected output: Login Succeeded.

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

  1. Create an IAM role for the hotdata-core service account in namespace hotdata (IRSA), with read and write access to your bucket. Hotdata uses this role for S3, so you store no AWS keys.

  2. 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'
    
  3. 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>
    
  4. 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: true lets anyone who can reach the Service query it. The chart creates an internal ClusterIP Service and no ingress.
  • To validate tokens instead, set runtimedb.auth.mode: required, jwksUrl to your identity provider's JWKS URL, and workspaceId to 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

SymptomCause and fix
403 ... accepts only Hotdata robot accountsThe username lost its robot$ prefix, usually because the shell expanded $. Quote the username in single quotes.
401 Unauthorized at loginWrong or revoked token. Copy it again without spaces, or ask Hotdata for a new one.
helm install says the chart version is not foundCheck the version Hotdata sent. Run helm registry login again: a new shell may not have the login.
Engine pod in ImagePullBackOffThe 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 errorThe 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 errorNo authentication choice was made. Set runtimedb.auth.allowUnauthenticated=true or configure JWT validation.
PVC stays PendingThe StorageClass cannot provision the size asked for. Check kubectl -n hotdata describe pvc.
Engine logs an io_uring error at startA seccomp profile blocks io_uring. Allow it for the engine pod.
Engine restarts during first startIt 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.