Connect Your Cluster to Lepton
Register your Kubernetes cluster, install the cluster agent, and add GPU nodes to a BYOK node group.
After you prepare your cluster, connect it to DGX Cloud Lepton. Then add your GPU nodes to a node group. You need the workspace administrator role in Lepton and cluster-admin access to your cluster.
Register the Cluster
- In the Dashboard, open the Kubernetes Clusters page. You can also go to Nodes and select Kubernetes Clusters.
- Select Register Cluster.
- Enter a Cluster name. Use 4 to 20 lowercase letters, digits, or hyphens. Start with a letter, and end with a letter or a digit.
- Select or enter a Provider.
- Optionally, enter a Region.
- Select Generate token.
- Copy the Install command, and record its expiration time.
The Dashboard shows the token only once. The install command contains this token. Do not put the command in shared terminals, screenshots, logs, or support tickets.
Install the Cluster Agent
Review the
access
that you grant to Lepton before you run the command. The cluster agent gets
ongoing cluster-admin access to all of your cluster.
Make sure that your terminal uses the correct cluster:
Run the Install command before the token expires. Then make sure that the Helm release exists, and wait for the Deployment:
Make sure that all containers of the cluster agent Pods are Ready. These commands use the default release name and namespace. If you installed with --release-name= or --namespace=, use your values.
On the Kubernetes Clusters page, wait until the cluster status is READY. A Ready cluster agent does not make the cluster Ready, because Lepton must also install its platform components. You can select the cluster for a node group only when its status is READY.
Create a Node Group and Add Nodes
Before you add nodes, move your other applications off them, and add an
operator: Exists toleration to all DaemonSets. Lepton adds a NoExecute
taint to each node that you add, and Kubernetes evicts the Pods that do not
tolerate it. See Prepare GPU Nodes and
DaemonSets.
- On the Nodes page, select Create Node Group, and then select BYOK.
- Enter the Node group name.
- Under Kubernetes Cluster (BYOK), select your cluster. You can select only clusters that are Ready.
- Keep the default Kubernetes runtime.
- Optionally, select the Accelerator Type. If you leave it empty, Lepton detects the type. You cannot change it after you create the node group.
- Review Used By and Visible To.
- Optionally, enable Auto Pause Schedule. Then Lepton stops scheduling on unhealthy nodes. If you also enable Auto Reboot, Lepton can reboot an unhealthy node that has no workloads.
- Create the node group.
- Open the Nodes tab of the node group.
- Select Add Nodes.
- Select the GPU nodes that you prepared. Their Adoption Status must be Adoptable, and Kubernetes Ready must be Ready. If a node shows Unadoptable, hover over the status to see the reason.
- Submit the request.
- Review the result for each node. A Failed result does not cancel the other requests. Correct the problem, and then add that node again.
Requested means that Lepton accepted the request and continues the work in the background. It does not mean that the node is ready for workloads. Select Done. Then wait until each node shows Healthy in the node group. Make sure that the Kubernetes Node is still Ready:
You can also add nodes with a label. The Add Nodes dialog shows the label for the node group, in the form byok.lepton.ai/target-dng=<node-group-id>. Lepton adds the labeled nodes to the node group. Prepare these nodes in the same way.
Run Your First Workload
Follow the Batch Job guide. Select your BYOK node group and a GPU resource shape. Make sure that the job starts in the node group, completes its GPU work, and writes the expected logs.
Troubleshoot the Connection and Node Addition
| Symptom | What to do |
|---|---|
| Cluster agent Pods stay Pending | Examine the Pod events and the available node capacity. The cluster agent runs two replicas, each on a different node. |
| Cluster agent shows ImagePullBackOff | Make sure that the cluster can reach the image registry. Examine the image pull credentials. |
| Cluster status stays PENDINGREGISTRATION | Examine the bootstrap logs and the outbound connections. If the token expired, select Renew to get a new install command. If the agent release already exists, add --upgrade to the new command. |
| Cluster agent is Ready, but the cluster does not become READY | The status can show JOINING, NOSERVINGTUNNEL, or OFFLINE. Examine the prerequisites. Then contact Lepton support with the cluster name and status. Do not delete the cluster and register it again. |
| Node stays Requested | Remove the taints other than nvidia.com/gpu, and uncordon the node. Lepton waits while other taints are on the node. If another controller added a taint, find its source before you remove it. |
| Node does not become Healthy | Make sure that the GPU Operator Pods in the gpu-operator namespace and a Node Feature Discovery worker are Ready on the node. On GB200 and GB300 nodes, also examine the DRA kubelet plugin and the nvidia.com/gpu.clique label. |
To diagnose the cluster agent, collect its Pod events and recent logs:
When you contact support, give this information:
- The workspace name.
- The cluster and node group names.
- The names of the affected Nodes.
- The time of the operation.
- The errors that the Dashboard shows.
Do not give registration tokens or Secret contents.