github.com/iqoqo/nomad@v0.11.3-0.20200911112621-d7021c74d101/website/pages/docs/internals/plugins/devices.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: Device Plugins
     4  sidebar_title: Devices
     5  description: Learn how to author a Nomad device plugin.
     6  ---
     7  
     8  # Devices
     9  
    10  Nomad has built-in support for scheduling compute resources such as CPU, memory,
    11  and networking. Nomad device plugins are used to support scheduling tasks with
    12  other devices, such as GPUs. They are responsible for fingerprinting these
    13  devices and working with the Nomad client to make them available to assigned
    14  tasks.
    15  
    16  For a real world example of a Nomad device plugin implementation, see the [Nvidia
    17  GPU plugin](https://github.com/hashicorp/nomad/tree/master/devices/gpu/nvidia).
    18  
    19  ## Authoring Device Plugins
    20  
    21  Authoring a device plugin in Nomad consists of implementing the
    22  [DevicePlugin][deviceplugin] interface alongside
    23  a main package to launch the plugin.
    24  
    25  The [device plugin skeleton project][skeletonproject] exists to help bootstrap
    26  the development of new device plugins. It provides most of the boilerplate
    27  necessary for a device plugin, along with detailed comments.
    28  
    29  ### Lifecycle and State
    30  
    31  A device plugin is long-lived. Nomad will ensure that one instance of the plugin is
    32  running. If the plugin crashes or otherwise terminates, Nomad will launch another
    33  instance of it.
    34  
    35  However, unlike [task drivers](/docs/internals/plugins/task-drivers), device plugins do not currently
    36  have an interface for persisting state to the Nomad client. Instead, the device
    37  plugin API emphasizes fingerprinting devices and reporting their status. After
    38  helping to provision a task with a scheduled device, a device plugin does not
    39  have any responsibility (or ability) to monitor the task.
    40  
    41  ## Device Plugin API
    42  
    43  The [base plugin][baseplugin] must be implemented in addition to the following
    44  functions.
    45  
    46  ### `Fingerprint(context.Context) (<-chan *FingerprintResponse, error)`
    47  
    48  The `Fingerprint` [function][fingerprintfn] is called by the client when the plugin is started.
    49  It allows the plugin to provide Nomad with a list of discovered devices, along with their
    50  attributes, for the purpose of scheduling workloads using devices.
    51  The channel returned should immediately send an initial
    52  [`FingerprintResponse`][fingerprintresponse], then send periodic updates at
    53  an appropriate interval until the context is canceled.
    54  
    55  Each fingerprint response consists of either an error or a list of device groups.
    56  A device group is a list of detected devices that are identical for the purpose of
    57  scheduling; that is, they will have identical attributes.
    58  
    59  ### `Stats(context.Context, time.Duration) (<-chan *StatsResponse, error)`
    60  
    61  The `Stats` [function][statsfn] returns a channel on which the plugin should
    62  emit device statistics, at the specified interval, until either an error is
    63  encountered or the specified context is cancelled. The `StatsReponse` object
    64  allows [dimensioned][dimensioned] statistics to be returned for each device in a device group.
    65  
    66  ### `Reserve(deviceIDs []string) (*ContainerReservation, error)`
    67  
    68  The `Reserve` [function][reservefn] accepts a list of device IDs and returns the information
    69  necessary for the client to make those devices available to a task. Currently,
    70  the `ContainerReservation` object allows the plugin to specify environment
    71  variables for the task, as well as a list of host devices and files to be mounted
    72  into the task's filesystem. Any orchestration required to prepare the device for
    73  use should also be performed in this function.
    74  
    75  [deviceplugin]: https://github.com/hashicorp/nomad/blob/v0.9.0/plugins/device/device.go#L20-L33
    76  [baseplugin]: /docs/internals/plugins/base
    77  [skeletonproject]: https://github.com/hashicorp/nomad-skeleton-device-plugin
    78  [fingerprintresponse]: https://github.com/hashicorp/nomad/blob/v0.9.0/plugins/device/device.go#L37-L43
    79  [fingerprintfn]: https://github.com/hashicorp/nomad-skeleton-device-plugin/blob/v0.1.0/device/device.go#L159-L165
    80  [statsfn]: https://github.com/hashicorp/nomad-skeleton-device-plugin/blob/v0.1.0/device/device.go#L169-L176
    81  [reservefn]: https://github.com/hashicorp/nomad-skeleton-device-plugin/blob/v0.1.0/device/device.go#L189-L245
    82  [dimensioned]: https://github.com/hashicorp/nomad/blob/v0.9.0/plugins/shared/structs/stats.go#L33-L34