Skip to content

Document fields in spec to indicate when these were added. #215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 8, 2024
Merged

Document fields in spec to indicate when these were added. #215

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
61fe2c4
Document fields in spec to indicate when these were added.
bart0sh Jul 29, 2024
9c4f75c
Add comments with version info
bart0sh Aug 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions SPEC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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

Expand All @@ -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.
Expand All @@ -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}.
Expand All @@ -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.
Expand Down
10 changes: 6 additions & 4 deletions specs-go/config.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ type Spec struct {
Version string `json:"cdiVersion"`
Kind string `json:"kind"`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to call out the allowed character change for the class in a docstring?

// 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"`
Expand All @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One thought that I had was whether we wanted to add golang field tags so that we could parse these programatically? This could be done as a follow-up though.

Annotations map[string]string `json:"annotations,omitempty"`
ContainerEdits ContainerEdits `json:"containerEdits"`
}
Expand All @@ -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"`
Expand All @@ -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.
Expand Down