mirror of
https://github.com/kubernetes-sigs/node-feature-discovery.git
synced 2025-03-17 05:48:21 +00:00
Simplify and rationalize the compat api. Many of the fields in Rule, like Labels, Annotations or ExtendedResources are not applicable in this context.
227 lines
6.9 KiB
Markdown
227 lines
6.9 KiB
Markdown
---
|
|
title: "Image Compatibility Artifact"
|
|
layout: default
|
|
sort: 11
|
|
---
|
|
|
|
# Image Compatibility Artifact
|
|
{: .no_toc}
|
|
|
|
## Table of contents
|
|
{: .no_toc .text-delta}
|
|
|
|
1. TOC
|
|
{:toc}
|
|
|
|
---
|
|
|
|
## Image Compatibility
|
|
|
|
**Image Compatibility is in the experimental `v1alpha1` version.**
|
|
|
|
Image compatibility metadata enables container image authors to define their
|
|
image requirements using a spec similar to
|
|
[Node Feature Groups](./custom-resources.md#nodefeaturegroup).
|
|
This complementary solution allows features discovered on nodes to be matched
|
|
directly from images. As a result, container requirements become discoverable
|
|
and programmable, supporting various consumers and use cases where applications
|
|
need a specific compatible environment.
|
|
|
|
### Compatibility Specification
|
|
|
|
The compatibility specification is a list of compatibility objects that contain
|
|
rules similar to [Node Feature Groups](./custom-resources.md#nodefeaturegroup),
|
|
along with additional fields to control the execution of validation between the
|
|
image and the host.
|
|
|
|
### Schema
|
|
|
|
- **version** - *string*
|
|
This REQUIRED property specifies the version of the API in use.
|
|
|
|
- **compatibilities** - *array of object*
|
|
This REQUIRED property is a list of compatibility sets.
|
|
|
|
- **rules** - *object*
|
|
This REQUIRED property is a reference to the spec of the [NodeFeatureGroup API](./custom-resources.md#nodefeaturegroup).
|
|
The spec allows image requirements to be described using the features
|
|
discovered from NFD sources. For more details, please refer to [the documentation](./custom-resources.md#nodefeaturegroup).
|
|
|
|
- **weight** - *int*
|
|
This OPTIONAL property specifies the [node affinity weight](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity-weight).
|
|
|
|
- **tag** - *string*
|
|
This OPTIONAL property allows for the grouping or separation of
|
|
compatibility sets.
|
|
|
|
- **description** - *string*
|
|
This OPTIONAL property provides a brief description of a compatibility set.
|
|
|
|
#### Example
|
|
|
|
```yaml
|
|
version: v1alpha1
|
|
compatibilities:
|
|
- description: "My image requirements"
|
|
rules:
|
|
- name: "kernel and cpu"
|
|
matchFeatures:
|
|
- feature: kernel.loadedmodule
|
|
matchExpressions:
|
|
vfio-pci: {op: Exists}
|
|
- feature: cpu.model
|
|
matchExpressions:
|
|
vendor_id: {op: In, value: ["Intel", "AMD"]}
|
|
- name: "one of available nics"
|
|
matchAny:
|
|
- matchFeatures:
|
|
- feature: pci.device
|
|
matchExpressions:
|
|
vendor: {op: In, value: ["0eee"]}
|
|
class: {op: In, value: ["0200"]}
|
|
- matchFeatures:
|
|
- feature: pci.device
|
|
matchExpressions:
|
|
vendor: {op: In, value: ["0fff"]}
|
|
class: {op: In, value: ["0200"]}
|
|
```
|
|
|
|
### OCI Artifact
|
|
|
|
An [OCI artifact](https://github.com/opencontainers/image-spec/blob/main/manifest.md#guidelines-for-artifact-usage)
|
|
is used to store image compatibility metadata.
|
|
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)
|
|
and pushed to the registry along with the image.
|
|
|
|
Example manifest:
|
|
|
|
```json
|
|
{
|
|
"schemaVersion": 2,
|
|
"mediaType": "application/vnd.oci.image.manifest.v1+json",
|
|
"artifactType": "application/vnd.nfd.image-compatibility.v1alpha1",
|
|
"config": {
|
|
"mediaType": "application/vnd.oci.empty.v1+json",
|
|
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
|
|
"size": 2
|
|
},
|
|
"layers": [
|
|
{
|
|
"mediaType": "application/vnd.nfd.image-compatibility.spec.v1alpha1+yaml",
|
|
"digest": "sha256:4a47f8ae4c713906618413cb9795824d09eeadf948729e213a1ba11a1e31d052",
|
|
"size": 1710
|
|
}
|
|
],
|
|
"subject": {
|
|
"mediaType": "application/vnd.oci.image.manifest.v1+json",
|
|
"digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",
|
|
"size": 7682
|
|
},
|
|
"annotations": {
|
|
"oci.opencontainers.image.created": "2024-03-27T08:08:08Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Attach the artifact to the image
|
|
|
|
Create an image compatibility specification for the image, then install the
|
|
[ORAS](https://github.com/oras-project/oras/) tool and execute `oras attach`
|
|
command.
|
|
|
|
Example:
|
|
|
|
```sh
|
|
oras attach --artifact-type application/vnd.nfd.image-compatibility.v1alpha1 \
|
|
<image-url> <path-to-spec>.yaml:application/vnd.nfd.image-compatibility.spec.v1alpha1+yaml
|
|
```
|
|
|
|
**Note**: The attach command is planned to be integrated into the `nfd` client
|
|
tool. This will streamline the process, allowing you to perform the operation
|
|
directly within the tool rather than using a separate command.
|
|
|
|
### Validate the host against the image compatibility specification
|
|
|
|
1. Build `nfd` client: `make build`
|
|
1. Run `./bin/nfd compat validate-node --image <image-url>`
|
|
|
|
For more information about the available commands and flags, refer to
|
|
[the client documentation](../reference/node-feature-client-reference.md).
|
|
|
|
### Validate the k8s cluster node with the validate-image Job
|
|
|
|
**Note**: This does not require installation of NFD master and workers.
|
|
Additionally, public registry certificates must be included in the job.
|
|
In the example below, this is done using hostPath,
|
|
but it can be done using any Kubernetes-supported method.
|
|
|
|
```yaml
|
|
apiVersion: batch/v1
|
|
kind: Job
|
|
metadata:
|
|
name: validate-image
|
|
spec:
|
|
backoffLimit: 1
|
|
template:
|
|
spec:
|
|
restartPolicy: Never
|
|
containers:
|
|
- name: image-compatibility
|
|
securityContext:
|
|
allowPrivilegeEscalation: false
|
|
capabilities:
|
|
drop:
|
|
- ALL
|
|
readOnlyRootFilesystem: true
|
|
runAsNonRoot: true
|
|
image: <image-with-nfd-client>
|
|
command: ["nfd", "compat", "validate-node", "--image", "<image-to-be-validated>"]
|
|
volumeMounts:
|
|
- mountPath: /host-boot
|
|
name: host-boot
|
|
readOnly: true
|
|
- mountPath: /host-etc/os-release
|
|
name: host-os-release
|
|
readOnly: true
|
|
- mountPath: /host-sys
|
|
name: host-sys
|
|
readOnly: true
|
|
- mountPath: /host-usr/lib
|
|
name: host-usr-lib
|
|
readOnly: true
|
|
- mountPath: /host-lib
|
|
name: host-lib
|
|
readOnly: true
|
|
- mountPath: /host-proc
|
|
name: host-proc
|
|
readOnly: true
|
|
volumes:
|
|
- hostPath:
|
|
path: /boot
|
|
type: ""
|
|
name: host-boot
|
|
- hostPath:
|
|
path: /etc/os-release
|
|
type: ""
|
|
name: host-os-release
|
|
- hostPath:
|
|
path: /sys
|
|
type: ""
|
|
name: host-sys
|
|
- hostPath:
|
|
path: /usr/lib
|
|
type: ""
|
|
name: host-usr-lib
|
|
- hostPath:
|
|
path: /lib
|
|
type: ""
|
|
name: host-lib
|
|
- hostPath:
|
|
path: /proc
|
|
type: ""
|
|
name: host-proc
|
|
- hostPath:
|
|
path: "<path-to-registry-public-certs>"
|
|
type: ""
|
|
name: certs
|
|
```
|