Skip to content

hardware_instances.mdx

Latest commit

 

History

History
116 lines (91 loc) · 4.13 KB

hardware_instances.mdx

File metadata and controls

116 lines (91 loc) · 4.13 KB
Raw
title Managing Hardware Instances
description Create, list, and delete hardware instances under a cluster with the Python SDK
icon server

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`](https://github.com/CentML/centml-python-client/blob/main/examples/sdk/manage_hardware_instances.py).

What's next

Programmatically manage your deployments with the NVIDIA CCluster SDK. Deploy workloads onto the clusters your hardware instances belong to. Submit a Support Request.