From 61fe2c465296da006f40d0e9b083abf33d90f2b6 Mon Sep 17 00:00:00 2001
From: Ed Bartosh <eduard.bartosh@intel.com>
Date: Mon, 29 Jul 2024 18:11:37 +0300
Subject: [PATCH 1/2] Document fields in spec to indicate when these were
added.
Signed-off-by: Ed Bartosh <eduard.bartosh@intel.com>
---
SPEC.md | 14 ++++++++------
1 file changed, 8 insertions(+), 6 deletions(-)
diff --git a/SPEC.md b/SPEC.md
index 447053f2..7ddcdb16 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -179,12 +179,14 @@ The keywords "must", "must not", "required", "shall", "shall not", "should", "sh
* `kind` (string, REQUIRED) field specifies a label which uniquely identifies the device vendor.
It can be used to disambiguate the vendor that matches a device, e.g: `docker/podman run --device vendor.com/device=foo ...`.
* The `kind` label has two segments: a prefix and a name, separated by a slash (/).
- * The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (\_), dots (.), and alphanumerics between.
+ * The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (\_), dots (.), and alphanumerics between. Dots (.) are supported from v0.6.0.
* The prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/).
* Examples (not an exhaustive list):
* Valid: `vendor.com/foo`, `foo.bar.baz/foo-bar123.B_az`.
* Invalid: `foo`, `vendor.com/foo/`, `vendor.com/foo/bar`.
+* `Annotations` (string, OPTIONAL) field contains a set of key-value pairs that may be used to provide additional information to a consumer on the spec. Added in v0.6.0.
+
#### CDI Devices
The `devices` field describes the set of hardware devices that can be requested by the container runtime user.
@@ -197,7 +199,7 @@ Note: For a CDI file to be valid, at least one entry must be specified in this a
* Entries in the array MUST use the same schema as the entry for the `name` field
* `containerEdits` (object, OPTIONAL) this field is described in the next section.
* This field should only be merged in the OCI spec if the device has been requested by the container runtime user.
-
+ * `Annotations` (string, OPTIONAL) field contains a set of key-value pairs that may be used to provide additional information to a consumer on the spec. Added in v0.6.0.
#### OCI Edits
@@ -212,7 +214,7 @@ The `containerEdits` field has the following definition:
* `env` (array of strings in the format of "VARNAME=VARVALUE", OPTIONAL) describes the environment variables that should be set. These values are appended to the container environment array.
* `deviceNodes` (array of objects, OPTIONAL) describes the device nodes that should be mounted:
* `path` (string, REQUIRED) path of the device within the container.
- * `hostPath` (string, OPTIONAL) path of the device node on the host. If not specified the value for `path` is used.
+ * `hostPath` (string, OPTIONAL) path of the device node on the host. If not specified the value for `path` is used. Added in v0.5.0.
* `type` (string, OPTIONAL) Device type: block, char, etc.
* `major` (int64, OPTIONAL) Device major number.
* `minor` (int64, OPTIONAL) Device minor number.
@@ -226,7 +228,7 @@ The `containerEdits` field has the following definition:
* `mounts` (array of objects, OPTIONAL) describes the mounts that should be mounted:
* `hostPath` (string, REQUIRED) path of the device on the host.
* `containerPath` (string, REQUIRED) path of the device within the container.
- * `type` (string, OPTIONAL) the type of the filesystem to be mounted. For bind mounts (when options include either bind or rbind), the type is a dummy, often "none" (not listed in /proc/filesystems).
+ * `type` (string, OPTIONAL) the type of the filesystem to be mounted. For bind mounts (when options include either bind or rbind), the type is a dummy, often "none" (not listed in /proc/filesystems). Added in v0.4.0.
* `options` (array of strings, OPTIONAL) Mount options of the filesystem to be used.
* `hooks` (array of objects, OPTIONAL) describes the hooks that should be ran:
* `hookName` is the name of the hook to invoke, if the runtime is OCI compliant it should be one of {createRuntime, createContainer, startContainer, poststart, poststop}.
@@ -235,13 +237,13 @@ The `containerEdits` field has the following definition:
* `args` (array of strings, OPTIONAL) with the same semantics as IEEE Std 1003.1-2008 execv's argv.
* `env` (array of strings, OPTIONAL) with the same semantics as IEEE Std 1003.1-2008's environ.
* `timeout` (int, OPTIONAL) is the number of seconds before aborting the hook. If set, timeout MUST be greater than zero. If not set container runtime will wait for the hook to return.
- * `intelRdt` (object, OPTIONAL) describes the Linux [resctrl][resctrl] settings for the container (object, OPTIONAL)
+ * `intelRdt` (object, OPTIONAL) describes the Linux [resctrl][resctrl] settings for the container (object, OPTIONAL). Added in v0.7.0.
* `closID` (string, OPTIONAL) name of the `CLOS` (Class of Service).
* `l3CacheSchema` (string, OPTIONAL) L3 cache allocation schema for the `CLOS`.
* `memBwSchema` (string, OPTIONAL) memory bandwidth allocation schema for the `CLOS`.
* `enableCMT` (boolean, OPTIONAL) whether to enable cache monitoring
* `enableMBM` (boolean, OPTIONAL) whether to enable memory bandwidth monitoring
- * `additionalGids` (array of uint32s, OPTIONAL) A list of additional group IDs to add with the container process. These values are added to the `user.additionalGids` field in the OCI runtime specification. Values of 0 are ignored.
+ * `additionalGids` (array of uint32s, OPTIONAL) A list of additional group IDs to add with the container process. These values are added to the `user.additionalGids` field in the OCI runtime specification. Values of 0 are ignored. Added in v0.7.0.
## Error Handling
* Kind requested is not present in any CDI file.
From 9c4f75cb94918b11095a98ed83404e1e41e476cf Mon Sep 17 00:00:00 2001
From: Ed Bartosh <eduard.bartosh@intel.com>
Date: Wed, 7 Aug 2024 11:24:44 +0300
Subject: [PATCH 2/2] Add comments with version info
Signed-off-by: Ed Bartosh <eduard.bartosh@intel.com>
---
specs-go/config.go | 10 ++++++----
1 file changed, 6 insertions(+), 4 deletions(-)
diff --git a/specs-go/config.go b/specs-go/config.go
index d6d6302f..2416c795 100644
--- a/specs-go/config.go
+++ b/specs-go/config.go
@@ -10,6 +10,7 @@ type Spec struct {
Version string `json:"cdiVersion"`
Kind string `json:"kind"`
// Annotations add meta information per CDI spec. Note these are CDI-specific and do not affect container metadata.
+ // Added in v0.6.0.
Annotations map[string]string `json:"annotations,omitempty"`
Devices []Device `json:"devices"`
ContainerEdits ContainerEdits `json:"containerEdits,omitempty"`
@@ -19,6 +20,7 @@ type Spec struct {
type Device struct {
Name string `json:"name"`
// Annotations add meta information per device. Note these are CDI-specific and do not affect container metadata.
+ // Added in v0.6.0.
Annotations map[string]string `json:"annotations,omitempty"`
ContainerEdits ContainerEdits `json:"containerEdits"`
}
@@ -29,14 +31,14 @@ type ContainerEdits struct {
DeviceNodes []*DeviceNode `json:"deviceNodes,omitempty"`
Hooks []*Hook `json:"hooks,omitempty"`
Mounts []*Mount `json:"mounts,omitempty"`
- IntelRdt *IntelRdt `json:"intelRdt,omitempty"`
- AdditionalGIDs []uint32 `json:"additionalGids,omitempty"`
+ IntelRdt *IntelRdt `json:"intelRdt,omitempty"` // Added in v0.7.0
+ AdditionalGIDs []uint32 `json:"additionalGids,omitempty"` // Added in v0.7.0
}
// DeviceNode represents a device node that needs to be added to the OCI spec.
type DeviceNode struct {
Path string `json:"path"`
- HostPath string `json:"hostPath,omitempty"`
+ HostPath string `json:"hostPath,omitempty"` // Added in v0.5.0
Type string `json:"type,omitempty"`
Major int64 `json:"major,omitempty"`
Minor int64 `json:"minor,omitempty"`
@@ -51,7 +53,7 @@ type Mount struct {
HostPath string `json:"hostPath"`
ContainerPath string `json:"containerPath"`
Options []string `json:"options,omitempty"`
- Type string `json:"type,omitempty"`
+ Type string `json:"type,omitempty"` // Added in v0.4.0
}
// Hook represents a hook that needs to be added to the OCI spec.