From cdc7558f6f7c5d9148c70de8e7c93b737163181b Mon Sep 17 00:00:00 2001 From: Markus Lehtonen Date: Thu, 1 Dec 2022 11:08:20 +0200 Subject: [PATCH] docs: better document custom resources Add a separate page for describing the custom resources used by NFD. Simplify the Introduction page by moving the details of NodeResourceTopology from there. Similarly, drop long NodeResourceTopology example from the quick-start page, making the page shorter and simpler. --- docs/get-started/introduction.md | 56 +++------------ docs/get-started/quick-start.md | 59 ---------------- docs/usage/custom-resources.md | 109 ++++++++++++++++++++++++++++++ docs/usage/customization-guide.md | 2 +- docs/usage/examples-and-demos.md | 2 +- 5 files changed, 121 insertions(+), 107 deletions(-) create mode 100644 docs/usage/custom-resources.md diff --git a/docs/get-started/introduction.md b/docs/get-started/introduction.md index 59ba8cd9de..f17f13bc5b 100644 --- a/docs/get-started/introduction.md +++ b/docs/get-started/introduction.md @@ -102,49 +102,13 @@ command line flag affects the annotation names Unapplicable annotations are not created, i.e. for example master.version is only created on nodes running nfd-master. -## NodeResourceTopology CR - -When run with NFD-Topology-Updater, NFD creates CR instances corresponding to -node resource hardware topology such as: - - ```yaml -apiVersion: topology.node.k8s.io/v1alpha1 -kind: NodeResourceTopology -metadata: - name: node1 -topologyPolicies: ["SingleNUMANodeContainerLevel"] -zones: - - name: node-0 - type: Node - resources: - - name: cpu - capacity: 20 - allocatable: 16 - available: 10 - - name: vendor/nic1 - capacity: 3 - allocatable: 3 - available: 3 - - name: node-1 - type: Node - resources: - - name: cpu - capacity: 30 - allocatable: 30 - available: 15 - - name: vendor/nic2 - capacity: 6 - allocatable: 6 - available: 6 - - name: node-2 - type: Node - resources: - - name: cpu - capacity: 30 - allocatable: 30 - available: 15 - - name: vendor/nic1 - capacity: 3 - allocatable: 3 - available: 3 - ``` +## Custom resources + +NFD takes use of some Kubernetes Custom Resources. + +NFD-Master uses [NodeFeatureRule](../usage/custom-resources/nodefeaturerule)s +for custom labeling of nodes. + +NFD-Topology-Updater creates +[NodeResourceTopology](../usage/custom-resources/noderesourcetopology) objects +that describe the hardware topology of node resources. diff --git a/docs/get-started/quick-start.md b/docs/get-started/quick-start.md index 57ba0103eb..c0400121b7 100644 --- a/docs/get-started/quick-start.md +++ b/docs/get-started/quick-start.md @@ -120,65 +120,6 @@ kind-control-plane 23s kind-worker 23s ``` -## Show the CR instances - -```bash -$ kubectl describe noderesourcetopologies.topology.node.k8s.io kind-control-plane -Name: kind-control-plane -Namespace: default -Labels: -Annotations: -API Version: topology.node.k8s.io/v1alpha1 -Kind: NodeResourceTopology -... -Topology Policies: - SingleNUMANodeContainerLevel -Zones: - Name: node-0 - Costs: - node-0: 10 - node-1: 20 - Resources: - Name: Cpu - Allocatable: 3 - Capacity: 3 - Available: 3 - Name: vendor/nic1 - Allocatable: 2 - Capacity: 2 - Available: 2 - Name: vendor/nic2 - Allocatable: 2 - Capacity: 2 - Available: 2 - Type: Node - Name: node-1 - Costs: - node-0: 20 - node-1: 10 - Resources: - Name: Cpu - Allocatable: 4 - Capacity: 4 - Available: 4 - Name: vendor/nic1 - Allocatable: 2 - Capacity: 2 - Available: 2 - Name: vendor/nic2 - Allocatable: 2 - Capacity: 2 - Available: 2 - Type: Node -Events: -``` - -The CR instances created can be used to gain insight into the allocatable -resources along with the granularity of those resources at a per-zone level -(represented by node-0 and node-1 in the above example) or can be used by an -external entity (e.g. topology-aware scheduler plugin) to take an action based -on the gathered information. - [podresource-api]: https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/#monitoring-device-plugin-resources [feature-gate]: https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates diff --git a/docs/usage/custom-resources.md b/docs/usage/custom-resources.md new file mode 100644 index 0000000000..5d5e472f2f --- /dev/null +++ b/docs/usage/custom-resources.md @@ -0,0 +1,109 @@ +--- +title: "CRDs" +layout: default +sort: 6 +--- + +# Custom Resources +{: .no_toc} + +## Table of contents +{: .no_toc .text-delta} + +1. TOC +{:toc} + +--- + +NFD uses some Kubernetes [custom resources][custom-resources]. + +## NodeFeatureRule + +NodeFeatureRule is an NFD-specific custom resource that is designed for +rule-based custom labeling of nodes. NFD-Master watches for NodeFeatureRule +objects in the cluster and labels nodes according to the rules within. Some use +cases are e.g. application specific labeling in a specific environments or +being distributed by hardware vendors to create specific labels for their +devices. + +```yaml +apiVersion: nfd.k8s-sigs.io/v1alpha1 +kind: NodeFeatureRule +metadata: + name: example-rule +spec: + rules: + - name: "example rule" + labels: + "example-custom-feature": "true" + # Label is created if all of the rules below match + matchFeatures: + # Match if "veth" kernel module is loaded + - feature: kernel.loadedmodule + matchExpressions: + veth: {op: Exists} + # Match if any PCI device with vendor 8086 exists in the system + - feature: pci.device + matchExpressions: + vendor: {op: In, value: ["8086"]} +``` + +See the +[Customization guide](customization-guide#node-feature-rule-custom-resource) +for full documentation of the NodeFeatureRule resource and its usage. + +## NodeResourceTopology + +When run with NFD-Topology-Updater, NFD creates NodeResourceTopology objects +corresponding to node resource hardware topology such as: + +```yaml +apiVersion: topology.node.k8s.io/v1alpha1 +kind: NodeResourceTopology +metadata: + name: node1 +topologyPolicies: ["SingleNUMANodeContainerLevel"] +zones: + - name: node-0 + type: Node + resources: + - name: cpu + capacity: 20 + allocatable: 16 + available: 10 + - name: vendor/nic1 + capacity: 3 + allocatable: 3 + available: 3 + - name: node-1 + type: Node + resources: + - name: cpu + capacity: 30 + allocatable: 30 + available: 15 + - name: vendor/nic2 + capacity: 6 + allocatable: 6 + available: 6 + - name: node-2 + type: Node + resources: + - name: cpu + capacity: 30 + allocatable: 30 + available: 15 + - name: vendor/nic1 + capacity: 3 + allocatable: 3 + available: 3 +``` + +The NodeResourceTopology objects created by NFD can be used to gain insight +into the allocatable resources along with the granularity of those resources at +a per-zone level (represented by node-0 and node-1 in the above example) or can +be used by an external entity (e.g. topology-aware scheduler plugin) to take an +action based on the gathered information. + + +[custom-resources]: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/ diff --git a/docs/usage/customization-guide.md b/docs/usage/customization-guide.md index 640cf7ac24..c34b345251 100644 --- a/docs/usage/customization-guide.md +++ b/docs/usage/customization-guide.md @@ -1,7 +1,7 @@ --- title: "Customization guide" layout: default -sort: 6 +sort: 7 --- # Customization guide diff --git a/docs/usage/examples-and-demos.md b/docs/usage/examples-and-demos.md index 1a3c9c65cd..7d64926292 100644 --- a/docs/usage/examples-and-demos.md +++ b/docs/usage/examples-and-demos.md @@ -1,7 +1,7 @@ --- title: "Examples and demos" layout: default -sort: 7 +sort: 8 --- # Examples and demos