Self-Managed Kubernetes
A Self-Managed Kubernetes data plane runs on a Kubernetes cluster you operate, with an S3-compatible object store. There is no Terraform customer stack. You create the cluster, the bucket and the ZooKeeper ensemble yourself, and onboarding is a form plus one helm install.
Before you start, complete the Self-Managed Kubernetes prerequisites and the checklist.
Onboarding Flow
- Create the project with the Self-Managed Kubernetes project type.
- Prepare your cluster: enter its StorageClass and ZooKeeper connection string.
- Connect object storage: enter the S3 endpoint and access key.
- Install the connect chart and wait for the preflight checks to pass.
- Provisioning: Onehouse validates bucket access and deploys the data plane into your cluster.
Step 1: Create the Project
Create a new project and choose Self-Managed Kubernetes as the project type. There is no region or deployment-mode choice; the cluster runs wherever you run it. If the option isn't shown, contact your Onehouse account team to enable it for your account.
Open Connections > Cloud Accounts and start the setup wizard.
Step 2: Prepare Your Kubernetes Cluster
The first wizard step lists the node labels, storage, object storage, ZooKeeper and egress requirements from the prerequisites page. Confirm your cluster meets them, then enter:
| Field | Value |
|---|---|
| Storage class | The StorageClass for Prometheus and Alertmanager volumes, for example longhorn. It must use a CSI provisioner that supports volume expansion. |
| ZooKeeper connection string | Your ensemble as host:port,host:port,host:port. |
Onehouse saves both when you continue and registers the ensemble as this data plane's lock provider.
Step 3: Connect Object Storage
| Field | Value |
|---|---|
| S3 endpoint URL | https://<your-endpoint>[:port]. HTTPS only, with a publicly trusted certificate for a DNS name. |
| Access key ID / Secret access key | A key with read, write, list and delete permission on the bucket the wizard shows. |
| Signing region | Leave unset to use us-east-1. Change it only if your store rejects that value. |
The bucket named in the wizard (onehouse-customer-bucket-<prefix>) must already exist on this endpoint.
Onehouse stores the access key in its own secret manager. It is never placed in the Helm values file or written into your cluster by the connect chart. To rotate the key later, submit this step again with the new key. Leave the secret blank to keep the stored one.
Step 4: Install the Connect Chart
Download onehouse-values.yaml from the wizard. It carries your S3 endpoint, bucket name, ZooKeeper servers and the egress hosts to check, but never the access key.
With a kubeconfig that has cluster-admin on your cluster, run the command the wizard shows. It pins the chart version for your environment:
helm -n oh-dpconnect install byok-dp-connect \
oci://registry-1.docker.io/onehouse/byok-dp-connect \
--version <chart-version> \
-f onehouse-values.yaml \
--create-namespace
The chart creates the onehouse-admin ServiceAccount with a cluster-admin binding and starts a connect job (byok-dpconnect-job in the oh-dpconnect namespace). The job opens an outbound tunnel to Onehouse and checks your cluster.
Preflight results
The wizard shows what the connect job finds, refreshed every few seconds:
| Group | Checks |
|---|---|
| Node labels: required to connect | At least one Ready node carries oh-essential-pods, monitoring-pods and pool=job-workers-repair, together with an oh-instance-type label. Any node with a role label but no oh-instance-type also fails this group. |
| Node labels: workloads | Ready node counts for driver-pods, job-workers and sql-workers. Informational here; enforced when you create a compute cluster. |
| Storage | The StorageClass exists. The S3 endpoint resolves, connects and presents a trusted certificate. The bucket exists. |
| Network egress | Each required host is reachable. Optional hosts are reported separately and don't block onboarding. |
| Lock provider | Each ZooKeeper server accepts a TCP connection on its port. |
Next becomes available when every required check passes. If a check fails, fix it in your cluster, for example by running the kubectl label command shown. The connect job keeps checking and picks up the fix within about 2 minutes, with no re-install.
If the panel says Re-install needed, the job was installed with a values file this project no longer accepts. Download a fresh onehouse-values.yaml, then delete the finished job and upgrade the chart:
kubectl delete job byok-dpconnect-job -n oh-dpconnect
helm -n oh-dpconnect upgrade byok-dp-connect \
oci://registry-1.docker.io/onehouse/byok-dp-connect \
--version <chart-version> \
-f onehouse-values.yaml
The connect job's pod template cannot change while the job exists, so helm upgrade alone does not re-run it.
Step 5: Provisioning
Onehouse first validates that it can read and write your bucket with the access key you entered. It then deploys the Onehouse agent, monitoring stack, Spark operator, YuniKorn and the rest of the data plane into your cluster over the tunnel. Onehouse keeps the Terraform state for these components in your bucket.
When provisioning completes, the cloud account appears under Connections > Cloud Accounts and Onehouse creates the default compute clusters on the node types it found.
If this step stays stuck or fails, contact your Onehouse team.
After Onboarding
Node types
Project Settings → Node Types lists one row per oh-instance-type value, with the vCPU and memory Onehouse read from the nodes and the role labels they carry. Two settings are yours to edit on each node type:
- DaemonSet reservation: CPU and memory to hold back for your own DaemonSets on those nodes. Prefilled from what's observed.
- Local scratch: the host path and capacity of a local scratch disk, if you prepared one.
The size of a node type always comes from its nodes. A compute cluster copies its node type when it is created or edited, so a reservation change reaches an existing cluster the next time you edit that cluster.
Compute clusters
When you create a compute cluster, you pick a node type for the driver and for the workers instead of a cloud instance type. Each picker lists only node types whose nodes carry the label that cluster type schedules onto:
| Cluster type | Driver label | Worker label |
|---|---|
| Managed, Table Optimizer | driver-pods | job-workers |
| SQL, Spark, PySpark, Lakecache | sql-workers | sql-workers |
| Open engines | openengine-trino, openengine-flink or openengine-ray-cpu | same |
Onehouse never adds nodes. If Max OCU is larger than the Ready nodes of the chosen node type can hold, the form warns you and jobs wait for capacity. Usage is metered from the CPU of running Onehouse pods, never from nodes, so sharing nodes with your own workloads does not affect billing.
Adding nodes
Label new nodes (oh-instance-type plus role labels) before or as they join. Onehouse picks them up within 5 minutes. Don't put nodes of different sizes under one oh-instance-type value: the node type freezes at its last consistent size until they match.
Kafka sources
Add your Kafka broker hostnames to Project Settings → Host Pattern Allowlist before creating the source, and make sure the brokers are reachable from the cluster.
Support Matrix
| Area | Supported |
|---|---|
| Sources | Apache Kafka, Confluent Cloud Kafka, Confluent Cloud CDC, Existing Onehouse Tables |
| Flows | Hudi writes, single- and multi-writer (concurrency control via your ZooKeeper), metadata table |
| Table services | Clustering, compaction, cleaning, indexing, Table Optimizer, table service monitoring |
| Catalogs | Onehouse Catalog (recommended), Hive, DataHub, OneTable, Snowflake, Snowflake Open Catalog, Unity |
| Compute clusters | Managed, SQL, Spark, PySpark, Lakecache, Table Optimizer |
| Discovery and observability | Table autodiscovery, Spark history server and event logs, Grafana, LakeView |
| Data plane apps | Spark UI and history server, Grafana, JupyterHub (shared password) and notebook Spark UIs, served through the Onehouse console |
| Secrets | Onehouse-managed secrets for sources, catalogs and schema registries |
| Object storage | S3-compatible stores with a publicly trusted certificate; NetApp StorageGRID validated |
| Lock provider | Your ZooKeeper 3.5+ ensemble, unauthenticated |
What Onehouse Does Not Manage
- Cluster lifecycle: Kubernetes version and upgrades, CNI, admission control, node OS hardening and Pod Security policy.
- Node capacity: Onehouse never creates, scales, labels or tags a node, and runs no autoscaler.
- Storage: the StorageClass provisioner, the object store and its bucket.
- ZooKeeper: sizing, high availability, upgrades and backups.
Converting an existing AWS, Google Cloud or Azure project to Self-Managed Kubernetes (or back) is not supported. The project type is fixed when the project is created.