Skip to content

Commit

Permalink
Merge pull request kubernetes-sigs#1397 from marquiz/devel/custom-leg…
Browse files Browse the repository at this point in the history 
…acy-rule-format

source/custom: drop support for the legacy rule format
  • Loading branch information
@k8s-ci-robot
k8s-ci-robot authored Oct 13, 2023
2 parents e1d1715 + 7d1df87 commit b6419c7
Show file tree
Hide file tree
Showing 9 changed files with 19 additions and 681 deletions.
275 changes: 0 additions & 275 deletions docs/usage/customization-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1062,278 +1062,3 @@ must be present):
vendor: "0fff"
device: "abcd"
```

## Legacy custom rule syntax

**DEPRECATED**: use the new rule syntax instead.

The `custom` source supports the legacy `matchOn` rule syntax for
backwards-compatibility.

To aid in making the legacy rule syntax clearer, we define a general and a per
rule nomenclature, keeping things as consistent as possible.

### General nomenclature and definitions

```plaintext
Rule :Represents a matching logic that is used to match on a feature.
Rule Input :The input a Rule is provided. This determines how a Rule performs the match operation.
Matcher :A composition of Rules, each Matcher may be composed of at most one instance of each Rule.
```

### Custom features format (using the nomenclature defined above)

Rules are specified under `sources.custom` in the nfd-worker configuration
file.

```yaml
sources:
custom:
- name: <feature name>
value: <optional feature value, defaults to "true">
matchOn:
- <Rule-1>: <Rule-1 Input>
[<Rule-2>: <Rule-2 Input>]
- <Matcher-2>
- ...
- ...
- <Matcher-N>
- <custom feature 2>
- ...
- ...
- <custom feature M>
```

The label is constructed by adding `custom-` prefix to the name field, label
value defaults to `true` if not specified in the rule spec:

```plaintext
feature.node.kubernetes.io/custom-<name> = <value>
```

### Matching process

Specifying Rules to match on a feature is done by providing a list of Matchers.
Each Matcher contains one or more Rules.

Logical _OR_ is performed between Matchers and logical _AND_ is performed
between Rules of a given Matcher.

### Rules

#### pciid rule

##### Nomenclature

```plaintext
Attribute :A PCI attribute.
Element :An identifier of the PCI attribute.
```

The PciId Rule allows matching the PCI devices in the system on the following
Attributes: `class`,`vendor` and `device`. A list of Elements is provided for
each Attribute.

##### Format

```yaml
pciId :
class: [<class id>, ...]
vendor: [<vendor id>, ...]
device: [<device id>, ...]
```

Matching is done by performing a logical _OR_ between Elements of an Attribute
and logical _AND_ between the specified Attributes for each PCI device in the
system. At least one Attribute must be specified. Missing attributes will not
partake in the matching process.

#### UsbId rule

##### Nomenclature

```plaintext
Attribute :A USB attribute.
Element :An identifier of the USB attribute.
```

The UsbId Rule allows matching the USB devices in the system on the following
Attributes: `class`,`vendor`, `device` and `serial`. A list of Elements is
provided for each Attribute.

##### Format

```yaml
usbId :
class: [<class id>, ...]
vendor: [<vendor id>, ...]
device: [<device id>, ...]
serial: [<serial>, ...]
```

Matching is done by performing a logical _OR_ between Elements of an Attribute
and logical _AND_ between the specified Attributes for each USB device in the
system. At least one Attribute must be specified. Missing attributes will not
partake in the matching process.

#### LoadedKMod rule

##### Nomenclature

```plaintext
Element :A kernel module
```

The LoadedKMod Rule allows matching the loaded kernel modules in the system
against a provided list of Elements.

##### Format

```yaml
loadedKMod : [<kernel module>, ...]
```

Matching is done by performing logical _AND_ for each provided Element, i.e
the Rule will match if all provided Elements (kernel modules) are loaded in the
system.

#### CpuId rule

##### Nomenclature

```plaintext
Element :A CPUID flag
```

The Rule allows matching the available CPUID flags in the system against a
provided list of Elements.

##### Format

```yaml
cpuId : [<CPUID flag string>, ...]
```

Matching is done by performing logical _AND_ for each provided Element, i.e the
Rule will match if all provided Elements (CPUID flag strings) are available in
the system.

#### Kconfig rule

##### Nomenclature

```plaintext
Element :A Kconfig option
```

The Rule allows matching the kconfig options in the system against a provided
list of Elements.

##### Format

```yaml
kConfig: [<kernel config option ('y' or 'm') or '=<value>'>, ...]
```

Matching is done by performing logical _AND_ for each provided Element, i.e the
Rule will match if all provided Elements (kernel config options) are enabled
(`y` or `m`) or matching `=<value>` in the kernel.

#### Nodename rule

##### Nomenclature

```plaintext
Element :A nodename regexp pattern
```

The Rule allows matching the node's name against a provided list of Elements.

##### Format

```yaml
nodename: [ <nodename regexp pattern>, ... ]
```

Matching is done by performing logical _OR_ for each provided Element, i.e the
Rule will match if one of the provided Elements (nodename regexp pattern)
matches the node's name.

### Legacy custom rule example

```yaml
custom:
- name: "my.kernel.feature"
matchOn:
- loadedKMod: ["kmod1", "kmod2"]
- name: "my.pci.feature"
matchOn:
- pciId:
vendor: ["15b3"]
device: ["1014", "1017"]
- name: "my.usb.feature"
matchOn:
- usbId:
vendor: ["1d6b"]
device: ["0003"]
serial: ["090129a"]
- name: "my.combined.feature"
matchOn:
- loadedKMod : ["vendor_kmod1", "vendor_kmod2"]
pciId:
vendor: ["15b3"]
device: ["1014", "1017"]
- name: "vendor.feature.node.kubernetes.io/accumulated.feature"
matchOn:
- loadedKMod : ["some_kmod1", "some_kmod2"]
- pciId:
vendor: ["15b3"]
device: ["1014", "1017"]
- name: "my.kernel.featureneedscpu"
matchOn:
- kConfig: ["KVM_INTEL"]
- cpuId: ["VMX"]
- name: "my.kernel.modulecompiler"
matchOn:
- kConfig: ["GCC_VERSION=100101"]
loadedKMod: ["kmod1"]
- name: "profile.node.kubernetes.io/my-datacenter"
value: "datacenter-1"
matchOn:
- nodename: [ "node-datacenter1-rack.*-server.*" ]
```

__In the example above:__

- A node would contain the label:
`feature.node.kubernetes.io/custom-my.kernel.feature=true` if the node has
`kmod1` _AND_ `kmod2` kernel modules loaded.
- A node would contain the label:
`feature.node.kubernetes.io/custom-my.pci.feature=true` if the node contains
a PCI device with a PCI vendor ID of `15b3` _AND_ PCI device ID of `1014` _OR_
`1017`.
- A node would contain the label:
`feature.node.kubernetes.io/custom-my.usb.feature=true` if the node contains
a USB device with a USB vendor ID of `1d6b` _AND_ USB device ID of `0003`.
- A node would contain the label:
`feature.node.kubernetes.io/custom-my.combined.feature=true` if
`vendor_kmod1` _AND_ `vendor_kmod2` kernel modules are loaded __AND__ the node
contains a PCI device
with a PCI vendor ID of `15b3` _AND_ PCI device ID of `1014` _or_ `1017`.
- A node would contain the label:
`vendor.feature.node.kubernetes.io/accumulated.feature=true` if
`some_kmod1` _AND_ `some_kmod2` kernel modules are loaded __OR__ the node
contains a PCI device
with a PCI vendor ID of `15b3` _AND_ PCI device ID of `1014` _OR_ `1017`.
- A node would contain the label:
`feature.node.kubernetes.io/custom-my.kernel.featureneedscpu=true` if
`KVM_INTEL` kernel config is enabled __AND__ the node CPU supports `VMX`
virtual machine extensions
- A node would contain the label:
`feature.node.kubernetes.io/custom-my.kernel.modulecompiler=true` if the
in-tree `kmod1` kernel module is loaded __AND__ it's built with
`GCC_VERSION=100101`.
- A node would contain the label:
`profile.node.kubernetes.io/my-datacenter=datacenter-1` if the node's name
matches the `node-datacenter1-rack.*-server.*` pattern, e.g.
`node-datacenter1-rack2-server42`
Loading

0 comments on commit b6419c7

Please sign in to comment.