Skip to content

Get started with the Helm chart

With the Helm chart you run the Polars Nanook cluster yourself, on your Kubernetes cluster, and point the client at it with a ClusterContext. Connect a quickstart cluster to a workspace in two steps, then run a first remote query. Before you start, install the client and sign up.

You need a running Kubernetes cluster with at least 10 GiB of free memory, such as Amazon EKS, Azure AKS, Google GKE, or minikube started with --memory 12g, and the kubectl and Helm CLIs.

Step 1: Create a service account

The cluster registers with your workspace through a service account: a client ID and secret for the workspace.

Open Integrations > Infrastructure in the portal sidebar and click Connect on the Kubernetes card. The Create service account step generates a service account. Copy the client ID and secret: they are shown only once. The portal fills them in, together with your workspace ID, in the Helm command of step 2.

nanook service-account create \
  --workspace-name "My workspace" \
  --name polars-kubernetes

The command prints the API client ID, the API secret and the Workspace ID you need in step 2. Store the secret: it is shown only once.

Step 2: Install the Helm chart

Install the chart with the workspace ID and the service account credentials from step 1:

helm repo add polars-inc https://polars-inc.github.io/helm-charts
helm repo update

helm upgrade --install polars polars-inc/polars \
  --set clusterId="My First Cluster" \
  --set license.onPrem.enabled=true \
  --set license.onPrem.workspaceId=<WORKSPACE_ID> \
  --set license.onPrem.clientId=<CLIENT_ID> \
  --set license.onPrem.clientSecret=<CLIENT_SECRET> \
  --set scheduler.deployment.runtimeContainer.resources.requests.memory=1Gi \
  --set worker.deployment.runtimeContainer.resources.requests.memory=4Gi \
  --set worker.deployment.runtimeContainer.resources.limits.memory=4Gi

This deploys a scheduler and two workers with 4Gi of memory each.

Not for production use

This configuration is for a quickstart only. Install with the Helm chart covers the settings to change for production.

Check that all pods are running:

kubectl get pods
Output
NAME                                         READY   STATUS    RESTARTS   AGE
polars-scheduler-xxxxxxxxx-xxxxx             1/1     Running   0          1m
polars-worker-xxxxxxxxx-xxxxx                1/1     Running   0          1m
polars-worker-xxxxxxxxx-xxxxx                1/1     Running   0          1m

Once the scheduler starts, the cluster registers with your workspace. The portal shows Cluster is set up and running, and the cluster appears under Registered clusters on the Kubernetes page. If a step fails, see Error messages.

Step 3: Run a test query

Port-forward the scheduler and the observatory, each in a separate terminal:

kubectl port-forward svc/polars-scheduler 5051:5051

kubectl port-forward svc/polars-observatory 3001:3001

Install the client release listed with the cluster release under Cluster software releases, on Python 3.13.9, the Python release of the chart's runtime (Set up explains why). A cluster context points the query at the scheduler:

ClusterContext · LazyFrameRemote

import polars as pl
import polars_nanook as pn

# The scheduler of the cluster you run, port-forwarded to localhost:5051.
ctx = pn.ClusterContext(uri="http://localhost")

# A regular lazy Polars query; `.remote(ctx)` runs it on the cluster's workers.
result = (
    pl.LazyFrame({"a": [1, 2, 3], "b": [4, 4, 5]})
    .with_columns(pl.col("a").max().over("b").alias("c"))
    .remote(ctx)
    .collect()
)

print(result)
Output
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 4   ┆ 2   │
│ 2   ┆ 4   ┆ 2   │
│ 3   ┆ 5   ┆ 3   │
└─────┴─────┴─────┘

The query runs on the cluster's workers and .collect() streams the result back to the client. Its profile shows up under Queries in the portal and in the cluster's observatory at http://localhost:3001.

See Run a remote query for the ways to handle results and How the distributed engine works for how a query runs across workers.

Remove the cluster

Uninstall the Helm release:

helm uninstall polars

This stops the scheduler and the workers, and the cluster shows as stopped on the Kubernetes page in the portal. The service account stays valid until you delete it in the workspace settings.

Next steps