Skip to main content
Version: main 🚧

Manage connected NVIDIA NVKE clusters

Connect an existing NVIDIA Kubernetes Engine (NVKE) workload cluster to vCluster Platform so you can view the cluster and deploy Apps, Stacks, and telemetry collectors into it. This workflow is separate from installing an NVKE management plane.

Before you begin​

  • Platform v5.0+ and a v0.38+ vcluster CLI.
  • Provision a workload cluster through NVKE, and confirm its nodes are ready using its kubeconfig.
  • Have administrator access to that Kubernetes cluster and permission to connect clusters to Platform.
  • Check agent networking and connectivity for the environment.

Follow the upstream NVKE installation and evaluation guides to provision the cluster. The local simulator can demonstrate connection and application delivery without proving GPU behavior or bare metal provisioning.

NVKE retains ownership of cluster creation, node pools, upgrades, and deletion. This guide doesn't create a cluster with vCluster or replace the NVKE provisioning path. Platform represents the connected Kubernetes cluster as a control plane cluster, even when you only use it as an application destination. You don't need to run additional cluster control planes on the NVKE-created cluster's GPU nodes for this workflow.

Direct access to a connected control plane cluster grants broad permissions. This guide uses platform administrator access. It doesn't cover restricted project-user or tenant access to the connected cluster.

Connect the workload cluster​

The CLI installs the Platform agent into the Kubernetes context you select. Check the context before running the connection command so the agent lands in the NVKE-created cluster.

  1. Log in to the Platform instance used for the evaluation.

    Modify the following with your specific values to generate a copyable command:
    vcluster platform login https://platform.example.com

    Complete the login method configured for that instance.

  2. Check the destination cluster's identity and node readiness.

    Modify the following with your specific values to generate a copyable command:
    kubectl --context nvke-eu cluster-info
    kubectl --context nvke-eu get nodes

    Expect the intended NVKE API endpoint and ready nodes. Resolve node or networking failures through NVKE before connecting.

  3. Connect that cluster with a unique Platform name.

    Modify the following with your specific values to generate a copyable command:
    vcluster platform add cluster nvke-eu --display-name "NVKE Europe" --context nvke-eu

    The command installs the Platform agent. Repeat with distinct names and contexts to connect more clusters.

  4. Check the connected-cluster list.

    vcluster platform list clusters

    Confirm that the name you supplied appears. Open its detail view in the platform UI and check the agent connection status.

For alternative connection methods and agent settings, see Connect a cluster. Use this connected-cluster path rather than a vCluster Standalone join command, which expects an existing standalone installation.

Deploy a Stack to the connected cluster​

Choose a StackTemplate already available in your evaluation environment. For the first check, use an application whose requirements the NVKE cluster already satisfies. A successful non-GPU application deployment is a useful first result before testing GPU workloads.

  1. Connect to the Platform management API.

    vcluster platform connect management

    Create the StackInstance in a project namespace where you have permission to deploy to the connected cluster.

  2. Save the following manifest as nvke-workload.yaml after selecting your template, owner, and connected-cluster name. Add the parameters required by that StackTemplate.

    Modify the following with your specific values to generate a copyable command:
    nvke-workload.yaml
    apiVersion: management.loft.sh/v1
    kind: StackInstance
    metadata:
    name: nvke-workload
    spec:
    displayName: NVKE application evaluation
    owner:
    user: admin
    destination:
    # Use the Platform name, not the Kubernetes context name.
    cluster:
    name: nvke-eu
    templateRef:
    name: REPLACE_WITH_STACK_TEMPLATE
    # Supply the parameters required by the selected StackTemplate.
    parameters: {}
    prunePolicy: Retain
  3. Apply the StackInstance and inspect its phase and task messages.

    Modify the following with your specific values to generate a copyable command:
    kubectl apply -n p-default -f nvke-workload.yaml
    kubectl get stackinstance nvke-workload -n p-default -o yaml

    When every task reports Healthy, the StackInstance reports status.phase: Healthy. If a task fails, the StackInstance reports Degraded. Inspect status.tasks for the failed task and its message. Verify the application in the NVKE cluster itself before calling the deployment successful.

For catalog installation through the UI and task permissions, see Use a Stack.

NVIDIA Dynamo is a possible next workload when the cluster has suitable GPUs, a device plugin, model access, and storage. The Dynamo Stack installs the serving runtime. You must also deploy a model as described in the Dynamo guide. Then send an inference request to confirm that the model responds.

Add metrics deliberately​

Connection and telemetry installation are separate steps. Check that your NVKE-created cluster includes the Metrics API needed for basic CPU and memory usage. Run these checks in the workload cluster:

Modify the following with your specific values to generate a copyable command:
kubectl --context nvke-eu get apiservice v1beta1.metrics.k8s.io
kubectl --context nvke-eu top nodes

If the API is absent or unavailable, configure Kubernetes Metrics Server using a version compatible with the selected Kubernetes release. Resolve its API and kubelet connectivity before checking the platform UI. Don't disable kubelet certificate verification to work around a Metrics API failure.

For centralized metrics, configure the Fleet Observability pipeline. Control plane cluster collection needs collectors and a reachable backend, just like other destinations. For GPU telemetry, follow the GPU observability deployment order.

NVKE's NKTP installation and NVIDIA Fleet Intelligence Agent don't automatically configure Platform's complete collection and query path. Record which collector, gateway, and backend produced each dashboard result.

Verify the integration​

Confirm each result:

CheckWhat to confirm
ConnectionPlatform version, CLI version, NVKE version, connected-cluster name, and healthy agent status.
Application deliveryStackTemplate and parameters, StackInstance task status, and workload status in the NVKE cluster.
Basic metricsAvailable Metrics API and successful node CPU/memory query.
Fleet telemetryCollector and backend configuration, query result, and cluster labels.
GPU workload, if testedActual GPU capacity, device plugin or operator, workload request, and successful inference or compute result.

Keep simulator and real-hardware results separate.

Clean up​

Remove evaluation workloads before disconnecting the cluster. Review each application's data-retention behavior first. Deleting a StackInstance removes its managed applications even when prunePolicy is Retain. That setting controls tasks removed from a template, not retention of the entire Stack on deletion.

Modify the following with your specific values to generate a copyable command:
kubectl delete stackinstance nvke-workload -n p-default

Check for application resources, storage, and collectors left in the NVKE cluster. Review the connected-cluster architecture before changing agent or registration resources. Delete the workload cluster through NVKE after cleanup if it was created only for this evaluation.

Next steps​