Custom resources

GPUClass

Short names: gpucls

Scope: Cluster
Version: v1alpha1

• apiVersion

  string

  APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
• kind

  string

  Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
• metadata

  object
• spec

  object

  GPUClassSpec defines a named pool of PhysicalGPU objects and the generated DeviceClass variants that users can request through extended resources.
  • spec.partitionFilter

    object

    PartitionFilter restricts partition profile names used for generated DeviceClasses. Names come from PhysicalGPU status capabilities.
    • spec.partitionFilter.allow

      array of strings

      Allow is a whitelist of names that may be used.
    • spec.partitionFilter.deny

      array of strings

      Deny is a blacklist of names that must not be used.
  • spec.selector

    object

    Selector selects PhysicalGPU objects by labels. Empty selector means all PhysicalGPU objects in the cluster.
    • spec.selector.matchExpressions

      array of objects

      matchExpressions is a list of label selector requirements. The requirements are ANDed.
      • spec.selector.matchExpressions.key

        string

        key is the label key that the selector applies to.
      • spec.selector.matchExpressions.operator

        string

        operator represents a key’s relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist.
      • spec.selector.matchExpressions.values

        array of strings

        values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch.
    • spec.selector.matchLabels

      object

      matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is “key”, the operator is “In”, and the values array contains only “value”. The requirements are ANDed.
  • spec.sharingFilter

    object

    SharingFilter restricts sharing mode names used for generated DeviceClasses. Names come from PhysicalGPU labels with the gpu.deckhouse.io/sharing. prefix.
    • spec.sharingFilter.allow

      array of strings

      Allow is a whitelist of names that may be used.
    • spec.sharingFilter.deny

      array of strings

      Deny is a blacklist of names that must not be used.
• status

  object

  GPUClassStatus defines the observed state of GPUClass.

  The status MUST NOT aggregate the readiness of the PhysicalGPU objects the class selected, including any counter of devices in phase Ready. A GPUClass picks devices with a label selector and does not own their lifecycle, so their readiness stays in the status of the PhysicalGPU objects themselves and is found with the same selector. MatchingPhysicalGPUCount is allowed because it is the result of applying the class’s own selector, not an assertion about the state of objects it does not own.

  Reconciliation state is carried entirely by the existing Ready condition, whose reason is Reconciled or Failed (see ReadyReason); no status field is added for presentation purposes.

  • status.conditions

    array of objects

    Conditions represent reconciliation status for this GPUClass.
    • status.conditions.lastTransitionTime

      string

      lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
    • status.conditions.message

      string

      message is a human readable message indicating details about the transition. This may be an empty string.

      Maximum length: 32768

    • status.conditions.observedGeneration

      integer

      observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.

      Allowed values: 0 <= X

    • status.conditions.reason

      string

      reason contains a programmatic identifier indicating the reason for the condition’s last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.

      Length: 1..1024

      Pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$

    • status.conditions.status

      string

      status of the condition, one of True, False, Unknown.

      Allowed values: True, False, Unknown

    • status.conditions.type

      string

      type of condition in CamelCase or in foo.example.com/CamelCase.

      Maximum length: 316

      Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

  • status.deviceClassNames

    array of strings

    DeviceClassNames is the complete list of DeviceClass objects generated for this GPUClass.
  • status.matchingPhysicalGPUCount

    integer

    MatchingPhysicalGPUCount is the number of PhysicalGPU objects matching the selector during the latest reconciliation.

PhysicalGPU

Short names: pgpu

Scope: Cluster
Version: v1alpha1

• apiVersion

  string

  APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
• kind

  string

  Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
• metadata

  object
• spec

  object

  PhysicalGPUSpec defines the desired state of PhysicalGPU. v0: desired state is intentionally empty.
• status

  object

  PhysicalGPUStatus defines the observed state of PhysicalGPU.

  The status describes the device itself; it is inventory, not an allocation ledger. It MUST NOT publish the identity of the device’s consumers: no references to ResourceClaim, Pod, VirtualMachine or any other consumer object. ResourceClaim remains the single source of truth about allocation (its status.allocation.devices.results and status.reservedFor), the same way an upstream DRA ResourceSlice never names its consumers. Who took the device is answered by the ResourceClaim; what the module makes of that is expressed by the Managed condition, whose reason names the case: BackingAllocation when an owning claim is what puts the device under management, NoBackingAllocation for an ordinarily free compute device, another reason for the cases that are neither.

  DriverBinding.ManagementState is a deliberate exception, and it also defines the shape of the only exception allowed here: a derived scalar that gates module behaviour (reclaim fires strictly on Orphaned), never a directory of consumers.

  • status.capabilities

    object

    Capabilities is a snapshot of device capabilities.
    • status.capabilities.architecture

      string

      Architecture is the GPU architecture name (for example “Hopper”, “RDNA3”, “Xe-HPC”).
    • status.capabilities.computeAPI

      string

      ComputeAPI is the primary compute API (“CUDA”, “ROCm”, “oneAPI”).
    • status.capabilities.computeCapability

      string

      ComputeCapability is the compute capability string (for example “8.0” for NVIDIA, empty for others).
    • status.capabilities.memoryMiB

      integer

      MemoryMiB is the total framebuffer memory in MiB.
    • status.capabilities.partitionSupport

      object

      PartitionSupport describes partition capabilities (MIG/SPX/SR-IOV).
      • status.capabilities.partitionSupport.profiles

        array of objects

        Profiles lists supported partition profiles.
        • status.capabilities.partitionSupport.profiles.maxInstances

          integer

          MaxInstances is the maximum number of instances for this profile.
        • status.capabilities.partitionSupport.profiles.memoryMiB

          integer

          MemoryMiB is the framebuffer size for the profile.
        • status.capabilities.partitionSupport.profiles.name

          string

          Name is the profile name (for example “1g.6gb”, “spx-half”).
        • status.capabilities.partitionSupport.profiles.profileID

          integer

          ProfileID is the numeric profile ID.
        • status.capabilities.partitionSupport.profiles.resources

          object

          Resources is a vendor-agnostic map of resource counters (for example {“multiprocessors”: 14, “copy-engines”: 1}).
        • status.capabilities.partitionSupport.profiles.sliceCount

          integer

          SliceCount is the number of slices consumed by the profile.
      • status.capabilities.partitionSupport.supported

        boolean

        Required value

        Supported indicates whether partitioning is supported on this GPU.
      • status.capabilities.partitionSupport.technology

        string

        Technology is the partition technology name (“MIG”, “SPX”, “SR-IOV”).
      • status.capabilities.partitionSupport.totalSlices

        integer

        TotalSlices is the total number of partition slices on the GPU.
    • status.capabilities.powerLimitMaxW

      integer

      PowerLimitMaxW is the maximum supported power limit in watts.
    • status.capabilities.powerLimitMinW

      integer

      PowerLimitMinW is the minimum supported power limit in watts.
    • status.capabilities.productName

      string

      ProductName is the GPU product name (for example “NVIDIA A30”).
    • status.capabilities.vendor

      string

      Vendor is the GPU vendor identifier (for example “nvidia”, “amd”, “intel”).
  • status.conditions

    array of objects

    Conditions represent the health and readiness of the GPU.
    • status.conditions.lastTransitionTime

      string

      lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
    • status.conditions.message

      string

      message is a human readable message indicating details about the transition. This may be an empty string.

      Maximum length: 32768

    • status.conditions.observedGeneration

      integer

      observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.

      Allowed values: 0 <= X

    • status.conditions.reason

      string

      reason contains a programmatic identifier indicating the reason for the condition’s last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.

      Length: 1..1024

      Pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$

    • status.conditions.status

      string

      status of the condition, one of True, False, Unknown.

      Allowed values: True, False, Unknown

    • status.conditions.type

      string

      type of condition in CamelCase or in foo.example.com/CamelCase.

      Maximum length: 316

      Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

  • status.currentState

    object

    CurrentState reflects current driver binding and runtime details.
    • status.currentState.computeAPIVersion

      string

      ComputeAPIVersion is the compute API version string at runtime.
    • status.currentState.driverVersion

      string

      DriverVersion is the driver version string.
    • status.currentState.gpuUUID

      string

      GPUUUID is the GPU UUID reported by the vendor driver.
    • status.currentState.partition

      object

      Partition describes the current partition mode state.
      • status.currentState.partition.mode

        string

        Mode is the current partition mode reported by the adapter.
    • status.currentState.powerLimitCurrentW

      integer

      PowerLimitCurrentW is the current power limit in watts.
    • status.currentState.powerLimitEnforcedW

      integer

      PowerLimitEnforcedW is the enforced power limit in watts.
  • status.driverBinding

    object

    DriverBinding reports the observed kernel driver binding, its classified serving mode, and the observed management state. Ownership is split per field via Server-Side Apply (see the DriverBinding type): driver and mode are owned by gpu-node-agent, managementState by gpu-controller.
    • status.driverBinding.driver

      string

      Driver is the raw kernel driver bound to the device in sysfs (for example “nvidia”, “vfio-pci”, “nvidia-vgpu-vfio”, or an empty string when no driver is bound). It is treated as ground truth. Owned by field manager gpu-node-agent (FieldManagerNodeAgent).
    • status.driverBinding.managementState

      string

      ManagementState is the observed answer to who manages this device: the module (Managed), a deliberate operator opt-out that has settled after the binding was released (Excluded), an unintended orphan (Orphaned), nobody while the device is identified, its binding is in Compute mode, no opt-out is declared and no claim holds it (Unclaimed), or no settled answer at all (Unknown). It is orthogonal to Mode. Orphaned is the ONLY reclaim-gating value; while an opt-out is pending but the binding is still alive it stays Managed (the transient is carried by the Managed condition as ExcludedReleasePending), so a live binding is never reclaim-eligible. Unclaimed is the ordinary free state and promises nothing about allocatability, which DRA decides; Unknown is the fail-safe and keeps every case without a settled answer, the grace window of a stray binding and a binding that is not live included. Owned by field manager gpu-controller (FieldManagerController) via Server-Side Apply, separately from driver/mode; see ManagementState.

      Allowed values: Managed, Excluded, Orphaned, Unclaimed, Unknown

    • status.driverBinding.mode

      string

      Mode is the classified serving mode derived from the bound driver. It is transport-agnostic; consumers MUST NOT infer the transport from it. Owned by field manager gpu-node-agent (FieldManagerNodeAgent).

      Allowed values: Compute, Passthrough, Unbound, Unknown

  • status.message

    string

    Message is a human-readable explanation of the current Phase. It is derived from the same conditions Phase is derived from, so it introduces no new source of truth, and it is empty whenever there is nothing to explain (for example a healthy device in PhaseReady).

    Owned exclusively by field manager gpu-controller (FieldManagerController) via Server-Side Apply.

    The field is deliberately NOT machine-readable: consumers MUST NOT parse it and MUST NOT use it as a gate. The machine-readable signals stay Phase, Conditions and DriverBinding.ManagementState. It MUST NOT become a metric label either, because free-form text would give unbounded cardinality.

  • status.nodeInfo

    object

    NodeInfo contains node identification and bare-metal detection.
    • status.nodeInfo.bareMetal

      boolean

      BareMetal indicates whether the node is detected as bare metal.
    • status.nodeInfo.nodeName

      string

      NodeName is the Kubernetes node name where the GPU is detected.
  • status.pciInfo

    object

    PCIInfo holds PCI identification details for the device.
    • status.pciInfo.address

      string

      Address is the PCI address, for example “0000:02:00.0”.
    • status.pciInfo.class

      object

      Class describes the PCI class.
      • status.pciInfo.class.code

        string

        Code is the PCI class code (base+subclass), for example “0302”.
    • status.pciInfo.device

      object

      Device describes the PCI device.
      • status.pciInfo.device.id

        string

        ID is the PCI device ID, for example “20b7”.
    • status.pciInfo.vendor

      object

      Vendor describes the PCI vendor.
      • status.pciInfo.vendor.id

        string

        ID is the PCI vendor ID, for example “10de”.
  • status.phase

    string

    Phase is the lifecycle phase of the GPU, derived from conditions by gpu-controller.

    Allowed values: Pending, Initializing, Ready, Reconfiguring, Failed, Lost, Passthrough