Clusters

Add a cluster before creating storage or deploying a model. Use its kubeconfig to connect an existing cluster, or use Kubespray to create one on your machines.

Before you begin: proxy exclusions

If Kubernetes components use an HTTP(S) proxy, keep cluster-internal traffic off it. Set NO_PROXY and no_proxy to the same value, preserving existing exclusions and including localhost, node hostnames/IPs, the API server address, Service/Pod CIDRs, and cluster DNS suffixes. Example (replace the placeholders and adapt cluster.local if your cluster uses a different DNS domain):

localhost,127.0.0.1,::1,<node-hostnames-and-IPs>,<api-server-host>,<service-CIDR>,<pod-CIDR>,.svc,.svc.cluster.local,cluster.local

Verify these settings on the running kube-apiserver process, not just in a shell or Lens. For kubeadm, configure its environment in /etc/kubernetes/manifests/kube-apiserver.yaml; kubelet recreates the static Pod, briefly interrupting API access. Keep manifest backups outside that directory. CIDR exclusions alone do not cover Service DNS names: missing DNS exclusions can route webhook calls through the proxy and cause TLS errors or timeouts.

Register a cluster from a kubeconfig

1. Open Clusters and click Add.
2. Enter Cluster name. Keep I already have a kubeconfig, click Browse, and choose the file.
3. Click Next. If connection or version checks fail, correct the reported problem before continuing.
4. On Network Proxy, keep Auto-detect this cluster's proxy (recommended). To supply a proxy, choose Custom proxy for this cluster and fill in the proxy fields.
5. On Model gateway, keep Provider on Istio and check the addresses using the table below.
6. On Accelerator, select the accelerator types installed in the cluster and their driver access modes.
7. On llm-d stack, review the listed versions and click Next. Wait for source downloads and image preparation to finish.
8. On Model Cache, keep the suggested secret namespace/name and paste a HuggingFace token from your Hugging Face settings. To prepare a cache now, select Create a storage volume for model-cache on this cluster and fill in its path and capacity.
9. Click Review, check the summary, then click Finish.
10. Wait for the operations to finish and click Done. Select the cluster in the list and check Workers and Deployable GPU.

Model gateway field	What to enter
Gateway exposed port (NodePort)	The port clients will use to call models
Gateway host/IP	A host or IP reachable by clients; leave blank to let Lens derive it
Lens address	The Lens host or IP reachable from the cluster; keep the auto-filled address if it is reachable
Node inotify limit	Keep the initial value unless your administrator requires a different limit

The wizard installs software and prepares images on cluster nodes. Run it against a cluster you are authorized to manage. A failed preparation step must be corrected before completing the wizard.

Bootstrap a new cluster via Kubespray

1. Open Clusters → Add and enter the cluster name.
2. Choose Bootstrap a new cluster via Kubespray.
3. For each machine, enter Host(s), Port, Role(s), Username, and an SSH private key or SSH password. Use Add node for more machines.
4. Under Network proxy for target nodes, keep Auto to reuse each machine's settings, or choose Custom for these nodes and enter the proxy.
5. Click Run preflight. Fix failed checks and run preflight again until every host passes.
6. Click Start bootstrap and follow its progress.
7. When the generated kubeconfig appears, continue through the registration steps above to Finish and Done.

Bootstrap changes the target machines. Check their addresses and roles before starting.

Edit a cluster

1. Select the cluster, then click Edit cluster.
2. Change its name, description, proxy, HF_TOKEN secret or model-gateway settings.
3. Click Save changes and check that the updated values appear.

Component versions are supplied by the Lens release and are not editable here.

Rotate the HF_TOKEN secret

HF_TOKEN secret holds the Hugging Face token this cluster uses to pull gated models. Lens stores only the Secret's namespace and name; the token value lives on the cluster and is never shown again.

1. Leave New token empty to keep the current token. Type a token only when you want to replace it.
2. Change Namespace or Secret name only to point the cluster at a different Secret; Lens creates that Secret when it does not exist yet.
3. Click Save changes. The confirmation names the Secret that was written.

Deployments and Model Cache downloads copy the token into their own namespace when they run, so workloads that are already running keep the previous token until you recreate them.

Check model gateway access

1. In Clusters → Edit cluster, check Gateway host/IP and Gateway exposed port against the address clients can reach.
2. Open Model services and locate this cluster's Gateway node.
3. Open the node menu and choose Install if the gateway is absent, or Reconcile to apply its saved settings.
4. Follow the operation logs, then publish a model service and send a request.

If installation or requests fail, use Troubleshooting. The create/edit wizard currently offers Istio; instructions for manually repairing other providers belong to troubleshooting, not the normal registration flow.

Review cluster health

The cluster list refreshes quietly every five seconds while the page is visible. The selected cluster's health refreshes every five seconds; other clusters' health refreshes every ten seconds. No manual refresh is needed. List refreshes preserve the current selection and search, and retain existing entries with an error message if an update fails.

1. Select a cluster in Clusters.
2. Check Workers, CPU, Memory, Deployable GPU, VRAM, Disk, and Monitoring. Memory and Disk lead with the capacity still free out of the cluster total, and show the percentage already in use on the Usage line below. A dash means the cluster cannot report that reading right now, not that nothing is free.

Clusters shows infrastructure health and worker nodes, not deployment lists or individual deployment failures. Click Deployments below Deploy a model in the Target cluster panel to open the Deployments page with the selected cluster already set in its filter. You can change or clear that filter; the entry URL preserves it on reload. Use that page to manage deployments, endpoints and logs. Deployment monitoring and profiling remain available through Observability.

Click Model services below Deployments to open Model services with the same cluster preselected in the service-flow filter. This filter can also be changed or cleared, and its entry URL restores the cluster on reload or browser history navigation.

When accelerators use DRA, Lens reads their model from ResourceSlice device attributes even if nodes do not have GPU product labels. The reported model is used to select the matching AIConfigurator system for hardware-aware recommendations.

Put worker nodes into maintenance mode

1. In the cluster's Workers list, select the nodes.
2. Click Enter maintenance mode, review the names, then click Cordon nodes.
3. After maintenance, select the nodes, click Exit maintenance mode, and confirm Uncordon nodes.

Cordon stops new pods from being scheduled; it does not stop or move existing pods. Plan any required workload shutdown or migration separately.

Delete a cluster registration

1. Open the cluster's Actions → Delete cluster.
2. Check the cluster name and the deletion warning.
3. Click Delete and confirm the registration disappears from the list.

Deletion also removes this registration's isolated Gateway namespace, normally lens-gateway-<cluster-id>, including its Gateway, IPP and authorization resources. The old shared lens-gateway namespace and other registrations' namespaces are left alone. If Gateway namespace deletion fails or times out, Lens reports the error and keeps the registration and credentials so you can retry.

Lens also cleans up what it created on the cluster. The cluster's HF_TOKEN secret is deleted, and its namespace goes with it when keeping the namespace would serve no purpose: Lens created the namespace, or the secret was the only thing in it. If the namespace still holds anything else, it is kept, and the cluster's built-in namespaces are never touched. For a cluster you are still registering, any storage volume created during the wizard is removed together with its PVC and PV, while model files on NFS or hostPath are kept. A fully registered cluster that still has storage volumes cannot be deleted until you delete those volumes first.

Cannot see a cluster?

Ask an administrator to check your cluster assignment. Maintainers manage assigned clusters; administrators can manage all clusters.