# Helm Source: https://www.hotdata.dev/docs/helm Site index: https://www.hotdata.dev/llms.txt > **Early access** — The Helm install is in early access. [Book a demo](https://meetings-na2.hubspot.com/eddie-tejeda) for access. 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](#local-development). ## Prerequisites - An EKS cluster with an [IAM OIDC provider](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html), 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: | 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: ```bash export HOTDATA_USER='robot$acme' export HOTDATA_TOKEN='4fHq9ZrT2mWbX8nKc1LpV6sYdE3gJ0aU' export HOTDATA_VERSION='' echo "$HOTDATA_USER" # must print robot$acme, not robot ``` > **Use single quotes** — The username contains a `$`. Without single quotes, the shell drops `$acme`, the username becomes `robot`, and the login fails. If you received a JSON file (`robot$acme.json`) instead, load the two values from it (needs `jq`): ```bash 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: ```bash 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: ```bash 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](https://docs.aws.amazon.com/eks/latest/userguide/associate-service-account-role.html)), 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: ```bash kubectl -n hotdata create secret generic hotdata-postgres \ --from-literal=password='' kubectl -n hotdata create secret generic hotdata-redis \ --from-literal=url='rediss://:@:6379/0' ``` 3. Write `hotdata-values.yaml`: ```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:::role/ ``` 4. Install: ```bash 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"`. > **Back up the secret key** — On first install the chart generates a key that encrypts the data source credentials you store in Hotdata. If it is lost, those credentials cannot be read. Copy it to your secret manager with the command below, or supply your own with `runtimedb.secretKey.existingSecret`. ```bash 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: ```bash 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: ```bash 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. > **Not for data you need to keep** — Uninstalling a local development install deletes all of its data. ## Upgrades and uninstall To upgrade, set `HOTDATA_VERSION` to the new version and run: ```bash 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: ```bash 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 `, 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=` 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.