|
35 | 35 | // available and instantiated the first time it is referenced directly |
36 | 36 | // or indirectly. The most frequently used cache functions are available |
37 | 37 | // as identically named package level functions which operate on the |
38 | | -// default cache instance. Moreover, the registry also operates on the |
39 | | -// same default cache. We plan to deprecate the registry and eventually |
40 | | -// remove it in a future release. |
41 | | -// |
42 | | -// # CDI Registry |
43 | | -// |
44 | | -// Note: the Registry and its related interfaces are deprecated and will |
45 | | -// be removed in a future version. Please use the default cache and its |
46 | | -// related package-level function instead. |
47 | | -// |
48 | | -// The primary interface to interact with CDI devices is the Registry. It |
49 | | -// is essentially a cache of all Specs and devices discovered in standard |
50 | | -// CDI directories on the host. The registry has two main functionality, |
51 | | -// injecting devices into an OCI Spec and refreshing the cache of CDI |
52 | | -// Specs and devices. |
| 38 | +// default cache instance. |
53 | 39 | // |
54 | 40 | // # Device Injection |
55 | 41 | // |
56 | | -// Using the Registry one can inject CDI devices into a container with code |
| 42 | +// Using the Cache one can inject CDI devices into a container with code |
57 | 43 | // similar to the following snippet: |
58 | 44 | // |
59 | | -// import ( |
60 | | -// "fmt" |
61 | | -// "strings" |
| 45 | +// import ( |
| 46 | +// "fmt" |
| 47 | +// "strings" |
62 | 48 | // |
63 | | -// log "github.com/sirupsen/logrus" |
| 49 | +// log "github.com/sirupsen/logrus" |
64 | 50 | // |
65 | | -// "tags.cncf.io/container-device-interface/pkg/cdi" |
66 | | -// oci "github.com/opencontainers/runtime-spec/specs-go" |
67 | | -// ) |
| 51 | +// "tags.cncf.io/container-device-interface/pkg/cdi" |
| 52 | +// oci "github.com/opencontainers/runtime-spec/specs-go" |
| 53 | +// ) |
68 | 54 | // |
69 | | -// func injectCDIDevices(spec *oci.Spec, devices []string) error { |
70 | | -// log.Debug("pristine OCI Spec: %s", dumpSpec(spec)) |
| 55 | +// func injectCDIDevices(spec *oci.Spec, devices []string) error { |
| 56 | +// log.Debug("pristine OCI Spec: %s", dumpSpec(spec)) |
71 | 57 | // |
72 | | -// unresolved, err := cdi.GetRegistry().InjectDevices(spec, devices) |
73 | | -// if err != nil { |
74 | | -// return fmt.Errorf("CDI device injection failed: %w", err) |
75 | | -// } |
| 58 | +// cache := cdi.GetDefaultCache() |
| 59 | +// unresolved, err := cache.InjectDevices(spec, devices) |
| 60 | +// if err != nil { |
| 61 | +// return fmt.Errorf("CDI device injection failed: %w", err) |
| 62 | +// } |
76 | 63 | // |
77 | | -// log.Debug("CDI-updated OCI Spec: %s", dumpSpec(spec)) |
78 | | -// return nil |
79 | | -// } |
| 64 | +// log.Debug("CDI-updated OCI Spec: %s", dumpSpec(spec)) |
| 65 | +// return nil |
| 66 | +// } |
80 | 67 | // |
81 | 68 | // # Cache Refresh |
82 | 69 | // |
|
99 | 86 | // CDI Spec cache is up to date before performing device injection. |
100 | 87 | // A code snippet similar to the following accmplishes that: |
101 | 88 | // |
102 | | -// import ( |
103 | | -// "fmt" |
104 | | -// "strings" |
| 89 | +// import ( |
| 90 | +// "fmt" |
| 91 | +// "strings" |
105 | 92 | // |
106 | | -// log "github.com/sirupsen/logrus" |
| 93 | +// log "github.com/sirupsen/logrus" |
107 | 94 | // |
108 | | -// "tags.cncf.io/container-device-interface/pkg/cdi" |
109 | | -// oci "github.com/opencontainers/runtime-spec/specs-go" |
110 | | -// ) |
| 95 | +// "tags.cncf.io/container-device-interface/pkg/cdi" |
| 96 | +// specs "github.com/opencontainers/runtime-spec/specs-go" |
| 97 | +// ) |
111 | 98 | // |
112 | | -// func injectCDIDevices(spec *oci.Spec, devices []string) error { |
113 | | -// registry := cdi.GetRegistry() |
| 99 | +// func injectCDIDevices(spec *specs.Spec, devices []string) error { |
| 100 | +// cache := cdi.GetDefaultCache() |
114 | 101 | // |
115 | | -// if err := registry.Refresh(); err != nil { |
116 | | -// // Note: |
117 | | -// // It is up to the implementation to decide whether |
118 | | -// // to abort injection on errors. A failed Refresh() |
119 | | -// // does not necessarily render the registry unusable. |
120 | | -// // For instance, a parse error in a Spec file for |
121 | | -// // vendor A does not have any effect on devices of |
122 | | -// // vendor B... |
123 | | -// log.Warnf("pre-injection Refresh() failed: %v", err) |
124 | | -// } |
| 102 | +// if err := cache.Refresh(); err != nil { |
| 103 | +// // Note: |
| 104 | +// // It is up to the implementation to decide whether |
| 105 | +// // to abort injection on errors. A failed Refresh() |
| 106 | +// // does not necessarily render the cache unusable. |
| 107 | +// // For instance, a parse error in a Spec file for |
| 108 | +// // vendor A does not have any effect on devices of |
| 109 | +// // vendor B... |
| 110 | +// log.Warnf("pre-injection Refresh() failed: %v", err) |
| 111 | +// } |
125 | 112 | // |
126 | | -// log.Debug("pristine OCI Spec: %s", dumpSpec(spec)) |
| 113 | +// log.Debug("pristine OCI Spec: %s", dumpSpec(spec)) |
127 | 114 | // |
128 | | -// unresolved, err := registry.InjectDevices(spec, devices) |
129 | | -// if err != nil { |
130 | | -// return fmt.Errorf("CDI device injection failed: %w", err) |
131 | | -// } |
| 115 | +// unresolved, err := cache.InjectDevices(spec, devices) |
| 116 | +// if err != nil { |
| 117 | +// return fmt.Errorf("CDI device injection failed: %w", err) |
| 118 | +// } |
132 | 119 | // |
133 | | -// log.Debug("CDI-updated OCI Spec: %s", dumpSpec(spec)) |
134 | | -// return nil |
135 | | -// } |
| 120 | +// log.Debug("CDI-updated OCI Spec: %s", dumpSpec(spec)) |
| 121 | +// return nil |
| 122 | +// } |
136 | 123 | // |
137 | 124 | // # Generated Spec Files, Multiple Directories, Device Precedence |
138 | 125 | // |
|
186 | 173 | // |
187 | 174 | // "fmt" |
188 | 175 | // ... |
189 | | -// "tags.cncf.io/container-device-interface/specs-go" |
| 176 | +// specs "tags.cncf.io/container-device-interface/specs-go" |
190 | 177 | // "tags.cncf.io/container-device-interface/pkg/cdi" |
191 | 178 | // |
192 | 179 | // ) |
193 | 180 | // |
194 | 181 | // func generateDeviceSpecs() error { |
195 | | -// registry := cdi.GetRegistry() |
| 182 | +// cache := specs.GetDefaultCache() |
196 | 183 | // spec := &specs.Spec{ |
197 | 184 | // Version: specs.CurrentVersion, |
198 | 185 | // Kind: vendor+"/"+class, |
|
210 | 197 | // return fmt.Errorf("failed to generate Spec name: %w", err) |
211 | 198 | // } |
212 | 199 | // |
213 | | -// return registry.SpecDB().WriteSpec(spec, specName) |
| 200 | +// return cache.WriteSpec(spec, specName) |
214 | 201 | // } |
215 | 202 | // |
216 | 203 | // Similarly, generating and later cleaning up transient Spec files can be |
|
222 | 209 | // import ( |
223 | 210 | // |
224 | 211 | // "fmt" |
225 | | -// ... |
226 | | -// "tags.cncf.io/container-device-interface/specs-go" |
| 212 | +// |
| 213 | +// specs "tags.cncf.io/container-device-interface/specs-go" |
227 | 214 | // "tags.cncf.io/container-device-interface/pkg/cdi" |
228 | 215 | // |
229 | 216 | // ) |
230 | 217 | // |
231 | 218 | // func generateTransientSpec(ctr Container) error { |
232 | | -// registry := cdi.GetRegistry() |
| 219 | +// cache := specs.GetDefaultCache() |
233 | 220 | // devices := getContainerDevs(ctr, vendor, class) |
234 | 221 | // spec := &specs.Spec{ |
235 | 222 | // Version: specs.CurrentVersion, |
|
257 | 244 | // return fmt.Errorf("failed to generate Spec name: %w", err) |
258 | 245 | // } |
259 | 246 | // |
260 | | -// return registry.SpecDB().WriteSpec(spec, specName) |
| 247 | +// return cache.WriteSpec(spec, specName) |
261 | 248 | // } |
262 | 249 | // |
263 | 250 | // func removeTransientSpec(ctr Container) error { |
264 | | -// registry := cdi.GetRegistry() |
| 251 | +// cache := specs.GetDefaultCache() |
265 | 252 | // transientID := getSomeSufficientlyUniqueIDForContainer(ctr) |
266 | 253 | // specName := cdi.GenerateNameForTransientSpec(vendor, class, transientID) |
267 | 254 | // |
268 | | -// return registry.SpecDB().RemoveSpec(specName) |
| 255 | +// return cache.RemoveSpec(specName) |
269 | 256 | // } |
270 | 257 | // |
271 | 258 | // # CDI Spec Validation |
272 | 259 | // |
273 | 260 | // This package performs both syntactic and semantic validation of CDI |
274 | | -// Spec file data when a Spec file is loaded via the registry or using |
| 261 | +// Spec file data when a Spec file is loaded via the cache or using |
275 | 262 | // the ReadSpec API function. As part of the semantic verification, the |
276 | 263 | // Spec file is verified against the CDI Spec JSON validation schema. |
277 | 264 | // |
|
0 commit comments