package hashicorp.nomad.plugins.device

Get desktop application:
View/edit binary Protocol Buffers messages

DevicePlugin is the API exposed by device plugins

• rpc Fingerprint (FingerprintRequest, stream FingerprintResponse)

  device.proto:18

  Fingerprint allows the device plugin to return a set of detected devices and provide a mechanism to update the state of the device.

  message FingerprintRequest

  device.proto:31

  FingerprintRequest is used to request for devices to be fingerprinted.

  (message has no fields)

  message FingerprintResponse

  device.proto:34

  FingerprintResponse returns a set of detected devices.

  • repeated DeviceGroup device_group = 1

    device_group is a group of devices that share a vendor, device_type, and device_name. This is returned as a set so that a single plugin could potentially detect several device types and models.

• rpc Reserve (ReserveRequest, ReserveResponse)

  device.proto:24

  Reserve is called by the client before starting an allocation that requires access to the plugin’s devices. The plugin can use this to run any setup steps and provides the mounting details to the Nomad client

  message ReserveRequest

  device.proto:89

  ReserveRequest is used to ask the device driver for information on how to allocate the requested devices.

  • repeated string device_ids = 1

    device_ids are the requested devices.

  message ReserveResponse

  device.proto:96

  ReserveResponse informs Nomad how to expose the requested devices to the task.

  • optional ContainerReservation container_res = 1

    container_res contains information on how to mount the device into a task isolated using container technologies (where the host is shared)

• rpc Stats (StatsRequest, stream StatsResponse)

  device.proto:27

  Stats returns a stream of device statistics.

  message StatsRequest

  device.proto:146

  StatsRequest is used to parameterize the retrieval of statistics.

  • optional google.protobuf.Duration collection_interval = 1

    collection_interval is the duration in which to collect statistics.

  message StatsResponse

  device.proto:152

  StatsResponse returns the statistics for each device group.

  • repeated DeviceGroupStats groups = 1

    groups contains statistics for each device group.

ContainerReservation returns how to mount the device into a container that shares the host OS.

Used in: ReserveResponse

• map<string, string> envs = 1

  List of environment variable to be set

• repeated Mount mounts = 2

  Mounts for the task.

• repeated DeviceSpec devices = 3

  Devices for the task.

DetectedDevice is a single detected device.

Used in: DeviceGroup

• string ID = 1

  ID is the ID of the device. This ID is used during allocation and must be stable across restarts of the device driver. buf:lint:ignore FIELD_LOWER_SNAKE_CASE

• bool healthy = 2

  Health of the device.

• string health_description = 3

  health_description allows the device plugin to optionally annotate the health field with a human readable reason.

• optional DeviceLocality hw_locality = 4

  hw_locality is optionally set to expose hardware locality information for more optimal placement decisions.

DeviceGroup is a group of devices that share a vendor, device type and name.

Used in: FingerprintResponse

• string vendor = 1

  vendor is the name of the vendor of the device

• string device_type = 2

  device_type is the type of the device (gpu, fpga, etc).

• string device_name = 3

  device_name is the name of the device.

• repeated DetectedDevice devices = 4

  devices is the set of devices detected by the plugin.

• map<string, shared.structs.Attribute> attributes = 5

  attributes allows adding attributes to be used for constraints or affinities.

DeviceGroupStats contains statistics for each device of a particular device group, identified by the vendor, type and name of the device.

Used in: StatsResponse

• string vendor = 1

• string type = 2

• string name = 3

• map<string, DeviceStats> instance_stats = 4

  instance_stats is a mapping of each device ID to its statistics.

DeviceLocality is used to expose HW locality information about a device.

Used in: DetectedDevice

• string pci_bus_id = 1

  pci_bus_id is the PCI bus ID for the device. If reported, it allows Nomad to make NUMA aware optimizations.

DeviceSpec specifies a host device to mount into a task.

Used in: ContainerReservation

• string task_path = 1

  Path of the device within the task.

• string host_path = 2

  Path of the device on the host.

• string permissions = 3

  Cgroups permissions of the device, candidates are one or more of * r - allows task to read from the specified device. * w - allows task to write to the specified device. * m - allows task to create device files that do not yet exist

DeviceStats is the statistics for an individual device

Used in: DeviceGroupStats

• optional shared.structs.StatValue summary = 1

  summary exposes a single summary metric that should be the most informative to users.

• optional shared.structs.StatObject stats = 2

  stats contains the verbose statistics for the device.

• optional google.protobuf.Timestamp timestamp = 3

  timestamp is the time the statistics were collected.

Mount specifies a host volume to mount into a task. where device library or tools are installed on host and task

Used in: ContainerReservation

• string task_path = 1

  Path of the mount within the task.

• string host_path = 2

  Path of the mount on the host.

• bool read_only = 3

  If set, the mount is read-only.