Configuration file reference of nfd-worker

Table of contents

  1. core
    1. core.sleepInterval
    2. core.featureSources
    3. core.labelSources
    4. core.sources
    5. core.noPublishFeatures
    6. core.labelWhiteList
    7. core.noPublish
    8. core.ownerRefs
    9. core.noOwnerRefs
    10. core.klog
  2. sources
    1. sources.cpu
    2. sources.kernel
    3. sources.local
    4. sources.pci
    5. sources.usb
    6. sources.custom
    7. sources.fake

See the sample configuration file for a full example configuration.

core

The core section contains common configuration settings that are not specific to any particular feature source.

core.sleepInterval

core.sleepInterval specifies the interval between consecutive passes of feature (re-)detection, and thus also the interval between node re-labeling. A non-positive value implies infinite sleep interval, i.e. no re-detection or re-labeling is done.

Default: 60s

Example:

core:
  sleepInterval: 60s

core.featureSources

core.featureSources specifies the list of enabled feature sources. A special value all enables all sources except fake, which must be named explicitly. Prefixing a source name with - indicates that the source will be disabled instead - this is only meaningful when used in conjunction with all. This option allows completely disabling the feature detection so that neither standard feature labels are generated nor the raw feature data is available for custom rule processing.

Default: [all]

Example:

core:
  # Enable all but cpu and local sources
  featureSources:
    - "all"
    - "-cpu"
    - "-local"

core:
  # Enable only cpu and local sources
  featureSources:
    - "cpu"
    - "local"

core.labelSources

core.labelSources specifies the list of enabled label sources. A special value all enables all sources except fake, which must be named explicitly. Prefixing a source name with - indicates that the source will be disabled instead - this is only meaningful when used in conjunction with all. This configuration option affects the generation of node labels but not the actual discovery of the underlying feature data that is used e.g. in custom/NodeFeatureRule rules.

NOTE: Overridden by the -label-sources command line flag and the core.sources configurations option (if either of them is specified).

Default: [all]

Example:

core:
  # Enable all but cpu and system sources
  labelSources:
    - "all"
    - "-cpu"
    - "-system"

core:
  # Enable only cpu and system sources
  labelSources:
    - "cpu"
    - "system"

core.sources

DEPRECATED: use core.labelSources instead.

NOTE: core.sources takes precedence over the core.labelSources configuration file option.

core.noPublishFeatures

core.noPublishFeatures specifies a list of feature keys that are discovered but omitted from the published NodeFeature object. Discovery itself is not affected, so the features remain available locally for label sources and inline custom/NodeFeatureRule rules in sources.custom; they are only stripped from the published object to reduce its size (and thus the load on the Kubernetes API server, etcd and the nfd-master informer cache).

Each entry is matched against the <source>.<feature> key either exactly, or as a prefix when it ends with *.

NOTE: Overridden by the -no-publish-features command line flag (if specified). Only use this for features that no cluster-side NodeFeatureRule or NodeFeatureGroup consumes - those are evaluated by nfd-master against the published Spec.Features, so removing a feature they rely on changes the resulting labels, taints and extended resources.

Default: empty

Example:

core:
  # Discover PCI and USB devices (so local rules can still use them) but do not
  # publish the potentially large per-device lists in the NodeFeature object.
  noPublishFeatures:
    - "pci.device"
    - "usb.*"

core.labelWhiteList

core.labelWhiteList specifies a regular expression for filtering feature labels based on the label name. Non-matching labels are not published.

NOTE: The regular expression is only matches against the "basename" part of the label, i.e. to the part of the name after ‘/'. The label prefix (or namespace) is omitted.

Default: null

Example:

core:
  labelWhiteList: '^cpu-cpuid'

core.noPublish

Setting core.noPublish to true disables publishing of the discovered features. It is effectively a "dry-run" option: NFD-Worker runs feature detection normally, but no NodeFeature objects are created or updated in the API server. nfd-worker still needs a Kubernetes client configuration (in-cluster or -kubeconfig) to start, and it still contacts the API server to resolve the owner references: with the default [pod, ds] it reads its own Pod when POD_NAME is set, as in the DaemonSet (requires get on pods), and with node it reads its Node.

NOTE: Overridden by the -no-publish command line flag (if specified).

Default: false

Example:

core:
  noPublish: true

core.ownerRefs

The core.ownerRefs option selects the objects referenced as owners of the NodeFeature object. Valid values are node, pod and ds. An explicitly empty list disables owner references.

  • node ties the NodeFeature to the UID of the current Node and is recommended for environments that rebuild Nodes under the same name.
  • pod ties it to the UID of the nfd-worker Pod.
  • ds ties it to the DaemonSet that owns the nfd-worker Pod.

When multiple owners are configured, Kubernetes keeps the NodeFeature while at least one owner still exists. Thus, adding ds makes the DaemonSet the longest-lived owner during a Node rebuild.

Selecting node requires the worker service account to have get permission for Nodes. The Helm chart creates this permission when worker.ownerRefs contains node. Kustomize installations must include the worker-node-rbac component. Installations with custom RBAC must add the permission. The NFD garbage collector may still explicitly delete stale NodeFeature objects independently of native owner-reference garbage collection.

Changes to this option take effect only after nfd-worker restarts; nfd-worker does not reload its configuration at runtime. On its first publication after a restart, each worker replaces the complete owner reference list on its existing NodeFeature. Thus, a DaemonSet rollout migrates live Nodes in place without deleting the NodeFeature, even when its discovered feature spec is unchanged. Changing worker.ownerRefs in a Helm release updates the worker Pod arguments and triggers this rollout. Nodes without a running worker converge when their worker next starts.

NOTE: Overridden by the -owner-refs command line flag (if specified).

Default: [pod, ds]

Example:

core:
  ownerRefs: [node]

core.noOwnerRefs

Setting core.noOwnerRefs to true disables setting the owner references of the NodeFeature object created by the nfd-worker. This option is deprecated; use core.ownerRefs: [] instead. When true, it takes precedence over core.ownerRefs.

NOTE: Overridden by the -no-owner-refs command line flag (if specified).

Default: false

Example:

core:
  noOwnerRefs: true

core.klog

The following options specify the logger configuration.

NOTE: The logger options can also be specified via command line flags which take precedence over any corresponding config file options.

core.klog.addDirHeader

If true, adds the file directory to the header of the log messages.

Default: false

core.klog.alsologtostderr

Log to standard error as well as files.

Default: false

core.klog.alsologtostderrthreshold

Logs at or above this threshold go to stderr when alsologtostderr is true (no effect when logtostderr is true).

Default: 0

core.klog.legacyStderrThresholdBehavior

If true, stderrthreshold is ignored when logtostderr is true (legacy behavior). If false, stderrthreshold is honored even when logtostderr is true.

Default: true

core.klog.logBacktraceAt

When logging hits line file:N, emit a stack trace.

Default: empty

core.klog.logDir

If non-empty, write log files in this directory.

Default: empty

core.klog.logFile

If non-empty, use this log file.

Default: empty

core.klog.logFileMaxSize

Defines the maximum size a log file can grow to. Unit is megabytes. If the value is 0, the maximum file size is unlimited.

Default: 1800

core.klog.logtostderr

Log to standard error instead of files

Default: true

core.klog.oneOutput

If true, only write logs to their native severity level (vs also writing to each lower severity level; no effect when logtostderr is true).

Default: false

core.klog.skipHeaders

If true, avoid header prefixes in the log messages.

Default: false

core.klog.skipLogHeaders

If true, avoid headers when opening log files.

Default: false

core.klog.stderrthreshold

Logs at or above this threshold go to stderr (default 2)

core.klog.v

Number for the log level verbosity.

Default: 0

core.klog.vmodule

Comma-separated list of pattern=N settings for file-filtered logging.

Default: empty

sources

The sources section contains feature source specific configuration parameters.

sources.cpu

sources.cpu.cpuid

sources.cpu.cpuid.attributeBlacklist

Prevent publishing cpuid features listed in this option.

NOTE: overridden by sources.cpu.cpuid.attributeWhitelist (if specified)

Default: [AVX10, BMI1, BMI2, CLMUL, CMOV, CX16, ERMS, F16C, HTT, LZCNT, MMX, MMXEXT, NX, POPCNT, RDRAND, RDSEED, RDTSCP, SGX, SGXLC, SSE, SSE2, SSE3, SSE4, SSE42, SSSE3, TDX_GUEST]

Example:

sources:
  cpu:
    cpuid:
      attributeBlacklist: [MMX, MMXEXT]
sources.cpu.cpuid.attributeWhitelist

Only publish the cpuid features listed in this option.

NOTE: takes precedence over sources.cpu.cpuid.attributeBlacklist

Default: empty

Example:

sources:
  cpu:
    cpuid:
      attributeWhitelist: [AVX512BW, AVX512CD, AVX512DQ, AVX512F, AVX512VL]

sources.kernel

sources.kernel.kconfigFile

Path of the kernel config file. If empty, NFD runs a search in the well-known standard locations.

Default: empty

Example:

sources:
  kernel:
    kconfigFile: "/path/to/kconfig"

sources.kernel.configOpts

Kernel configuration options to publish as feature labels.

Default: [NO_HZ, NO_HZ_IDLE, NO_HZ_FULL, PREEMPT]

Example:

sources:
  kernel:
    configOpts: [NO_HZ, X86, DMI]

sources.local

The local feature source has no configuration options. It reads feature files from /etc/kubernetes/node-feature-discovery/features.d/. See the local feature source documentation for the file format and usage.

sources.pci

sources.pci.deviceClassWhitelist

List of PCI device class IDs for which to publish a label. Can be specified as a main class only (e.g. 03) or full class-subclass combination (e.g. 0300) - the former implies that all subclasses are accepted. The format of the labels can be further configured with deviceLabelFields.

Default: ["03", "0b40", "12"]

Example:

sources:
  pci:
    deviceClassWhitelist: ["0200", "03"]

sources.pci.deviceLabelFields

The set of PCI ID fields to use when constructing the name of the feature label. Valid fields are class, vendor, device, subsystem_vendor and subsystem_device.

Default: [class, vendor]

Example:

sources:
  pci:
    deviceLabelFields: [class, vendor, device]

With the example config above NFD would publish labels like: feature.node.kubernetes.io/pci-<class-id>_<vendor-id>_<device-id>.present=true

sources.usb

sources.usb.deviceClassWhitelist

List of USB device class IDs for which to publish a feature label. The format of the labels can be further configured with deviceLabelFields.

Default: ["0e", "ef", "fe", "ff"]

Example:

sources:
  usb:
    deviceClassWhitelist: ["ef", "ff"]

sources.usb.deviceLabelFields

The set of USB ID fields from which to compose the name of the feature label. Valid fields are class, vendor, device and serial.

Default: [class, vendor, device]

Example:

sources:
  usb:
    deviceLabelFields: [class, vendor]

With the example config above NFD would publish labels like: feature.node.kubernetes.io/usb-<class-id>_<vendor-id>.present=true

sources.custom

List of rules to process in the custom feature source to create user-specific labels. Refer to the documentation of the custom feature source for details of the available rules and their configuration.

Default: empty

Example:

sources:
  custom:
    - name: "my custom rule"
      labels:
        my-custom-feature: "true"
      matchFeatures:
        - feature: kernel.loadedmodule
          matchExpressions:
            e1000e: {op: Exists}
        - feature: pci.device
          matchExpressions:
            class: {op: In, value: ["0200"]}
            vendor: {op: In, value: ["8086"]}

sources.fake

The fake feature source generates static features and labels for testing. It is disabled by default: it is not included in all and must be named explicitly in core.featureSources and core.labelSources (e.g. [all, fake]). It publishes the features fake.flag, fake.attribute and fake.instance, and labels with the feature.node.kubernetes.io/fake- prefix.

Options: labels (map of label name to value; default fakefeature1, fakefeature2, fakefeature3 = "true"), flagFeatures (list; default [flag_1, flag_2, flag_3]), attributeFeatures (map; default attr_1: "true", attr_2: "false", attr_3: "10"), instanceFeatures (list of attribute maps; default instance_1..instance_3). Map options are merged with the defaults rather than replacing them.

Example:

core:
  featureSources: [all, fake]
  labelSources: [all, fake]
sources:
  fake:
    labels:
      my-fake-label: "foo"