1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/node-feature-discovery.git synced 2024-12-14 11:57:51 +00:00

source/custom: implement generic feature matching

Implement generic feature matchers that cover all feature sources (that
implement the FeatureSource interface). The implementation relies on the
unified data model provided by the FeatureSource interface as well as
the generic expression-based rule processing framework that was added to
the source/custom/expression package.

With this patch any new features added will be automatically available
for custom rules, without any additional work. Rule hierarchy follows
the source/feature hierarchy by design.

This patch introduces a new format for custom rule specifications,
dropping the 'value' field and introducing new 'labels' field which
makes it possible to specify multiple labels per rule. Also, in the new
format the 'name' field is just for reference and no matching label is
created. The new generic rules are available in this new rule format
under a 'matchFeatures. MatchFeatures implements a logical AND over
an array of per-feature matchers - i.e. a match for all of the matchers
is required. The goal of the new rule format is to make it better follow
K8s API design guidelines and make it extensible for future enhancements
(e.g. addition of templating, taints, annotations, extended resources
etc).

The old rule format (with cpuID, kConfig, loadedKMod, nodename, pciID,
usbID rules) is still supported. The rule format (new vs. old) is
determined at config parsing time based on the existence of the
'matchOn' field.

The new rule format and the configuration format for the new
matchFeatures field is

  - name: <rule-name>
    labels:
      <key>: <value>
      ...
    matchFeatures:
      - feature: <domain>.<feature>
        matchExpressions:
          <attribute>:
            op: <operator>
            value:
              - <list-of-values>
      - feature: <domain>.<feature>
        ...

Currently, "cpu", "kernel", "pci", "system", "usb" and "local" sources
are covered by the matshers/feature selectors. Thus, the following
features are available for matching with this patch:

  - cpu.cpuid:
      <cpuid-flag>: <exists/does-not-exist>
  - cpu.cstate:
      enabled: <bool>
  - cpu.pstate:
      status: <string>
      turbo: <bool>
      scaling_governor: <string>
  - cpu.rdt:
      <rdt-feature>: <exists/does-not-exist>
  - cpu.sst:
      bf.enabled: <bool>
  - cpu.topology:
      hardware_multithreading: <bool>
  - kernel.config:
      <flag-name>: <string>
  - kernel.loadedmodule:
      <module-name>: <exists/does-not-exist>
  - kernel.selinux:
      enabled: <bool>
  - kernel.version:
      major: <int>
      minor: <int>
      revision: <int>
      full: <string>
  - system.osrelease:
      <key-name>: <string>
      VERSION_ID.major: <int>
      VERSION_ID.minor: <int>
  - system.name:
      nodename: <string>
  - pci.device:
      <device-instance>:
        class: <string>
        vendor: <string>
        device: <string>
        subsystem_vendor: <string>
        susbystem_device: <string>
        sriov_totalvfs: <int>
  - usb.device:
      <device-instance>:
        class: <string>
        vendor: <string>
        device: <string>
        serial: <string>
  - local.label:
      <label-name>: <string>

The configuration also supports some "shortforms" for convenience:

   matchExpressions: [<attr-1>, <attr-2>=<val-2>]
   ---
   matchExpressions:
     <attr-3>:
     <attr-4>: <val-4>

is equal to:

   matchExpressions:
     <attr-1>: {op: Exists}
     <attr-2>: {op: In, value: [<val-2>]}
   ---
   matchExpressions:
     <attr-3>: {op: Exists}
     <attr-4>: {op: In, value: [<val-4>]}

In other words:

  - feature: kernel.config
    matchExpressions: ["X86", "INIT_ENV_ARG_LIMIT=32"]
  - feature: pci.device
    matchExpressions:
      vendor: "8086"

is the same as:

  - feature: kernel.config
    matchExpressions:
      X86: {op: Exists}
      INIT_ENV_ARG_LIMIT: {op: In, values: ["32"]}
  - feature: pci.device
    matchExpressions:
      vendor: {op: In, value: ["8086"]

Some configuration examples below. In order to match a CPUID feature the
following snippet can be used:

  - name: cpu-test-1
    labels:
      cpu-custom-feature: "true"
    matchFeatures:
      - feature: cpu.cpuid
        matchExpressions:
          AESNI: {op: Exists}
          AVX: {op: Exists}

In order to match against a loaded kernel module and OS version:

  - name: kernel-test-1
    labels:
      kernel-custom-feature: "true"
    matchFeatures:
      - feature: kernel.loadedmodule
        matchExpressions:
          e1000: {op: Exists}
      - feature: system.osrelease
        matchExpressions:
          NAME: {op: InRegexp, values: ["^openSUSE"]}
          VERSION_ID.major: {op: Gt, values: ["14"]}

In order to require a kernel module and both of two specific PCI devices:

  - name: multi-device-test
    labels:
      multi-device-feature: "true"
    matchFeatures:
      - feature: kernel.loadedmodule
        matchExpressions:
          driver-module: {op: Exists}
      - pci.device:
          vendor: "8086"
          device: "1234"
      - pci.device:
          vendor: "8086"
          device: "abcd"
This commit is contained in:
Markus Lehtonen 2021-10-14 10:22:07 +03:00
parent cfc1c82746
commit e206f0b86b
6 changed files with 471 additions and 67 deletions

View file

@ -107,3 +107,56 @@
# value: customValue
# matchOn:
# - nodename: ["worker-0", "my-.*-node"]
#
# # The following feature demonstrates the capabilities of the matchFeatures
# - name: "my.ng.feature"
# labels:
# my-ng-feature: "true"
# # matchFeatures implements a logical AND over all matcher terms in the
# # list (i.e. all of the terms, or per-feature matchers, must match)
# matchFeatures:
# - feature: cpu.cpuid
# matchExpressions:
# AVX512F: {op: Exists}
# - feature: cpu.cstate
# matchExpressions:
# enabled: {op: IsTrue}
# - feature: cpu.pstate
# matchExpressions:
# no_turbo: {op: IsFalse}
# scaling_governor: {op: In, value: ["performance"]}
# - feature: cpu.rdt
# matchExpressions:
# RDTL3CA: {op: Exists}
# - feature: cpu.sst
# matchExpressions:
# bf.enabled: {op: IsTrue}
# - feature: cpu.topology
# matchExpressions:
# hardware_multithreading: {op: IsFalse}
#
# - feature: kernel.config
# matchExpressions:
# X86: {op: Exists}
# LSM: {op: InRegexp, value: ["apparmor"]}
# - feature: kernel.loadedmodule
# matchExpressions:
# e1000e: {op: Exists}
# - feature: kernel.selinux
# matchExpressions:
# enabled: {op: IsFalse}
# - feature: kernel.version
# matchExpressions:
# major: {op: In, value: ["5"]}
# minor: {op: Gt, value: ["10"]}
#
# - feature: system.osrelease
# matchExpressions:
# ID: {op: In, value: ["fedora", "centos"]}
# - feature: system.name
# matchExpressions:
# nodename: {op: InRegexp, value: ["^worker-X"]}
#
# - feature: local.label
# matchExpressions:
# custom-feature-knob: {op: Gt, value: ["100"]}

View file

@ -193,6 +193,59 @@ worker:
# value: customValue
# matchOn:
# - nodename: ["worker-0", "my-.*-node"]
#
# # The following feature demonstrates the capabilities of the matchFeatures
# - name: "my.ng.feature"
# labels:
# my-ng-feature: "true"
# # matchFeatures implements a logical AND over all matcher terms in the
# # list (i.e. all of the terms, or per-feature matchers, must match)
# matchFeatures:
# - feature: cpu.cpuid
# matchExpressions:
# AVX512F: {op: Exists}
# - feature: cpu.cstate
# matchExpressions:
# enabled: {op: IsTrue}
# - feature: cpu.pstate
# matchExpressions:
# no_turbo: {op: IsFalse}
# scaling_governor: {op: In, value: ["performance"]}
# - feature: cpu.rdt
# matchExpressions:
# RDTL3CA: {op: Exists}
# - feature: cpu.sst
# matchExpressions:
# bf.enabled: {op: IsTrue}
# - feature: cpu.topology
# matchExpressions:
# hardware_multithreading: {op: IsFalse}
#
# - feature: kernel.config
# matchExpressions:
# X86: {op: Exists}
# LSM: {op: InRegexp, value: ["apparmor"]}
# - feature: kernel.loadedmodule
# matchExpressions:
# e1000e: {op: Exists}
# - feature: kernel.selinux
# matchExpressions:
# enabled: {op: IsFalse}
# - feature: kernel.version
# matchExpressions:
# major: {op: In, value: ["5"]}
# minor: {op: Gt, value: ["10"]}
#
# - feature: system.osrelease
# matchExpressions:
# ID: {op: In, value: ["fedora", "centos"]}
# - feature: system.name
# matchExpressions:
# nodename: {op: InRegexp, value: ["^worker-X"]}
#
# - feature: local.label
# matchExpressions:
# custom-feature-knob: {op: Gt, value: ["100"]}
### <NFD-WORKER-CONF-END-DO-NOT-REMOVE>
podSecurityContext: {}

View file

@ -17,19 +17,25 @@ limitations under the License.
package custom
import (
"encoding/json"
"fmt"
"reflect"
"strings"
"k8s.io/klog/v2"
"sigs.k8s.io/yaml"
"sigs.k8s.io/node-feature-discovery/pkg/api/feature"
"sigs.k8s.io/node-feature-discovery/pkg/utils"
"sigs.k8s.io/node-feature-discovery/source"
"sigs.k8s.io/node-feature-discovery/source/custom/expression"
"sigs.k8s.io/node-feature-discovery/source/custom/rules"
)
const Name = "custom"
// Custom Features Configurations
type MatchRule struct {
// LegacyMatcher contains the legacy custom rules.
type LegacyMatcher struct {
PciID *rules.PciIDRule `json:"pciId,omitempty"`
UsbID *rules.UsbIDRule `json:"usbId,omitempty"`
LoadedKMod *rules.LoadedKModRule `json:"loadedKMod,omitempty"`
@ -38,13 +44,31 @@ type MatchRule struct {
Nodename *rules.NodenameRule `json:"nodename,omitempty"`
}
type FeatureSpec struct {
type LegacyRule struct {
Name string `json:"name"`
Value *string `json:"value,omitempty"`
MatchOn []MatchRule `json:"matchOn"`
MatchOn []LegacyMatcher `json:"matchOn"`
}
type config []FeatureSpec
type Rule struct {
Name string `json:"name"`
Labels map[string]string `json:"labels"`
MatchFeatures FeatureMatcher `json:"matchFeatures"`
}
type FeatureMatcher []FeatureMatcherTerm
type FeatureMatcherTerm struct {
Feature string
MatchExpressions expression.MatchExpressionSet
}
type config []CustomRule
type CustomRule struct {
*LegacyRule
*Rule
}
// newDefaultConfig returns a new config with pre-populated defaults
func newDefaultConfig() *config {
@ -91,40 +115,137 @@ func (s *customSource) Priority() int { return 10 }
// GetLabels method of the LabelSource interface
func (s *customSource) GetLabels() (source.FeatureLabels, error) {
features := source.FeatureLabels{}
// Get raw features from all sources
domainFeatures := make(map[string]*feature.DomainFeatures)
for n, s := range source.GetAllFeatureSources() {
domainFeatures[n] = s.GetFeatures()
}
labels := source.FeatureLabels{}
allFeatureConfig := append(getStaticFeatureConfig(), *s.config...)
allFeatureConfig = append(allFeatureConfig, getDirectoryFeatureConfig()...)
utils.KlogDump(2, "custom features configuration:", " ", allFeatureConfig)
// Iterate over features
for _, customFeature := range allFeatureConfig {
featureExist, err := s.discoverFeature(customFeature)
for _, rule := range allFeatureConfig {
ruleOut, err := rule.execute(domainFeatures)
if err != nil {
klog.Errorf("failed to discover feature: %q: %s", customFeature.Name, err.Error())
klog.Error(err)
continue
}
if featureExist {
var value interface{} = true
if customFeature.Value != nil {
value = *customFeature.Value
}
features[customFeature.Name] = value
for n, v := range ruleOut {
labels[n] = v
}
}
return features, nil
return labels, nil
}
// Process a single feature by Matching on the defined rules.
// A feature is present if all defined Rules in a MatchRule return a match.
func (s *customSource) discoverFeature(feature FeatureSpec) (bool, error) {
for _, matchRules := range feature.MatchOn {
func (r *CustomRule) execute(features map[string]*feature.DomainFeatures) (map[string]string, error) {
if r.LegacyRule != nil {
ruleOut, err := r.LegacyRule.execute(features)
if err != nil {
return nil, fmt.Errorf("failed to execute legacy rule %s: %w", r.LegacyRule.Name, err)
}
return ruleOut, err
}
if r.Rule != nil {
ruleOut, err := r.Rule.execute(features)
if err != nil {
return nil, fmt.Errorf("failed to execute rule %s: %w", r.Rule.Name, err)
}
return ruleOut, err
}
return nil, fmt.Errorf("BUG: an empty rule, this really should not happen")
}
func (r *LegacyRule) execute(features map[string]*feature.DomainFeatures) (map[string]string, error) {
if len(r.MatchOn) > 0 {
// Logical OR over the legacy rules
matched := false
for _, matcher := range r.MatchOn {
if m, err := matcher.match(); err != nil {
return nil, err
} else if m {
matched = true
break
}
}
if !matched {
return nil, nil
}
}
value := "true"
if r.Value != nil {
value = *r.Value
}
return map[string]string{r.Name: value}, nil
}
func (r *Rule) execute(features map[string]*feature.DomainFeatures) (map[string]string, error) {
if len(r.MatchFeatures) > 0 {
if m, err := r.MatchFeatures.match(features); err != nil {
return nil, err
} else if !m {
return nil, nil
}
}
labels := make(map[string]string, len(r.Labels))
for k, v := range r.Labels {
labels[k] = v
}
return labels, nil
}
func (m *FeatureMatcher) match(features map[string]*feature.DomainFeatures) (bool, error) {
// Logical AND over the terms
for _, term := range *m {
split := strings.SplitN(term.Feature, ".", 2)
if len(split) != 2 {
return false, fmt.Errorf("invalid selector %q: must be <domain>.<feature>", term.Feature)
}
domain := split[0]
// Ignore case
featureName := strings.ToLower(split[1])
domainFeatures, ok := features[domain]
if !ok {
return false, fmt.Errorf("unknown feature source/domain %q", domain)
}
var m bool
var err error
if f, ok := domainFeatures.Keys[featureName]; ok {
m, err = term.MatchExpressions.MatchKeys(f.Elements)
} else if f, ok := domainFeatures.Values[featureName]; ok {
m, err = term.MatchExpressions.MatchValues(f.Elements)
} else if f, ok := domainFeatures.Instances[featureName]; ok {
m, err = term.MatchExpressions.MatchInstances(f.Elements)
} else {
return false, fmt.Errorf("%q feature of source/domain %q not available", featureName, domain)
}
if err != nil {
return false, err
} else if !m {
return false, nil
}
}
return true, nil
}
func (m *LegacyMatcher) match() (bool, error) {
allRules := []legacyRule{
matchRules.PciID,
matchRules.UsbID,
matchRules.LoadedKMod,
matchRules.CpuID,
matchRules.Kconfig,
matchRules.Nodename,
m.PciID,
m.UsbID,
m.LoadedKMod,
m.CpuID,
m.Kconfig,
m.Nodename,
}
// return true, nil if all rules match
@ -142,13 +263,33 @@ func (s *customSource) discoverFeature(feature FeatureSpec) (bool, error) {
return true, nil
}
if match, err := matchRules(allRules); err != nil {
return false, err
} else if match {
return true, nil
return matchRules(allRules)
}
// UnmarshalJSON implements the Unmarshaler interface from "encoding/json"
func (c *CustomRule) UnmarshalJSON(data []byte) error {
// Do a raw parse to determine if this is a legacy rule
raw := map[string]json.RawMessage{}
err := yaml.Unmarshal(data, &raw)
if err != nil {
return err
}
for k := range raw {
if strings.ToLower(k) == "matchon" {
return yaml.Unmarshal(data, &c.LegacyRule)
}
}
return false, nil
return yaml.Unmarshal(data, &c.Rule)
}
// MarshalJSON implements the Marshaler interface from "encoding/json"
func (c *CustomRule) MarshalJSON() ([]byte, error) {
if c.LegacyRule != nil {
return json.Marshal(c.LegacyRule)
}
return json.Marshal(c.Rule)
}
func init() {

View file

@ -0,0 +1,153 @@
/*
Copyright 2021 The Kubernetes Authors.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package custom
import (
"testing"
"github.com/stretchr/testify/assert"
"sigs.k8s.io/node-feature-discovery/pkg/api/feature"
"sigs.k8s.io/node-feature-discovery/source/custom/expression"
)
func TestRule(t *testing.T) {
f := map[string]*feature.DomainFeatures{}
r1 := Rule{Labels: map[string]string{"label-1": "", "label-2": "true"}}
r2 := Rule{
Labels: map[string]string{"label-1": "label-val-1"},
MatchFeatures: FeatureMatcher{
FeatureMatcherTerm{
Feature: "domain-1.kf-1",
MatchExpressions: expression.MatchExpressionSet{"key-1": expression.MustCreateMatchExpression(expression.MatchExists)},
},
},
}
// Test totally empty features
m, err := r1.execute(f)
assert.Nilf(t, err, "unexpected error: %v", err)
assert.Equal(t, r1.Labels, m, "empty matcher should have matched empty features")
_, err = r2.execute(f)
assert.Error(t, err, "matching agains a missing domain should have returned an error")
// Test empty domain
d := feature.NewDomainFeatures()
f["domain-1"] = d
m, err = r1.execute(f)
assert.Nilf(t, err, "unexpected error: %v", err)
assert.Equal(t, r1.Labels, m, "empty matcher should have matched empty features")
_, err = r2.execute(f)
assert.Error(t, err, "matching agains a missing feature type should have returned an error")
// Test empty feature sets
d.Keys["kf-1"] = feature.NewKeyFeatures()
d.Values["vf-1"] = feature.NewValueFeatures(nil)
d.Instances["if-1"] = feature.NewInstanceFeatures(nil)
m, err = r1.execute(f)
assert.Nilf(t, err, "unexpected error: %v", err)
assert.Equal(t, r1.Labels, m, "empty matcher should have matched empty features")
m, err = r2.execute(f)
assert.Nilf(t, err, "unexpected error: %v", err)
assert.Nil(t, m, "unexpected match")
// Test non-empty feature sets
d.Keys["kf-1"].Elements["key-x"] = feature.Nil{}
d.Values["vf-1"].Elements["key-1"] = "val-x"
d.Instances["if-1"] = feature.NewInstanceFeatures([]feature.InstanceFeature{
*feature.NewInstanceFeature(map[string]string{"attr-1": "val-x"})})
m, err = r1.execute(f)
assert.Nilf(t, err, "unexpected error: %v", err)
assert.Equal(t, r1.Labels, m, "empty matcher should have matched empty features")
// Match "key" features
m, err = r2.execute(f)
assert.Nilf(t, err, "unexpected error: %v", err)
assert.Nil(t, m, "keys should not have matched")
d.Keys["kf-1"].Elements["key-1"] = feature.Nil{}
m, err = r2.execute(f)
assert.Nilf(t, err, "unexpected error: %v", err)
assert.Equal(t, r2.Labels, m, "keys should have matched")
// Match "value" features
r3 := Rule{
Labels: map[string]string{"label-3": "label-val-3", "empty": ""},
MatchFeatures: FeatureMatcher{
FeatureMatcherTerm{
Feature: "domain-1.vf-1",
MatchExpressions: expression.MatchExpressionSet{"key-1": expression.MustCreateMatchExpression(expression.MatchIn, "val-1")},
},
},
}
m, err = r3.execute(f)
assert.Nilf(t, err, "unexpected error: %v", err)
assert.Nil(t, m, "values should not have matched")
d.Values["vf-1"].Elements["key-1"] = "val-1"
m, err = r3.execute(f)
assert.Nilf(t, err, "unexpected error: %v", err)
assert.Equal(t, r3.Labels, m, "values should have matched")
// Match "instance" features
r4 := Rule{
Labels: map[string]string{"label-4": "label-val-4"},
MatchFeatures: FeatureMatcher{
FeatureMatcherTerm{
Feature: "domain-1.if-1",
MatchExpressions: expression.MatchExpressionSet{"attr-1": expression.MustCreateMatchExpression(expression.MatchIn, "val-1")},
},
},
}
m, err = r4.execute(f)
assert.Nilf(t, err, "unexpected error: %v", err)
assert.Nil(t, m, "instances should not have matched")
d.Instances["if-1"].Elements[0].Attributes["attr-1"] = "val-1"
m, err = r4.execute(f)
assert.Nilf(t, err, "unexpected error: %v", err)
assert.Equal(t, r4.Labels, m, "instances should have matched")
// Test multiple feature matchers
r5 := Rule{
Labels: map[string]string{"label-5": "label-val-5"},
MatchFeatures: FeatureMatcher{
FeatureMatcherTerm{
Feature: "domain-1.vf-1",
MatchExpressions: expression.MatchExpressionSet{"key-1": expression.MustCreateMatchExpression(expression.MatchIn, "val-x")},
},
FeatureMatcherTerm{
Feature: "domain-1.if-1",
MatchExpressions: expression.MatchExpressionSet{"attr-1": expression.MustCreateMatchExpression(expression.MatchIn, "val-1")},
},
},
}
m, err = r5.execute(f)
assert.Nilf(t, err, "unexpected error: %v", err)
assert.Nil(t, m, "instances should not have matched")
r5.MatchFeatures[0].MatchExpressions["key-1"] = expression.MustCreateMatchExpression(expression.MatchIn, "val-1")
m, err = r5.execute(f)
assert.Nilf(t, err, "unexpected error: %v", err)
assert.Equal(t, r5.Labels, m, "instances should have matched")
}

View file

@ -31,14 +31,14 @@ const Directory = "/etc/kubernetes/node-feature-discovery/custom.d"
// getDirectoryFeatureConfig returns features configured in the "/etc/kubernetes/node-feature-discovery/custom.d"
// host directory and its 1st level subdirectories, which can be populated e.g. by ConfigMaps
func getDirectoryFeatureConfig() []FeatureSpec {
func getDirectoryFeatureConfig() []CustomRule {
features := readDir(Directory, true)
klog.V(1).Infof("all configmap based custom feature specs: %+v", features)
return features
}
func readDir(dirName string, recursive bool) []FeatureSpec {
features := make([]FeatureSpec, 0)
func readDir(dirName string, recursive bool) []CustomRule {
features := make([]CustomRule, 0)
klog.V(1).Infof("getting files in %s", dirName)
files, err := ioutil.ReadDir(dirName)
@ -76,7 +76,7 @@ func readDir(dirName string, recursive bool) []FeatureSpec {
}
klog.V(2).Infof("custom config rules raw: %s", string(bytes))
config := &[]FeatureSpec{}
config := &[]CustomRule{}
err = yaml.UnmarshalStrict(bytes, config)
if err != nil {
klog.Errorf("could not parse custom config file %q, %v", fileName, err)

View file

@ -23,11 +23,12 @@ import (
// getStaticFeatures returns statically configured custom features to discover
// e.g RMDA related features. NFD configuration file may extend these custom features by adding rules.
func getStaticFeatureConfig() []FeatureSpec {
return []FeatureSpec{
func getStaticFeatureConfig() []CustomRule {
return []CustomRule{
{
LegacyRule: &LegacyRule{
Name: "rdma.capable",
MatchOn: []MatchRule{
MatchOn: []LegacyMatcher{
{
PciID: &rules.PciIDRule{
MatchExpressionSet: expression.MatchExpressionSet{
@ -37,9 +38,11 @@ func getStaticFeatureConfig() []FeatureSpec {
},
},
},
},
{
LegacyRule: &LegacyRule{
Name: "rdma.available",
MatchOn: []MatchRule{
MatchOn: []LegacyMatcher{
{
LoadedKMod: &rules.LoadedKModRule{
MatchExpressionSet: expression.MatchExpressionSet{
@ -50,5 +53,6 @@ func getStaticFeatureConfig() []FeatureSpec {
},
},
},
},
}
}