1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
// Package cdi has the primary purpose of providing an API for
// interacting with CDI and consuming CDI devices.
//
// For more information about Container Device Interface, please refer to
// https://github.com/container-orchestrated-devices/container-device-interface
//
// Container Device Interface
//
// Container Device Interface, or CDI for short, provides comprehensive
// third party device support for container runtimes. CDI uses vendor
// provided specification files, CDI Specs for short, to describe how a
// container's runtime environment should be modified when one or more
// of the vendor-specific devices is injected into the container. Beyond
// describing the low level platform-specific details of how to gain
// basic access to a device, CDI Specs allow more fine-grained device
// initialization, and the automatic injection of any necessary vendor-
// or device-specific software that might be required for a container
// to use a device or take full advantage of it.
//
// In the CDI device model containers request access to a device using
// fully qualified device names, qualified names for short, consisting of
// a vendor identifier, a device class and a device name or identifier.
// These pieces of information together uniquely identify a device among
// all device vendors, classes and device instances.
//
// This package implements an API for easy consumption of CDI. The API
// implements discovery, loading and caching of CDI Specs and injection
// of CDI devices into containers. This is the most common functionality
// the vast majority of CDI consumers need. The API should be usable both
// by OCI runtime clients and runtime implementations.
//
// CDI Registry
//
// The primary interface to interact with CDI devices is the Registry. It
// is essentially a cache of all Specs and devices discovered in standard
// CDI directories on the host. The registry has two main functionality,
// injecting devices into an OCI Spec and refreshing the cache of CDI
// Specs and devices.
//
// Device Injection
//
// Using the Registry one can inject CDI devices into a container with code
// similar to the following snippet:
//
// import (
// "fmt"
// "strings"
//
// "github.com/pkg/errors"
// log "github.com/sirupsen/logrus"
//
// "github.com/container-orchestrated-devices/container-device-interface/pkg/cdi"
// oci "github.com/opencontainers/runtime-spec/specs-go"
// )
//
// func injectCDIDevices(spec *oci.Spec, devices []string) error {
// log.Debug("pristine OCI Spec: %s", dumpSpec(spec))
//
// unresolved, err := cdi.GetRegistry().InjectDevices(spec, devices)
// if err != nil {
// return errors.Wrap(err, "CDI device injection failed")
// }
//
// log.Debug("CDI-updated OCI Spec: %s", dumpSpec(spec))
// return nil
// }
//
// Cache Refresh
//
// In a runtime implementation one typically wants to make sure the
// CDI Spec cache is up to date before performing device injection.
// A code snippet similar to the following accmplishes that:
//
// import (
// "fmt"
// "strings"
//
// "github.com/pkg/errors"
// log "github.com/sirupsen/logrus"
//
// "github.com/container-orchestrated-devices/container-device-interface/pkg/cdi"
// oci "github.com/opencontainers/runtime-spec/specs-go"
// )
//
// func injectCDIDevices(spec *oci.Spec, devices []string) error {
// registry := cdi.GetRegistry()
//
// if err := registry.Refresh(); err != nil {
// // Note:
// // It is up to the implementation to decide whether
// // to abort injection on errors. A failed Refresh()
// // does not necessarily render the registry unusable.
// // For instance, a parse error in a Spec file for
// // vendor A does not have any effect on devices of
// // vendor B...
// log.Warnf("pre-injection Refresh() failed: %v", err)
// }
//
// log.Debug("pristine OCI Spec: %s", dumpSpec(spec))
//
// unresolved, err := registry.InjectDevices(spec, devices)
// if err != nil {
// return errors.Wrap(err, "CDI device injection failed")
// }
//
// log.Debug("CDI-updated OCI Spec: %s", dumpSpec(spec))
// return nil
// }
//
// Generated Spec Files, Multiple Directories, Device Precedence
//
// There are systems where the set of available or usable CDI devices
// changes dynamically and this needs to be reflected in the CDI Specs.
// This is done by dynamically regenerating CDI Spec files which are
// affected by these changes.
//
// CDI can collect Spec files from multiple directories. Spec files are
// automatically assigned priorities according to which directory they
// were loaded from. The later a directory occurs in the list of CDI
// directories to scan, the higher priority Spec files loaded from that
// directory are assigned to. When two or more Spec files define the
// same device, conflict is resolved by chosing the definition from the
// Spec file with the highest priority.
//
// The default CDI directory configuration is chosen to encourage
// separating dynamically generated CDI Spec files from static ones.
// The default directories are '/etc/cdi' and '/var/run/cdi'. By putting
// dynamically generated Spec files under '/var/run/cdi', those take
// precedence over static ones in '/etc/cdi'.
package cdi
|
