Independently provisioned instances
| Enterprise | ||||
|---|---|---|---|---|
| Available in these plans | Free | Dev | Prod | Scale |
| Machine Management | ||||
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.
An instance doesn't have to become a Kubernetes node. You can request one, get a provisioned server with your SSH keys on it, and stop there. Nothing installs a kubelet, and no cluster is involved.
This is the path for customers who buy compute rather than clusters. It's also the starting point for anyone who wants to run something other than Kubernetes on vMetal-provisioned hardware.
This guide uses two contexts. SSHKey and NodeClaim commands target the management cluster, while BareMetalHost commands target the control plane cluster named by NodeProvider.spec.metal3.clusterRef.cluster. The platform UI does the same management-cluster work under a project's Instances view.
For the broader model behind instances and servers, see Instance and server concepts. For the path where servers do join a cluster, see Cluster attachment.
The steps below use the Metal3 driver, which this section documents in the most depth. The model isn't Metal3-specific. An instance with no cluster is a platform-level concept, so other drivers support it too. KubeVirt, for example, creates the VM in the node provider's own namespace. For NVIDIA Infra Controller (NICo), see Provision instances and cluster nodes with NICo.
Before you begin​
Work through the Metal3 get started walkthrough steps 1 through 4 first. Those steps apply to every use of vMetal. Step 5 there is a branch point that routes to one of three guides. This is the one for servers that run no Kubernetes, and it picks up where step 4 ends.
By the end of those steps you have:
- A working NodeProvider with at least one
BareMetalHostinavailablestate. - At least one node type on that NodeProvider, with an OS image. See Define node types.
- A project to own the instance. Instances live in the project namespace,
loft-p-<project>.
Steps 1 and 2 below amend the node type you created while setting up your hardware. Do them before you claim a server. SSH keys are injected at provision time, and a server that's already provisioned doesn't pick up a key you add afterwards.
This guide provisions one server so you can see the whole path end to end. To do the same across a rack or a datacenter, see Scale to a fleet.
The machine-management feature gates any instance claimed from a provider that keeps an inventory, which includes Metal3. That covers every instance in this guide. It also covers workers and control plane instances on the same provider, so this isn't a cost specific to the clusterless path. A claim that pins a specific Machine with machineRef needs the feature too, whatever the provider.
The platform rejects the request at creation time if your plan doesn't include the feature. To check your plan, in the platform navigate to Platform > Platform Config > License and Billing.
If you need the feature added, contact support@vcluster.com.
How this differs from a cluster node​
Everything up to the moment the OS boots is identical. The platform selects an eligible server, allocates an IP, renders cloud-init, and hands the server to the driver for provisioning. The difference is what the platform appends to the cloud-init it generates.
| Independently provisioned instance | Cluster node | |
|---|---|---|
spec.vClusterRef | Empty | Names a cluster |
| Cloud-init contains | Your user data and SSH keys | Your user data, SSH keys, and a Kubernetes join command |
| Result | A server you reach over SSH | A Kubernetes node in that cluster |
| On release | The server is cleaned | The node is removed, then the server is cleaned |
Server selection, IP allocation, OS image resolution, network configuration, and the BareMetalHost lifecycle are the same in both cases. So is the return path. Deleting the instance returns the server to the available pool for reuse.
1. Register an SSH key​
Without a Kubernetes join, SSH is how you reach the server. Register the public key as an SSHKey resource so node types and instances can reference it by name.
The platform generates SSH key names, so the manifest sets a generateName prefix rather than a fixed name.
apiVersion: management.loft.sh/v1
kind: SSHKey
metadata:
generateName: ops-key-
spec:
displayName: "Ops team key"
publicKey: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... ops@example.com"
Create the key with kubectl create and note the name it prints. kubectl apply doesn't work here, because the platform refuses a fixed metadata.name.
kubectl --context <management-context> create -f ops-key.yaml -o name
The output names the key, for example sshkey.management.loft.sh/ops-key-x7k2p. The examples on this page use ops-key-x7k2p. Replace it with the name generated for your key.
SSHKey resources are cluster-scoped. Reference several of them from one instance with a comma-separated list. See SSH keys for the full field reference and access control.
If the project belongs to a tenant, share the key with that tenant before you request the instance. The platform refuses a NodeClaim that names a key its tenant can't see. See Share SSH keys with tenants.
2. Add the SSH key to your node type​
Node types are defined on the NodeProvider. Edit that NodeProvider and add vcluster.com/ssh-keys to the node type, so every instance created from it gets the key. The value is a comma-separated list of SSHKey resource names, not the key material itself.
nodeTypes:
- name: "compute-node"
displayName: "Compute Node"
resources:
cpu: "32"
memory: 128Gi
machines:
selector:
matchLabels:
role: compute
properties:
vcluster.com/os-image: ubuntu-noble
vcluster.com/ssh-keys: ops-key-x7k2p
You can also set vcluster.com/ssh-keys directly on an instance for one request only. The instance's list replaces the node type's list rather than adding to it, so repeat any node type keys you still want. Properties merge from the NodeProvider, then the node type, then the instance, and the most specific value wins. See Property merging.
If you need more than SSH keys at first boot, such as a package install or a service unit, set vcluster.com/user-data with a full cloud-config document. The platform appends your SSH keys to it rather than replacing it. See SSH and user data.
3. Request the instance​
Create a NodeClaim with no vClusterRef. That single omission is what makes this an independently provisioned instance.
apiVersion: management.loft.sh/v1
kind: NodeClaim
metadata:
name: machine-01
namespace: loft-p-my-project
spec:
displayName: "Compute 01"
providerRef: metal3-provider
typeRef: metal3-provider.compute-node
kubectl --context <management-context> apply -f machine-01.yaml
Two details to get right:
typeReftakes the node type's full resource name, which the platform generates as<provider>.<node type>. A node type calledcompute-nodeon a provider calledmetal3-providerbecomesmetal3-provider.compute-node. List them withkubectl --context <management-context> get nodetypes.- The namespace is the project namespace,
loft-p-<project>. An instance created anywhere else isn't governed by that project's roles or quotas.
To pin the request to one specific physical server rather than letting the platform choose, set the metal3.vcluster.com/server-name property to a BareMetalHost name. See Server pinning.
You can do all of this in the platform UI instead. Under a project, open Instances, then Create Instance, and leave the cluster unset. The instances list marks these as Provisioned manually, which is a useful filter once a project holds a mix of both kinds.
4. Watch it provision​
kubectl --context <management-context> get nodeclaim machine-01 \
-n loft-p-my-project -o wide
The instance reaches Available once the driver finishes provisioning. Because there's no cluster to join, the Joined condition is satisfied as soon as provisioning completes. It doesn't indicate that any Kubernetes component is running.
Watch the underlying server move through its own states at the same time:
kubectl --context <control-plane-context> get baremetalhost \
-n metal3-system
The server passes through provisioning and reaches provisioned. For what each state means and what to do when one stalls, see Server lifecycle and Troubleshooting.
5. Connect over SSH​
The platform records the allocated IP on the instance as an annotation once provisioning completes.
kubectl --context <management-context> get nodeclaim machine-01 \
-n loft-p-my-project \
-o jsonpath='{.metadata.annotations.nodeclaim\.vcluster\.com/ip-address}'
Then connect as the user your OS image defines. For the Ubuntu cloud images used in these examples, that's ubuntu.
ssh ubuntu@<ip-address>
The IP annotation is best-effort. A driver that can't report an address leaves it unset, and the instance still provisions normally. When it's missing, find the address through your own DHCP or IPAM records. If the instance is Available but SSH fails, follow Instance is available but SSH fails.
The platform UI shows the same address in the instances list, with a copy button. An instance's Connect via SSH action shows the address together with the SSH keys the platform resolved for it. That's the quickest way to confirm a server got the key you expected.
6. Release the instance​
Delete the instance when you're done with the server.
kubectl --context <management-context> delete nodeclaim machine-01 \
-n loft-p-my-project
The driver cleans the server and returns it to the available pool, where a later instance can claim it. Deleting the instance doesn't delete the BareMetalHost.
There's nothing for Kubernetes to drain, so quiesce your workloads before releasing the instance. Metal3's default automated cleaning removes partition tables but doesn't perform full-disk data erasure. Apply any additional sanitization your security policy requires before returning a server to a shared pool. See Reuse and reprovisioning.
To remove a server from the fleet entirely rather than releasing a claim on it, see Remove servers.
Scale to a fleet​
Nothing above changes when you go from one server to a hundred. Register the servers, define node types that describe your hardware, and create one instance per server you want to hand out.
Registering servers, labeling them, and designing node types are the same work whichever way you use the capacity. Only the last step, creating the instances, differs between handing servers out directly and giving them to a cluster.
Register servers in bulk​
Apply BareMetalHost and Secret resources together in a single manifest rather than one file per server. See Bulk registration.
Label each server as you register it. Labels are how node types select servers later, so setting them up front saves a relabeling pass across the whole fleet. Rack, datacenter, hardware generation, and GPU model are the keys that earn their place. See Label strategy, which applies to any fleet and not only GPU hardware.
Define node types for your hardware​
A node type groups servers by label selector and sets their provisioning defaults. Define one per distinct configuration you intend to hand out.
nodeTypes:
- name: "compute-gen9"
displayName: "Compute, Gen 9"
resources:
cpu: "32"
memory: 128Gi
machines:
selector:
matchLabels:
role: compute
generation: gen9
properties:
vcluster.com/os-image: ubuntu-noble
vcluster.com/ssh-keys: ops-key-x7k2p
- name: "compute-gen10"
displayName: "Compute, Gen 10"
resources:
cpu: "64"
memory: 256Gi
machines:
selector:
matchLabels:
role: compute
generation: gen10
properties:
vcluster.com/os-image: ubuntu-noble
vcluster.com/ssh-keys: ops-key-x7k2p
Selectors can overlap, so one server may be eligible under more than one node type. See Select machines by label and One node type per hardware profile.
Claim several servers at once​
Each instance claims exactly one server, so ten servers means ten instances. Create them from a single manifest.
apiVersion: management.loft.sh/v1
kind: NodeClaim
metadata:
name: machine-01
namespace: loft-p-my-project
spec:
providerRef: metal3-provider
typeRef: metal3-provider.compute-gen10
---
apiVersion: management.loft.sh/v1
kind: NodeClaim
metadata:
name: machine-02
namespace: loft-p-my-project
spec:
providerRef: metal3-provider
typeRef: metal3-provider.compute-gen10
The platform selects an eligible server for each claim independently. Claims that find no eligible server wait rather than fail, so a claim sitting in Pending usually means the pool is empty for that node type.
Track what is claimed and what is free​
List every instance in a project with the server and IP it holds:
kubectl --context <management-context> get nodeclaims \
-n loft-p-my-project \
-o custom-columns='NAME:.metadata.name,PHASE:.status.phase,IP:.metadata.annotations.nodeclaim\.vcluster\.com/ip-address'
Count the servers still free to claim:
kubectl --context <control-plane-context> get baremetalhost \
-n metal3-system -o json | \
jq '[.items[] | select(.status.provisioning.state=="available")] | length'
For the rest of the fleet view, including which servers are in error and how to withhold one from the pool, see Check fleet capacity.
What vMetal manages, and what it doesn't​
The boundary sits at the operating system. vMetal owns everything up to and including first boot, and your OS image and cloud-init own everything after it.
vMetal manages:
- The server. Registration, inspection, hardware inventory, OS installation, and network configuration.
- The claim. Which server is held by which instance, and returning it to the pool when you release it.
- Access and quota. Project roles govern who can request an instance and how many. An independently provisioned instance is governed by the same project isolation model as any other instance. See Prevent cross-project server access.
vMetal doesn't manage:
- Kubernetes. No kubelet, no container runtime, no CNI, unless your own OS image or user data installs them.
- In-guest monitoring or agents. Platform observability covers the provisioning layer and the server's BMC-reported state, not what runs inside the OS.
- The GPU driver stack. On cluster nodes a device plugin advertises GPUs to Kubernetes, and that mechanism doesn't exist here. Install vendor drivers through your OS image or user data. See GPU presentation modes.
- Anything you install after first boot. Configuration management, patching, and application deployment are yours.