Skip to content

Commit 5b57312

Browse files
mfranczymfranczy
committed
Add image compatibility documentation
Signed-off-by: Marcin Franczyk <[email protected]>
1 parent efc299e commit 5b57312

File tree

4 files changed

+290
-2
lines changed

4 files changed

+290
-2
lines changed

‎docs/reference/feature-gates.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Feature Gates"
33
layout: default
4-
sort: 10
4+
sort: 11
55
---
66

77
# Feature Gates

‎docs/reference/node-feature-client-reference.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: "Node Feature client cmdline reference"
3+
layout: default
4+
sort: 9
5+
---
6+
7+
# Commandline flags of nfd client
8+
{: .no_toc}
9+
10+
## Table of contents
11+
{: .no_toc .text-delta}
12+
13+
1. TOC
14+
{:toc}
15+
16+
---
17+
18+
To quickly view available command line flags execute `nfd --help`.
19+
20+
### -h, --help
21+
22+
Print usage and exit.
23+
24+
## compat
25+
26+
Image Compatibility commands.
27+
28+
### validate-node
29+
30+
Perform node validation based on its associated image compatibility artifact.
31+
32+
#### --image
33+
34+
The `--image` flag specifies the URL of the image containing compatibility metadata.
35+
36+
#### --plain-http
37+
38+
The `--plain-http` flag forces the use of HTTP protocol for all registry communications.
39+
Default: `false`
40+
41+
#### --platform
42+
43+
The `--platform` flag specifies the artifact platform in the format `os[/arch][/variant][:os_version]`.
44+
45+
#### --tags
46+
47+
The `--tags` flag specifies a list of tags that must match the tags
48+
set on the compatibility objects.
49+
50+
#### --output-json
51+
52+
The `--output-json` flag prints the output as a JSON object.
53+
54+
#### --reg-username
55+
56+
The `--reg-username` flag specifies the username for the registry.
57+
58+
#### --reg-password-stdin
59+
60+
The `--reg-password-stdin` flag enables reading of registry password from stdin.
61+
62+
#### --reg-token-stdin
63+
64+
The `--reg-token-stdin` flag enables reading of registry token from stdin.

‎docs/reference/versions.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Versions"
33
layout: default
4-
sort: 9
4+
sort: 10
55
---
66

77
# Versions and deprecation

‎docs/usage/image-compatibility.md

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
---
2+
title: "Image Compatibility Artifact"
3+
layout: default
4+
sort: 11
5+
---
6+
7+
# Image Compatibility Artifact
8+
{: .no_toc}
9+
10+
## Table of contents
11+
{: .no_toc .text-delta}
12+
13+
1. TOC
14+
{:toc}
15+
16+
---
17+
18+
## Image Compatibility (experimental: v1alpha1 version)
19+
20+
Image compatibility metadata enables container image authors to define their
21+
image requirements using [Node Feature Rules](./custom-resources.md#nodefeaturerule).
22+
This complementary solution allows features discovered on nodes to be matched
23+
directly from images. As a result, container requirements become discoverable
24+
and programmable, supporting various consumers and use cases where applications
25+
need a specific compatible environment.
26+
27+
### Compatibility Specification
28+
29+
The compatibility specification is a list of compatibility objects that contain
30+
[Node Feature Rules](./custom-resources.md#nodefeaturerule), along with
31+
additional fields to control the execution of validation between the image and
32+
the host.
33+
34+
### Schema
35+
36+
- **version** - *string*
37+
This REQUIRED property specifies the version of the API in use.
38+
39+
- **compatibilities** - *array of object*
40+
This REQUIRED property is a list of compatibility sets.
41+
42+
- **rules** - *object*
43+
This REQUIRED property is a reference to the spec of the [NodeFeatureRule API](./custom-resources.md#nodefeaturerule).
44+
The spec allows image requirements to be described using the features
45+
discovered from NFD sources. For more details, please refer to [the documentation](./custom-resources.md#nodefeaturerule).
46+
47+
- **weight** - *int*
48+
This OPTIONAL property specifies the [node affinity weight](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity-weight).
49+
50+
- **tag** - *string*
51+
This OPTIONAL property allows for the grouping or separation of
52+
compatibility sets.
53+
54+
- **description** - *string*
55+
This OPTIONAL property provides a brief description of a compatibility set.
56+
57+
#### Example
58+
59+
```yaml
60+
version: v1alpha1
61+
compatibilities:
62+
- description: "My image requirements"
63+
rules:
64+
- name: "kernel and cpu"
65+
matchFeatures:
66+
- feature: kernel.loadedmodule
67+
matchExpressions:
68+
vfio-pci: {op: Exists}
69+
- feature: cpu.model
70+
matchExpressions:
71+
vendor_id: {op: In, value: ["Intel", "AMD"]}
72+
- name: "one of available nics"
73+
matchAny:
74+
- matchFeatures:
75+
- feature: pci.device
76+
matchExpressions:
77+
vendor: {op: In, value: ["0eee"]}
78+
class: {op: In, value: ["0200"]}
79+
- matchFeatures:
80+
- feature: pci.device
81+
matchExpressions:
82+
vendor: {op: In, value: ["0fff"]}
83+
class: {op: In, value: ["0200"]}
84+
```
85+
86+
### OCI Artifact
87+
88+
An [OCI artifact](https://github.com/opencontainers/image-spec/blob/main/manifest.md#guidelines-for-artifact-usage)
89+
is used to store image compatibility metadata.
90+
The artifact can be associated with a specific image through [the subject field](https://github.com/opencontainers/distribution-spec/blob/11b8e3fba7d2d7329513d0cff53058243c334858/spec.md#pushing-manifests-with-subject)
91+
and pushed to the registry along with the image.
92+
93+
Example manifest:
94+
95+
```json
96+
{
97+
"schemaVersion": 2,
98+
"mediaType": "application/vnd.oci.image.manifest.v1+json",
99+
"artifactType": "application/vnd.nfd.image-compatibility.v1alpha1",
100+
"config": {
101+
"mediaType": "application/vnd.oci.empty.v1+json",
102+
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
103+
"size": 2
104+
},
105+
"layers": [
106+
{
107+
"mediaType": "application/vnd.nfd.image-compatibility.spec.v1alpha1+yaml",
108+
"digest": "sha256:4a47f8ae4c713906618413cb9795824d09eeadf948729e213a1ba11a1e31d052",
109+
"size": 1710
110+
}
111+
],
112+
"subject": {
113+
"mediaType": "application/vnd.oci.image.manifest.v1+json",
114+
"digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",
115+
"size": 7682
116+
},
117+
"annotations": {
118+
"oci.opencontainers.image.created": "2024-03-27T08:08:08Z"
119+
}
120+
}
121+
```
122+
123+
#### Attach the artifact to the image
124+
125+
Create an image compatibility specification for the image, then install the
126+
[ORAS](https://github.com/oras-project/oras/) tool and execute `oras attach`
127+
command.
128+
129+
Example:
130+
131+
```sh
132+
oras attach --artifact-type application/vnd.nfd.image-compatibility.v1alpha1 \
133+
<image-url> <path-to-spec>.yaml:application/vnd.nfd.image-compatibility.spec.v1alpha1+yaml
134+
```
135+
136+
**Note**: The attach command is planned to be integrated into the `nfd` client
137+
tool. This will streamline the process, allowing you to perform the operation
138+
directly within the tool rather than using a separate command.
139+
140+
### Validate the host against the image compatibility specification
141+
142+
1. Build `nfd` client: `make build`
143+
1. Run `./bin/nfd compat validate-node --image <image-url>`
144+
145+
For more information about the available commands and flags, refer to
146+
[the client documentation](../reference/node-feature-client-reference.md).
147+
148+
### Validate the k8s cluster node with the validate-image Job
149+
150+
**Note**: This does not require installation of NFD master and workers.
151+
Additionally, public registry certificates must be included in the job.
152+
In the example below, this is done using hostPath,
153+
but it can be done using any Kubernetes-supported method.
154+
155+
```yaml
156+
apiVersion: batch/v1
157+
kind: Job
158+
metadata:
159+
name: validate-image
160+
spec:
161+
backoffLimit: 1
162+
template:
163+
spec:
164+
restartPolicy: Never
165+
containers:
166+
- name: image-compatibility
167+
securityContext:
168+
allowPrivilegeEscalation: false
169+
capabilities:
170+
drop:
171+
- ALL
172+
readOnlyRootFilesystem: true
173+
runAsNonRoot: true
174+
image: <image-with-nfd-client>
175+
command: ["nfd", "compat", "validate-node", "--image", "<image-to-be-validated>"]
176+
volumeMounts:
177+
- mountPath: /host-boot
178+
name: host-boot
179+
readOnly: true
180+
- mountPath: /host-etc/os-release
181+
name: host-os-release
182+
readOnly: true
183+
- mountPath: /host-sys
184+
name: host-sys
185+
readOnly: true
186+
- mountPath: /host-usr/lib
187+
name: host-usr-lib
188+
readOnly: true
189+
- mountPath: /host-lib
190+
name: host-lib
191+
readOnly: true
192+
- mountPath: /host-proc
193+
name: host-proc
194+
readOnly: true
195+
volumes:
196+
- hostPath:
197+
path: /boot
198+
type: ""
199+
name: host-boot
200+
- hostPath:
201+
path: /etc/os-release
202+
type: ""
203+
name: host-os-release
204+
- hostPath:
205+
path: /sys
206+
type: ""
207+
name: host-sys
208+
- hostPath:
209+
path: /usr/lib
210+
type: ""
211+
name: host-usr-lib
212+
- hostPath:
213+
path: /lib
214+
type: ""
215+
name: host-lib
216+
- hostPath:
217+
path: /proc
218+
type: ""
219+
name: host-proc
220+
- hostPath:
221+
path: "<path-to-registry-public-certs>"
222+
type: ""
223+
name: certs
224+
```

0 commit comments

Comments
 (0)