GPU classes

A GPUClass is an administrator-defined pool of GPUs. It describes which cards belong to the pool and which partition and sharing options are allowed. The module turns that into a set of DeviceClass objects, each with an extended resource name that users can request directly.

This is the recommended way to expose GPUs to users. Without a GPUClass, every user has to author their own DeviceClass with a hand-written CEL selector — that path is described in Usage.

GPUClass is a cluster-scoped resource. Short name: gpucls.

Using GPUClass resources

How GPUClass works:

1. The cluster administrator creates a GPUClass with a selector over PhysicalGPU objects.
2. gpu-controller finds the matching cards and reads their capabilities — which MIG profiles they support and which sharing strategies are available.
3. For every allowed combination it creates a DeviceClass owned by that GPUClass. Each one gets an extendedResourceName.
4. Users request a GPU by that extended resource name. The module’s mutating webhook creates the ResourceClaim for them.

Deleting a GPUClass deletes all DeviceClass objects it generated (they are bound to the GPUClass via owner references).

Minimal GPUClass example

Every GPU in the cluster, whole cards only:

apiVersion: gpu.deckhouse.io/v1alpha1
kind: GPUClass
metadata:
  name: gpu-any
spec: {}

An empty spec means “all PhysicalGPU objects, all supported partition profiles, all supported sharing strategies”. On a mixed cluster this generates a large number of DeviceClass objects, so in practice you need a selector.

Selecting cards

spec.selector is a standard label selector over PhysicalGPU objects. An empty selector matches everything.

Available PhysicalGPU labels:

To list all PhysicalGPUs in the cluster and their labels, use:

d8 k get physicalgpus --show-labels

Example of a GPU class limited to one model:

apiVersion: gpu.deckhouse.io/v1alpha1
kind: GPUClass
metadata:
  name: a100
spec:
  selector:
    matchLabels:
      gpu.deckhouse.io/device: a100-sxm4-40gb

Restricting partition profiles

spec.partitionFilter limits which MIG profiles the class exposes. Use allow as a whitelist or deny as a blacklist.

To see which profiles a card supports, use:

d8 k get physicalgpu <name> -o jsonpath='{.status.capabilities.partitionSupport.profiles[*].name}'

This command prints the hardware names (1g.5gb, 2g.10gb, …). Strip the dots when writing them into the filter.

Example GPUClass that publishes only small A100 partitions:

apiVersion: gpu.deckhouse.io/v1alpha1
kind: GPUClass
metadata:
  name: a100-small
spec:
  selector:
    matchLabels:
      gpu.deckhouse.io/device: a100-sxm4-40gb
  partitionFilter:
    allow:
      - 1g5gb
      - 2g10gb

Everything except the full-card partition:

spec:
  partitionFilter:
    deny:
      - 7g40gb

Restricting sharing

spec.sharingFilter limits which sharing strategies the class exposes. Valid names are mps and ts; only strategies the hardware actually supports are used.

Example of a pool for exclusive use only — shared access to these cards is fully denied:

apiVersion: gpu.deckhouse.io/v1alpha1
kind: GPUClass
metadata:
  name: a100-exclusive
spec:
  selector:
    matchLabels:
      gpu.deckhouse.io/device: a100-sxm4-40gb
  sharingFilter:
    deny:
      - mps
      - ts

Example of a pool that only allows MPS:

spec:
  sharingFilter:
    allow:
      - mps

Generated DeviceClass names

Names are built from the class name plus partition and sharing segments:

For example, a class named ml-ai-h100 that allows the 1g12gb profile and MPS produces ml-ai-h100, ml-ai-h100-1g12gb, ml-ai-h100-mps-percent, and ml-ai-h100-1g12gb-mps-percent.

Generated objects get labels that make them easy to find and audit:

d8 k get deviceclasses -l gpu.deckhouse.io/gpuclass=ml-ai-h100

Viewing available GPUClass objects

To list GPUClass objects available in the cluster, use:

d8 k get gpuclasses

Example output:

NAME         STATE        GPUS   STATUS   AGE
ml-ai-h100   Reconciled   2               10m

Field meanings in the command output:

Until gpu-controller is upgraded to the version that writes this message, STATUS instead shows the constant DeviceClasses are reconciled on a healthy class.

The list of generated DeviceClass names is kept out of the default output because it grows with the number of partition and sharing variants. Add -o wide to see the DEVICECLASSES column (.status.deviceClassNames).

To get the full list of DeviceClass names created from a specific GPU class, use:

d8 k get gpuclass ml-ai-h100 -o jsonpath='{.status.deviceClassNames}' | jq

What information to give users requesting GPUs

Each generated DeviceClass publishes an extended resource named gpu.deckhouse.io/<device-class-name>.

To get that extended resource name, use (ml-ai-h100-1g12gb — replace with your value):

d8 k get deviceclass ml-ai-h100-1g12gb -o jsonpath='{.spec.extendedResourceName}'

Example output:

gpu.deckhouse.io/ml-ai-h100-1g12gb

Users must put this string in the Pod spec to request a GPU. See Usage.

GPU class specifics and limitations

GPU classes have the following specifics and limitations:

• Validation is strict and fails closed. The GPUClass webhook has failurePolicy: Fail, so while gpu-controller is unavailable, creating or updating a GPUClass is rejected. Reading and using already-generated DeviceClass objects is unaffected.
• Classes may overlap. Nothing stops two GPUClass objects from selecting the same cards; they simply produce two sets of names for the same hardware. Allocation conflicts are resolved by the scheduler, not by the class definition.
• Filters do not invent capabilities. If you allow a MIG profile or sharing strategy the card does not support, no DeviceClass is created for that combination — it is skipped, with no error message. If an expected name is missing from .status.deviceClassNames, check the card’s .status.capabilities first.
• Do not edit generated objects. gpu-controller reconciles them, so manual changes are reverted.