Merge pull request #974 from marquiz/docs/crds

docs: better document custom resources

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.

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:       <none>
-Annotations:  <none>
-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:               <none>
-```
-
-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.
-
 <!-- Links -->
 [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

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.
+
+<!-- Links -->
+[custom-resources]: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/

docs/usage/customization-guide.md

@@ -1,7 +1,7 @@
 ---
 title: "Customization guide"
 layout: default
-sort: 6
+sort: 7
 ---
 
 # Customization guide

docs/usage/examples-and-demos.md

@@ -1,7 +1,7 @@
 ---
 title: "Examples and demos"
 layout: default
-sort: 7
+sort: 8
 ---
 
 # Examples and demos