Enrol a cluster
Register a GPU cluster in the console, install the cluster-setup chart, and check that the operator connected and devices appear.
Enrolling connects a Kubernetes cluster to the plane so Wingsmith can see its GPUs and run models on it. It is a single procedure: register the cluster, take its values file, install the chart, verify.
Enrolment is done in the console. There is no hgr command to register a cluster or mint its token.
Before you start
- A running control plane with
HANGAR_HUB_PUBLIC_URL,HANGAR_OPERATOR_IMAGE,HANGAR_AGENT_IMAGEandHANGAR_SETUP_CHART_REFset. The console builds the cluster’s values and install command from them. - A Kubernetes cluster, 1.29 or later, with schedulable NVIDIA GPUs (
nvidia.com/gpu) and a ReadWriteMany storage class for model weights. helmandkubectlpointed at that cluster, and nodes that can pull the operator and agent images.- For a cluster that will serve models, a deployed gateway and
HANGAR_TUNNEL_GATEWAYset on the plane.
Procedure
Register the cluster
In the console, open Clusters and choose Register cluster.
| Field | What |
|---|---|
| Name | the cluster’s identifier. It becomes cluster.id in the chart values, so it must match exactly |
| Display name | a human label |
| Region, Zone | where the cluster is, for example eu-central-1 and a |
| Residency | the data residency domain used by placement, for example eu |
| Phase | leave the default |
The cluster appears as not enrolled, with sync state never_connected. See Clusters for what these fields mean.
Generate the enrolment token
Open the cluster’s page and choose Generate enrollment token. The plane stores a hash and shows the token once, folded into the values file. Each cluster has its own token. There is no shared fleet token.
The same token is the operator’s identity on the hub, the agent’s identity on the gateway tunnel, and the metrics agent’s write password. Rotate token invalidates the old one everywhere at once. Install the new values and the pods that hold it restart.
Save the values file
The page renders values.<name>.local.yaml. Download or copy it. The top block is filled in by the plane:
cluster:
id: eu-west-a1
hubUrl: wss://hub.example.com/v1/hub/sync
region: eu-central-1
readOnly: false
enrolmentToken:
value: <shown once>
frontend:
mode: none
It also carries the operator image from HANGAR_OPERATOR_IMAGE, an agent block with enabled: false and the gateway address when HANGAR_TUNNEL_GATEWAY is set, and a monitoring block when the plane has a metrics write URL.
The file contains the token. Keep it out of version control. The chart’s .helmignore keeps *.local.yaml out of packaged charts.
Fill in the cluster's facts
Below the divider is a commented skeleton. Fill in what is true of this cluster.
| Values | What |
|---|---|
pools.labelKey, pools.gpuValue, pools.cacheValue | the node label and the values that mark the GPU pool and the pool that downloads weights. Required. cacheValue must name a pool that exists, or prefetch jobs stay Pending |
pools.cacheTaintKey and the other taint fields | the taints each pool carries. Empty takes the defaults, nvidia.com/gpu and hangar.dev/cache |
modelCache.storageClass | a ReadWriteMany class. Required. A default class is usually ReadWriteOnce and leaves the PVC Pending |
fabric.type, fabric.devices | RDMA fabric for KV transfer: efa on AWS, rdma with fabric.resource elsewhere, empty for none |
hfToken.create, hfToken.value | a Hugging Face token, only for gated weights |
imagePullSecret.* | a registry credential, only if your registry is private |
workloadNamespace.name | where models run. Default dynamo |
Hardware options are explained in Hardware. Every key is in Chart values.
Build and push the images
The chart runs the operator and agent images. If you have not built them yet, follow Build the images. Tag them with the chart’s appVersion, because the chart’s default image tag is that version.
Install the chart
The cluster’s page shows a ready helm upgrade --install command that pulls the chart from HANGAR_SETUP_CHART_REF and names the cluster as --kube-context. If the chart registry is private, it shows the helm registry login step first. Run it from the directory that holds the values file.
The first install of a new cluster must keep frontend.mode: none and agent.enabled: false, which is how the values file arrives. The Dynamo operator applies the DynamoGraphDeployment CRD at runtime, so a fresh install that renders a frontend fails with no matches for kind DynamoGraphDeployment.
Verify the operator connected
Wait for the pods in hangar-system to become ready, then check the cluster:
hgr cluster get <name>
Under observed, sync state changes from never_connected to connected and last sync fills in. The console shows the same on the cluster’s page, which leaves the not-enrolled view.
Check that devices appear
hgr device ls --cluster <name>
Each GPU shows up once the operator has scraped the DCGM exporter and finished its first sync. In the console they are under Devices. See Devices.
Turn on serving (serving clusters only)
Skip this step if the cluster only needs to be observed and managed. To serve models, edit the values file:
frontend:
mode: per-model # per-model, shared or none; choose now
agent:
enabled: true
Then run the same install command again. The agent needs the gateway address, which the values file carries when HANGAR_TUNNEL_GATEWAY is set on the plane.
Changing frontend.mode after models exist means deleting and re-rendering every graph, and every model reloads its weights. Choose the topology now. See Frontend topology.
The chart refuses an agent on a read-only cluster, an agent with no gateway address, an address with a scheme, and an agent with no frontend. See Serving agent.