Skip to content

Commit 7d1df87

Browse files
committed
source/custom: drop support for the legacy rule format
1 parent 160c910 commit 7d1df87

File tree

9 files changed

+19
-681
lines changed

9 files changed

+19
-681
lines changed

docs/usage/customization-guide.md

Lines changed: 0 additions & 275 deletions
Original file line numberDiff line numberDiff line change
@@ -1062,278 +1062,3 @@ must be present):
10621062
vendor: "0fff"
10631063
device: "abcd"
10641064
```
1065-
1066-
## Legacy custom rule syntax
1067-
1068-
**DEPRECATED**: use the new rule syntax instead.
1069-
1070-
The `custom` source supports the legacy `matchOn` rule syntax for
1071-
backwards-compatibility.
1072-
1073-
To aid in making the legacy rule syntax clearer, we define a general and a per
1074-
rule nomenclature, keeping things as consistent as possible.
1075-
1076-
### General nomenclature and definitions
1077-
1078-
```plaintext
1079-
Rule :Represents a matching logic that is used to match on a feature.
1080-
Rule Input :The input a Rule is provided. This determines how a Rule performs the match operation.
1081-
Matcher :A composition of Rules, each Matcher may be composed of at most one instance of each Rule.
1082-
```
1083-
1084-
### Custom features format (using the nomenclature defined above)
1085-
1086-
Rules are specified under `sources.custom` in the nfd-worker configuration
1087-
file.
1088-
1089-
```yaml
1090-
sources:
1091-
custom:
1092-
- name: <feature name>
1093-
value: <optional feature value, defaults to "true">
1094-
matchOn:
1095-
- <Rule-1>: <Rule-1 Input>
1096-
[<Rule-2>: <Rule-2 Input>]
1097-
- <Matcher-2>
1098-
- ...
1099-
- ...
1100-
- <Matcher-N>
1101-
- <custom feature 2>
1102-
- ...
1103-
- ...
1104-
- <custom feature M>
1105-
```
1106-
1107-
The label is constructed by adding `custom-` prefix to the name field, label
1108-
value defaults to `true` if not specified in the rule spec:
1109-
1110-
```plaintext
1111-
feature.node.kubernetes.io/custom-<name> = <value>
1112-
```
1113-
1114-
### Matching process
1115-
1116-
Specifying Rules to match on a feature is done by providing a list of Matchers.
1117-
Each Matcher contains one or more Rules.
1118-
1119-
Logical _OR_ is performed between Matchers and logical _AND_ is performed
1120-
between Rules of a given Matcher.
1121-
1122-
### Rules
1123-
1124-
#### pciid rule
1125-
1126-
##### Nomenclature
1127-
1128-
```plaintext
1129-
Attribute :A PCI attribute.
1130-
Element :An identifier of the PCI attribute.
1131-
```
1132-
1133-
The PciId Rule allows matching the PCI devices in the system on the following
1134-
Attributes: `class`,`vendor` and `device`. A list of Elements is provided for
1135-
each Attribute.
1136-
1137-
##### Format
1138-
1139-
```yaml
1140-
pciId :
1141-
class: [<class id>, ...]
1142-
vendor: [<vendor id>, ...]
1143-
device: [<device id>, ...]
1144-
```
1145-
1146-
Matching is done by performing a logical _OR_ between Elements of an Attribute
1147-
and logical _AND_ between the specified Attributes for each PCI device in the
1148-
system. At least one Attribute must be specified. Missing attributes will not
1149-
partake in the matching process.
1150-
1151-
#### UsbId rule
1152-
1153-
##### Nomenclature
1154-
1155-
```plaintext
1156-
Attribute :A USB attribute.
1157-
Element :An identifier of the USB attribute.
1158-
```
1159-
1160-
The UsbId Rule allows matching the USB devices in the system on the following
1161-
Attributes: `class`,`vendor`, `device` and `serial`. A list of Elements is
1162-
provided for each Attribute.
1163-
1164-
##### Format
1165-
1166-
```yaml
1167-
usbId :
1168-
class: [<class id>, ...]
1169-
vendor: [<vendor id>, ...]
1170-
device: [<device id>, ...]
1171-
serial: [<serial>, ...]
1172-
```
1173-
1174-
Matching is done by performing a logical _OR_ between Elements of an Attribute
1175-
and logical _AND_ between the specified Attributes for each USB device in the
1176-
system. At least one Attribute must be specified. Missing attributes will not
1177-
partake in the matching process.
1178-
1179-
#### LoadedKMod rule
1180-
1181-
##### Nomenclature
1182-
1183-
```plaintext
1184-
Element :A kernel module
1185-
```
1186-
1187-
The LoadedKMod Rule allows matching the loaded kernel modules in the system
1188-
against a provided list of Elements.
1189-
1190-
##### Format
1191-
1192-
```yaml
1193-
loadedKMod : [<kernel module>, ...]
1194-
```
1195-
1196-
Matching is done by performing logical _AND_ for each provided Element, i.e
1197-
the Rule will match if all provided Elements (kernel modules) are loaded in the
1198-
system.
1199-
1200-
#### CpuId rule
1201-
1202-
##### Nomenclature
1203-
1204-
```plaintext
1205-
Element :A CPUID flag
1206-
```
1207-
1208-
The Rule allows matching the available CPUID flags in the system against a
1209-
provided list of Elements.
1210-
1211-
##### Format
1212-
1213-
```yaml
1214-
cpuId : [<CPUID flag string>, ...]
1215-
```
1216-
1217-
Matching is done by performing logical _AND_ for each provided Element, i.e the
1218-
Rule will match if all provided Elements (CPUID flag strings) are available in
1219-
the system.
1220-
1221-
#### Kconfig rule
1222-
1223-
##### Nomenclature
1224-
1225-
```plaintext
1226-
Element :A Kconfig option
1227-
```
1228-
1229-
The Rule allows matching the kconfig options in the system against a provided
1230-
list of Elements.
1231-
1232-
##### Format
1233-
1234-
```yaml
1235-
kConfig: [<kernel config option ('y' or 'm') or '=<value>'>, ...]
1236-
```
1237-
1238-
Matching is done by performing logical _AND_ for each provided Element, i.e the
1239-
Rule will match if all provided Elements (kernel config options) are enabled
1240-
(`y` or `m`) or matching `=<value>` in the kernel.
1241-
1242-
#### Nodename rule
1243-
1244-
##### Nomenclature
1245-
1246-
```plaintext
1247-
Element :A nodename regexp pattern
1248-
```
1249-
1250-
The Rule allows matching the node's name against a provided list of Elements.
1251-
1252-
##### Format
1253-
1254-
```yaml
1255-
nodename: [ <nodename regexp pattern>, ... ]
1256-
```
1257-
1258-
Matching is done by performing logical _OR_ for each provided Element, i.e the
1259-
Rule will match if one of the provided Elements (nodename regexp pattern)
1260-
matches the node's name.
1261-
1262-
### Legacy custom rule example
1263-
1264-
```yaml
1265-
custom:
1266-
- name: "my.kernel.feature"
1267-
matchOn:
1268-
- loadedKMod: ["kmod1", "kmod2"]
1269-
- name: "my.pci.feature"
1270-
matchOn:
1271-
- pciId:
1272-
vendor: ["15b3"]
1273-
device: ["1014", "1017"]
1274-
- name: "my.usb.feature"
1275-
matchOn:
1276-
- usbId:
1277-
vendor: ["1d6b"]
1278-
device: ["0003"]
1279-
serial: ["090129a"]
1280-
- name: "my.combined.feature"
1281-
matchOn:
1282-
- loadedKMod : ["vendor_kmod1", "vendor_kmod2"]
1283-
pciId:
1284-
vendor: ["15b3"]
1285-
device: ["1014", "1017"]
1286-
- name: "vendor.feature.node.kubernetes.io/accumulated.feature"
1287-
matchOn:
1288-
- loadedKMod : ["some_kmod1", "some_kmod2"]
1289-
- pciId:
1290-
vendor: ["15b3"]
1291-
device: ["1014", "1017"]
1292-
- name: "my.kernel.featureneedscpu"
1293-
matchOn:
1294-
- kConfig: ["KVM_INTEL"]
1295-
- cpuId: ["VMX"]
1296-
- name: "my.kernel.modulecompiler"
1297-
matchOn:
1298-
- kConfig: ["GCC_VERSION=100101"]
1299-
loadedKMod: ["kmod1"]
1300-
- name: "profile.node.kubernetes.io/my-datacenter"
1301-
value: "datacenter-1"
1302-
matchOn:
1303-
- nodename: [ "node-datacenter1-rack.*-server.*" ]
1304-
```
1305-
1306-
__In the example above:__
1307-
1308-
- A node would contain the label:
1309-
`feature.node.kubernetes.io/custom-my.kernel.feature=true` if the node has
1310-
`kmod1` _AND_ `kmod2` kernel modules loaded.
1311-
- A node would contain the label:
1312-
`feature.node.kubernetes.io/custom-my.pci.feature=true` if the node contains
1313-
a PCI device with a PCI vendor ID of `15b3` _AND_ PCI device ID of `1014` _OR_
1314-
`1017`.
1315-
- A node would contain the label:
1316-
`feature.node.kubernetes.io/custom-my.usb.feature=true` if the node contains
1317-
a USB device with a USB vendor ID of `1d6b` _AND_ USB device ID of `0003`.
1318-
- A node would contain the label:
1319-
`feature.node.kubernetes.io/custom-my.combined.feature=true` if
1320-
`vendor_kmod1` _AND_ `vendor_kmod2` kernel modules are loaded __AND__ the node
1321-
contains a PCI device
1322-
with a PCI vendor ID of `15b3` _AND_ PCI device ID of `1014` _or_ `1017`.
1323-
- A node would contain the label:
1324-
`vendor.feature.node.kubernetes.io/accumulated.feature=true` if
1325-
`some_kmod1` _AND_ `some_kmod2` kernel modules are loaded __OR__ the node
1326-
contains a PCI device
1327-
with a PCI vendor ID of `15b3` _AND_ PCI device ID of `1014` _OR_ `1017`.
1328-
- A node would contain the label:
1329-
`feature.node.kubernetes.io/custom-my.kernel.featureneedscpu=true` if
1330-
`KVM_INTEL` kernel config is enabled __AND__ the node CPU supports `VMX`
1331-
virtual machine extensions
1332-
- A node would contain the label:
1333-
`feature.node.kubernetes.io/custom-my.kernel.modulecompiler=true` if the
1334-
in-tree `kmod1` kernel module is loaded __AND__ it's built with
1335-
`GCC_VERSION=100101`.
1336-
- A node would contain the label:
1337-
`profile.node.kubernetes.io/my-datacenter=datacenter-1` if the node's name
1338-
matches the `node-datacenter1-rack.*-server.*` pattern, e.g.
1339-
`node-datacenter1-rack2-server42`

0 commit comments

Comments
 (0)