Managing Hardware Instances
A hardware instance describes a class of hardware — GPU type, GPU count, CPU, and memory — that is available for deployments within a cluster. The Python SDK lets you list the hardware instances you have access to, and (with the right permissions) create and delete them.
Creating and deleting hardware instances requires admin privileges (PERM_ADMIN_MANAGE_HARDWARE) on your NVIDIA CCluster organization. Listing hardware instances does not require admin privileges.
Prerequisites
Install the SDK and authenticate before running any of the examples below. For unattended use in CI or automation, authenticate with a service account by setting CENTML_SERVICE_ACCOUNT_ID and CENTML_SERVICE_ACCOUNT_SECRET. Interactive development can use centml login instead — see Client Setup.
List hardware instances
get_hardware_instances returns the hardware instances you have access to. Pass an optional cluster_id to restrict the results to a single cluster.
from centml.sdk.api import get_centml_client
with get_centml_client() as client:
clusters = {c.id: c for c in client.get_clusters().results}
instances = client.get_hardware_instances()
for hw in instances:
cluster = clusters.get(hw.cluster_id)
cluster_name = cluster.display_name if cluster else f"cluster {hw.cluster_id}"
print(f"{hw.name} ({cluster_name}): {hw.num_gpu}x {hw.gpu_type}, "
f"{hw.cpu} CPU, {hw.memory} memory")
Each returned hardware instance exposes fields such as id, name, cluster_id, gpu_type, num_gpu, cpu, and memory.
Create a hardware instance
Use create_hardware_instance with a CreateHardwareInstanceRequest to register a new hardware instance under a cluster.
from centml.sdk import CreateHardwareInstanceRequest
from centml.sdk.api import get_centml_client
request = CreateHardwareInstanceRequest(
cluster_id=1,
name="h100-8x",
gpu_type="H100",
num_gpu=8,
cpu=64000,
memory=128000,
accelerator_resource_key="nvidia.com/gpu",
node_affinity_labels={"gpu": "h100"},
accelerator_memory=80000,
)
with get_centml_client() as client:
instance = client.create_hardware_instance(request)
print(f"Created hardware instance '{instance.name}' with ID {instance.id}")
The CreateHardwareInstanceRequest accepts the following fields:
| Field | Description |
|---|---|
cluster_id | ID of the cluster the hardware instance belongs to. |
name | Human-readable name for the hardware instance. |
gpu_type | GPU model, e.g. "H100". |
num_gpu | Number of GPUs per instance. |
cpu | CPU allocation (in millicores). |
memory | Memory allocation (in MB). |
accelerator_resource_key | Kubernetes resource key for the accelerator, e.g. "nvidia.com/gpu". |
node_affinity_labels | Node affinity labels used to schedule onto the correct nodes, e.g. {"gpu": "h100"}. |
accelerator_memory | GPU memory per accelerator (in MB). |
Delete a hardware instance
Use delete_hardware_instance with the hardware instance's ID to remove it.
from centml.sdk.api import get_centml_client
with get_centml_client() as client:
client.delete_hardware_instance(123)
A full runnable example is available at examples/sdk/manage_hardware_instances.py.