Provision instances and cluster nodes with NICo
| Enterprise | ||||
|---|---|---|---|---|
| Available in these plans | Free | Dev | Prod | Scale |
| 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:
| Input | What it is | Set up in |
|---|---|---|
| NodeProvider | The connection to the NICo site, such as nico. | Create the NodeProvider |
| NodeType | A pool of the provider's Machines. Its name combines the provider and entry names, such as nico.gpu-h100. | Verify discovery |
| NetworkEnvironment | A ready network that a platform administrator lent to your Tenant, or a platform network for a platform project. | Create a network |
| OSImage | The 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
allowedNodeTypesmust permit the NodeType, and itsallowedNetworkEnvironmentsallowlist 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.
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.
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.yamlapiVersion: management.loft.sh/v1kind: NodeClaimmetadata:name: nico-workernamespace: p-defaultspec:providerRef: nicotypeRef: nico.gpu-h100properties:vcluster.com/network-environment: nico-networkvcluster.com/os-image: ubuntu-nicoTo 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.typeRefwithspec.machineRef:machineRef: <machine-name>machineRefandtypeRefare 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.yamlWatch the claim provision​
kubectl get nodeclaims -n p-defaultkubectl get nodeclaim nico-worker -n p-default -o yamlThe NodeClaim's conditions report provisioning progress. The
Provisionedcondition becomesTruewhen NICo reports the instance ready. Itsnico.vcluster.com/instance-idannotation identifies the NICo instance, andmachines.vcluster.com/machine-idnames the Machine it runs on. Don't edit controller-managed resource ID annotations.If no matching Machine becomes available,
Provisionedfails with the reasonInsufficientCapacityafter 30 minutes. Set themachines.vcluster.com/provisioning-wait-timeoutproperty 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.
Add a NICo pool to the cluster​
This
vcluster.yamlrequests one static worker:vcluster.yamlprivateNodes:enabled: trueautoNodes:- provider: nicoproperties:vcluster.com/network-environment: nico-networkvcluster.com/os-image: ubuntu-nicostatic:- name: nico-workersquantity: 1nodeTypeSelector:- property: vcluster.com/node-typevalue: nico.gpu-h100The 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
autoNodesentry to itsvcluster.yaml.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-defaultProvisionedbecomesTruewhen NICo reports the instance ready, andJoinedbecomesTrueonce the node registers with the cluster. Then, connected to the cluster itself, confirm the node isReady: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​
| Symptom | Checks and next action |
|---|---|
| Network missing from the instance form | Check 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 TenantNodeTypeQuotaExceeded | The 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 InsufficientCapacity | No 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 boot | Check 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 joined | Check 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.