Skip to main content
Version: v5.0 Stable

Provision instances and cluster nodes with NICo

Enterprise
Available in these plansFreeDevProdScale
NICo Node Provider

Free, Dev, Prod, and Scale are vCluster Platform license plans. Open source does not need a license or a Platform connection. See Compare open source and free tiers.

This task provisions capacity from an NVIDIA Infra Controller (NICo) node provider that a platform administrator has already connected. You either launch a standalone bare metal instance or have Auto Nodes supply private nodes to a cluster. For how the driver maps platform resources to NICo, see the NICo driver guide.

Before you begin​

A platform administrator must have completed the NICo driver setup. That setup produces the four resources this task consumes:

InputWhat it isSet up in
NodeProviderThe connection to the NICo site, such as nico.Create the NodeProvider
NodeTypeA pool of the provider's Machines. Its name combines the provider and entry names, such as nico.gpu-h100.Verify discovery
NetworkEnvironmentA ready network that a platform administrator lent to your Tenant, or a platform network for a platform project.Create a network
OSImageThe operating system image to install.Prepare an operating system image

Ask your administrator for these names if you don't have them.

You also need:

  • A project to provision in. Its allowedNodeTypes must permit the NodeType, and its allowedNetworkEnvironments allowlist must not exclude the network.
  • Permission to use the OSImage.
  • For SSH access to a standalone instance, an SSH key you're allowed to use, or permission to create one.
  • For cluster nodes, a cluster with private nodes whose project has access to the NodeType and network.

The project's Tenant decides which NICo tenant owns the instance. Each Tenant maps to the NICo tenant with the same name, and platform projects use the NodeProvider's own organization. To provision for a Tenant, work in one of that Tenant's projects. Tenant users work in their own Tenant. A platform administrator can click in the sidebar header and select the Tenant.

Networks don't belong to a project. A platform administrator manages them and lends each one exclusively to a Tenant. Tenants can't create or manage their own networks.

Set these values to match your environment. p-default is only an example. Use the management namespace of your project, not a cluster's workload namespace.

Modify the following with your specific values to replace on the whole page and generate copyable commands:

To use the API examples, connect kubectl to the management API:

vcluster platform login https://platform.example.com
vcluster platform connect management

Provision an instance​

A standalone instance is a provisioned bare metal host that doesn't join a cluster.

  1. Launch the instance​

    Open the Instances page of the project you want the instance in, and click . The instance belongs to that project. Under Compute Resources, select a node type, or select a specific Machine to provision on it. Select the OS image, network environment, and management access settings, then click .

    Alternatively, save this NodeClaim as nico-instance.yaml:

    nico-instance.yaml
    apiVersion: management.loft.sh/v1
    kind: NodeClaim
    metadata:
    name: nico-worker
    namespace: p-default
    spec:
    providerRef: nico
    typeRef: nico.gpu-h100
    properties:
    vcluster.com/network-environment: nico-network
    vcluster.com/os-image: ubuntu-nico

    To grant SSH access, add the key name alongside the image and network properties, without replacing them:

    properties:
    vcluster.com/ssh-keys: <ssh-key-name>

    Selecting an image alone doesn't grant SSH access. Supply the access configuration your OS needs.

    To target one machine, replace spec.typeRef with spec.machineRef:

    machineRef: <machine-name>

    machineRef and typeRef are mutually exclusive. Use the Machine resource name returned by the platform, not its hostname or NICo Core machine identifier. A Tenant can pin only Machines it can see, which are the ones assigned to it.

    Apply the manifest:

    kubectl apply -f nico-instance.yaml
  2. Watch the claim provision​

    kubectl get nodeclaims -n p-default
    kubectl get nodeclaim nico-worker -n p-default -o yaml

    The NodeClaim's conditions report provisioning progress. The Provisioned condition becomes True when NICo reports the instance ready. Its nico.vcluster.com/instance-id annotation identifies the NICo instance, and machines.vcluster.com/machine-id names the Machine it runs on. Don't edit controller-managed resource ID annotations.

    If no matching Machine becomes available, Provisioned fails with the reason InsufficientCapacity after 30 minutes. Set the machines.vcluster.com/provisioning-wait-timeout property to change the wait.

Network selection​

The examples select the network explicitly with vcluster.com/network-environment. If you omit it, the platform can use an accessible provider default, marked with machines.vcluster.com/is-default-environment: "true". Project.spec.allowedNetworkEnvironments restricts both explicit and default selections. An omitted allowlist allows otherwise accessible networks. An empty list allows none.

Every NICo instance needs vcluster.com/os-image. If your administrator gave you a NICo operating system ID instead of an OSImage, ask them for an OSImage that carries the ID. See Use an existing NICo operating system.

Supply cluster nodes with Auto Nodes​

Auto Nodes creates the NodeClaims for a cluster's private nodes from the provider's NodeTypes. Each instance boots with the cluster's join configuration and registers as a node.

  1. Add a NICo pool to the cluster​

    This vcluster.yaml requests one static worker:

    vcluster.yaml
    privateNodes:
    enabled: true
    autoNodes:
    - provider: nico
    properties:
    vcluster.com/network-environment: nico-network
    vcluster.com/os-image: ubuntu-nico
    static:
    - name: nico-workers
    quantity: 1
    nodeTypeSelector:
    - property: vcluster.com/node-type
    value: nico.gpu-h100

    The network and image properties are defaults for every pool in this provider entry. Pool-level properties can override them. For demand-based scaling, configure a dynamic pool with the same node type selector under that entry. See Auto Nodes and the Auto Nodes configuration reference for pool limits and scheduling settings.

    Create the cluster with this configuration. For a cluster that already uses private nodes, add the autoNodes entry to its vcluster.yaml.

  2. Check the claim and the node​

    The platform creates a NodeClaim, waits for its network and OS, and asks NICo to provision an instance. NICo instance readiness and Kubernetes node readiness are separate checks, so verify both.

    In the management API, check the claim's conditions:

    kubectl get nodeclaims -n p-default

    Provisioned becomes True when NICo reports the instance ready, and Joined becomes True once the node registers with the cluster. Then, connected to the cluster itself, confirm the node is Ready:

    kubectl get nodes

The driver reports each Machine's GPUs in its hardware status, but doesn't install GPU drivers or Kubernetes device plugins. Include the necessary host software in your image and configure the cluster's GPU stack.

If provisioning stalls​

SymptomChecks and next action
Network missing from the instance formCheck that one of the project's allowed node types, or a Machine assigned to the project's Tenant, uses the network's provider. Then check the project's Tenant, the network's assignment, and Project.spec.allowedNetworkEnvironments.
Claim waits with TenantNodeTypeQuotaExceededThe Tenant reached its quota for the NodeType. The quota counts only on-demand placements, not claims on Machines assigned to the Tenant or pinned to a Machine. Delete an on-demand instance of that type, or ask your administrator to raise the quota.
Claim fails with InsufficientCapacityNo matching Machine became available within the provisioning wait. Ask your administrator to check the NodeType's capacity and, for a Tenant, its assigned Machines.
Instance stays pending after bootCheck that the OS image is reachable and its settings are correct. Your administrator can check the NICo phone-home path.
Instance is ready but the node hasn't joinedCheck bootstrap logs on the host, the private node requirements, control plane or VPN connectivity, and DNS.

For provider, onboarding, and network failures, see Troubleshoot provisioning in the driver guide.

Delete instances and nodes​

Deleting a NodeClaim deletes its NICo instance. The Machine shows the Deprovisioning phase until NICo reports it ready again, and then another claim can use it.

kubectl delete nodeclaim nico-worker -n p-default

For Auto Nodes, remove the pool from vcluster.yaml or delete the cluster, so it stops maintaining its NodeClaims. For the order to remove networks, Tenants, and the provider, see Cleanup and resource ownership.