Node Feature Discovery (NFD)

NFD-Topology-Updater is a component designed to run as a Kubernetes DaemonSet. Its primary purpose is to capture changes in allocated resources (such as CPU cores, memory, and devices) and update NodeResourceTopology custom resources accordingly. This allows for tracking allocatable resources on a per-zone basis (where a zone can be a NUMA node).

Key Behaviors

• Resource Accounting: It only accounts for resources exclusively allocated to Guaranteed Quality of Service pods.
• Re-examination Triggers:
  • Interval-based: Nodes are re-examined at a regular interval defined by the -sleep-interval flag (default is 60s). Setting this to 0 disables re-examination.
  • Event-based: The updater can monitor the Kubelet checkpoint file (via the -kubelet-state-dir flag) to trigger updates whenever pod lifecycle events occur.
• Resource Filtering: You can prevent the examination of specific resources using the -excludeList option.

Image compatibility metadata (experimental v1alpha1) allows container image authors to define environment requirements using a specification similar to Node Feature Groups. This enables matching container requirements directly against features discovered on nodes by NFD.

Schema

• version (string, REQUIRED): The API version (e.g., v1alpha1).
• compatibilities (array of objects, REQUIRED): A list of compatibility sets.
  • rules (object, REQUIRED): A reference to the NodeFeatureGroup API spec. This allows describing requirements using features discovered from NFD sources.
  • weight (int, OPTIONAL): Specifies the node affinity weight.
  • tag (string, OPTIONAL): Used for grouping or separating compatibility sets.
  • description (string, OPTIONAL): A brief description of the compatibility set.

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"]}

NFD discovers features across several domains and converts them into node labels. Most feature labels follow the prefix feature.node.kubernetes.io/<domain>-<feature-name>.

Supported feature domains include:

• CPU
• Kernel
• Memory
• Network
• PCI
• Storage
• System
• USB
• Custom (rule-based)
• Local (based on files)

Common label patterns include:

• Boolean features: feature.node.kubernetes.io/<domain>-<feature-name>: "true"
• Value-based features: feature.node.kubernetes.io/<domain>-<feature-name>: "<feature value>"

{
  "feature.node.kubernetes.io/cpu-<feature-name>": "true",
  "feature.node.kubernetes.io/custom-<feature-name>": "true",
  "feature.node.kubernetes.io/kernel-<feature name>": "<feature value>",
  "feature.node.kubernetes.io/memory-<feature-name>": "true",
  "feature.node.kubernetes.io/network-<feature-name>": "true",
  "feature.node.kubernetes.io/pci-<device label>.present": "true",
  "feature.node.kubernetes.io/storage-<feature-name>": "true",
  "feature.node.kubernetes.io/system-<feature name>": "<feature value>",
  "feature.node.kubernetes.io/usb-<device label>.present": "<feature value>",
  "feature.node.kubernetes.io/<file name>-<feature name>": "<feature value>"
}

NFD supports an experimental Spiffe integration (KEP-1186) designed to improve security by signing NodeFeature Custom Resource (CR) specifications. This prevents malicious workloads from injecting false node features by ensuring that only features signed by a valid nfd-worker (using a private key from a Spiffe Verifiable Identity Document, or SVID) are propagated to nodes.

How it works

1. Identity: A single SVID is shared among all nfd-worker workloads.
2. Signing: After feature discovery, nfd-workers fetch their private key from Spiffe and sign the NodeFeature CR spec. The signature is stored in the CR annotations under annotations.signature as a base64-encoded string.
3. Verification: The nfd-master detects changes to the NodeFeature CR and verifies the signature using the corresponding public key. If the signature is invalid or missing (e.g., due to manual tampering), the changes are not propagated to the nodes.

Configuration

This feature is EXPERIMENTAL. Enabling or disabling Spiffe verification must be configured via command-line flags or a configuration file.

Integration for 3rd Party Tools

If you integrate third-party tools that interact with NFD data, you must create their respective SVIDs in the spire-server to allow their exposed data to be validated within this security model.