diff --git a/docs/advanced/architecture.md b/docs/advanced/architecture.md index ef9596df5..ea25bbc97 100644 --- a/docs/advanced/architecture.md +++ b/docs/advanced/architecture.md @@ -6,9 +6,11 @@ published: false --- # Architecture + {: .no_toc } ## Table of contents + {: .no_toc .text-delta } 1. TOC @@ -16,6 +18,6 @@ published: false --- -***WORK IN PROGRESS*** +***WORK IN PROGRESS.*** This page first gives an architectural overview and describes principles behind. diff --git a/docs/advanced/customization-guide.md b/docs/advanced/customization-guide.md index a581474f1..b03093b27 100644 --- a/docs/advanced/customization-guide.md +++ b/docs/advanced/customization-guide.md @@ -6,9 +6,11 @@ published: false --- # Customization Guide + {: .no_toc } ## Table of Contents + {: .no_toc .text-delta } 1. TOC @@ -16,7 +18,7 @@ published: false --- -***WORK IN PROGRESS*** +***WORK IN PROGRESS.*** This document explains with examples how to use hooks, feature files and the custom feature source. diff --git a/docs/advanced/developer-guide.md b/docs/advanced/developer-guide.md index 484209823..581b72819 100644 --- a/docs/advanced/developer-guide.md +++ b/docs/advanced/developer-guide.md @@ -5,9 +5,11 @@ sort: 1 --- # Developer Guide + {: .no_toc } ## Table of contents + {: .no_toc .text-delta } 1. TOC @@ -36,6 +38,7 @@ make ``` #### Push the container image + Optional, this example with Docker. ```bash @@ -117,13 +120,16 @@ make IMAGE_REGISTRY= Or to specify a build tool different from Docker, It can be done in 2 ways: 1. via environment -```bash -IMAGE_BUILD_CMD="buildah bud" make -``` + + ```bash + IMAGE_BUILD_CMD="buildah bud" make + ``` + 1. by overriding the variable value -```bash -make IMAGE_BUILD_CMD="buildah bud" -``` + + ```bash + make IMAGE_BUILD_CMD="buildah bud" + ``` ### Testing @@ -167,31 +173,31 @@ Command line flags of nfd-master: $ docker run --rm ${NFD_CONTAINER_IMAGE} nfd-master -help Usage of nfd-master: -ca-file string - Root certificate for verifying connections + Root certificate for verifying connections -cert-file string - Certificate used for authenticating connections + Certificate used for authenticating connections -extra-label-ns value - Comma separated list of allowed extra label namespaces + Comma separated list of allowed extra label namespaces -instance string - Instance name. Used to separate annotation namespaces for multiple parallel deployments. + Instance name. Used to separate annotation namespaces for multiple parallel deployments. -key-file string - Private key matching -cert-file + Private key matching -cert-file -kubeconfig string - Kubeconfig to use + Kubeconfig to use -label-whitelist value - Regular expression to filter label names to publish to the Kubernetes API server. NB: the label namespace is omitted i.e. the filter is only applied to the name part after '/'. + Regular expression to filter label names to publish to the Kubernetes API server. NB: the label namespace is omitted i.e. the filter is only applied to the name part after '/'. -no-publish - Do not publish feature labels + Do not publish feature labels -port int - Port on which to listen for connections. (default 8080) + Port on which to listen for connections. (default 8080) -prune - Prune all NFD related attributes from all nodes of the cluaster and exit. + Prune all NFD related attributes from all nodes of the cluaster and exit. -resource-labels value - Comma separated list of labels to be exposed as extended resources. + Comma separated list of labels to be exposed as extended resources. -verify-node-name - Verify worker node name against CN from the TLS certificate. Only takes effect when TLS authentication has been enabled. + Verify worker node name against CN from the TLS certificate. Only takes effect when TLS authentication has been enabled. -version - Print version and exit. + Print version and exit. ``` ### NFD-Worker @@ -214,44 +220,44 @@ Command line flags of nfd-worker: $ docker run --rm ${NFD_CONTAINER_IMAGE} nfd-worker -help Usage of nfd-worker: -ca-file string - Root certificate for verifying connections + Root certificate for verifying connections -cert-file string - Certificate used for authenticating connections + Certificate used for authenticating connections -config string - Config file to use. (default "/etc/kubernetes/node-feature-discovery/nfd-worker.conf") + Config file to use. (default "/etc/kubernetes/node-feature-discovery/nfd-worker.conf") -key-file string - Private key matching -cert-file + Private key matching -cert-file -label-whitelist value - Regular expression to filter label names to publish to the Kubernetes API server. NB: the label namespace is omitted i.e. the filter is only applied to the name part after '/'. DEPRECATED: This parameter should be set via the config file. + Regular expression to filter label names to publish to the Kubernetes API server. NB: the label namespace is omitted i.e. the filter is only applied to the name part after '/'. DEPRECATED: This parameter should be set via the config file. -no-publish - Do not publish discovered features, disable connection to nfd-master. + Do not publish discovered features, disable connection to nfd-master. -oneshot - Do not publish feature labels + Do not publish feature labels -options string - Specify config options from command line. Config options are specified in the same format as in the config file (i.e. json or yaml). These options + Specify config options from command line. Config options are specified in the same format as in the config file (i.e. json or yaml). These options -server string - NFD server address to connecto to. (default "localhost:8080") + NFD server address to connecto to. (default "localhost:8080") -server-name-override string - Hostname expected from server certificate, useful in testing + Hostname expected from server certificate, useful in testing -sleep-interval duration - Time to sleep between re-labeling. Non-positive value implies no re-labeling (i.e. infinite sleep). DEPRECATED: This parameter should be set via the config file + Time to sleep between re-labeling. Non-positive value implies no re-labeling (i.e. infinite sleep). DEPRECATED: This parameter should be set via the config file -sources value - Comma separated list of feature sources. Special value 'all' enables all feature sources. DEPRECATED: This parameter should be set via the config file + Comma separated list of feature sources. Special value 'all' enables all feature sources. DEPRECATED: This parameter should be set via the config file -version - Print version and exit. + Print version and exit. ``` **NOTE** Some feature sources need certain directories and/or files from the host mounted inside the NFD container. Thus, you need to provide Docker with the correct `--volume` options in order for them to work correctly when run stand-alone directly with `docker run`. See the -[template spec](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{ site.release }}/nfd-worker-daemonset.yaml.template) +[template spec](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{site.release}}/nfd-worker-daemonset.yaml.template) for up-to-date information about the required volume mounts. ## Documentation All documentation resides under the -[docs](https://github.com/kubernetes-sigs/node-feature-discovery/tree/{{ site.release }}/docs) +[docs](https://github.com/kubernetes-sigs/node-feature-discovery/tree/{{site.release}}/docs) directory in the source tree. It is designed to be served as a html site by [GitHub Pages](https://pages.github.com/). @@ -277,4 +283,4 @@ make site-build This will generate html documentation under `docs/_site/`. -[e2e-config-sample]: https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{ site.release }}/test/e2e/e2e-test-config.exapmle.yaml +[e2e-config-sample]: https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{site.release}}/test/e2e/e2e-test-config.exapmle.yaml diff --git a/docs/advanced/e2e-configuration-reference.md b/docs/advanced/e2e-configuration-reference.md index a67a23f5a..2275bb23f 100644 --- a/docs/advanced/e2e-configuration-reference.md +++ b/docs/advanced/e2e-configuration-reference.md @@ -6,9 +6,11 @@ published: false --- # End-to-End Test Configuration File Reference + {: .no_toc } ## Table of contents + {: .no_toc .text-delta } 1. TOC @@ -16,6 +18,6 @@ published: false --- -***WORK IN PROGRESS*** +***WORK IN PROGRESS.*** This section describes the end-to-end test configuration file. diff --git a/docs/advanced/master-commandline-reference.md b/docs/advanced/master-commandline-reference.md index 7cf641585..d352a23eb 100644 --- a/docs/advanced/master-commandline-reference.md +++ b/docs/advanced/master-commandline-reference.md @@ -5,9 +5,11 @@ sort: 2 --- # NFD-Master Commandline Flags + {: .no_toc } ## Table of Contents + {: .no_toc .text-delta } 1. TOC diff --git a/docs/advanced/worker-commandline-reference.md b/docs/advanced/worker-commandline-reference.md index e41c0d7fe..d33013e30 100644 --- a/docs/advanced/worker-commandline-reference.md +++ b/docs/advanced/worker-commandline-reference.md @@ -5,9 +5,11 @@ sort: 3 --- # NFD-Worker Commandline Flags + {: .no_toc } ## Table of Contents + {: .no_toc .text-delta } 1. TOC diff --git a/docs/advanced/worker-configuration-reference.md b/docs/advanced/worker-configuration-reference.md index 27dd98187..c26d8bcc3 100644 --- a/docs/advanced/worker-configuration-reference.md +++ b/docs/advanced/worker-configuration-reference.md @@ -5,12 +5,14 @@ sort: 4 --- # NFD-Worker Configuration File Reference + {: .no_toc } ## Table of contents + {: .no_toc .text-delta } -***WORK IN PROGRESS*** +***WORK IN PROGRESS.*** 1. TOC {:toc} @@ -18,7 +20,7 @@ sort: 4 --- See the -[sample configuration file](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{ site.release }}/nfd-worker.conf.example) +[sample configuration file](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{site.release}}/nfd-worker.conf.example) for a full example configuration. ## core diff --git a/docs/get-started/deployment-and-usage.md b/docs/get-started/deployment-and-usage.md index 297ef7000..4da0a1c91 100644 --- a/docs/get-started/deployment-and-usage.md +++ b/docs/get-started/deployment-and-usage.md @@ -5,9 +5,11 @@ sort: 3 --- # Deployment and Usage + {: .no_toc } ## Table of Contents + {: .no_toc .text-delta } 1. TOC @@ -36,24 +38,27 @@ is recommended to be done via [latest release](https://github.com/operator-framework/operator-lifecycle-manager/releases/latest) for detailed instructions. 1. Install the operator: -```bash -kubectl create -f https://operatorhub.io/install/nfd-operator.yaml -``` + + ```bash + kubectl create -f https://operatorhub.io/install/nfd-operator.yaml + ``` + 1. Create NodeFeatureDiscovery resource (in `nfd` namespace here): -```bash -cat << EOF | kubectl apply -f - -apiVersion: v1 -kind: Namespace -metadata: - name: nfd ---- -apiVersion: nfd.kubernetes.io/v1alpha1 -kind: NodeFeatureDiscovery -metadata: - name: my-nfd-deployment - namespace: nfd -EOF -``` + + ```bash + cat << EOF | kubectl apply -f - + apiVersion: v1 + kind: Namespace + metadata: + name: nfd + --- + apiVersion: nfd.kubernetes.io/v1alpha1 + kind: NodeFeatureDiscovery + metadata: + name: my-nfd-deployment + namespace: nfd + EOF + ``` ### Deployment Templates @@ -107,7 +112,7 @@ Node Feature Discovery Helm chart allow to easily deploy and manage NFD. [Helm package manager](https://helm.sh/) should be installed. -#### Deployment with Helm +#### Deployment To install the chart with the release name node-feature-discovery: @@ -118,8 +123,9 @@ export NFD_NS=node-feature-discovery helm install node-feature-discovery ./node-feature-discovery/ --namespace $NFD_NS --create-namespace ``` -The command deploys Node Feature Discovery on the Kubernetes cluster in the default configuration. -The Configuration section describes how it can be configured during installation. +The command deploys Node Feature Discovery on the Kubernetes cluster in the +default configuration. The Configuration section describes how it can be +configured during installation. #### Configuration @@ -146,7 +152,8 @@ export NFD_NS=node-feature-discovery helm uninstall node-feature-discovery --namespace $NFD_NS ``` -The command removes all the Kubernetes components associated with the chart and deletes the release. +The command removes all the Kubernetes components associated with the chart and +deletes the release. #### Chart Parameters @@ -167,7 +174,6 @@ We have introduced the following Chart parameters. | `nameOverride` | string | | Override the name of the chart | | `fullnameOverride` | string | | Override a default fully qualified app name | - ##### Master pod parameters | `master.*` | dict | | NFD master deployment configuration | @@ -194,7 +200,6 @@ We have introduced the following Chart parameters. | `worker.tolerations` | dict | {} | NFD worker pod [node tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) | | `worker.annotations` | dict | {} | NFD worker pod [metadata](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) | - ### Build Your Own If you want to use the latest development version (master branch) you need to @@ -234,7 +239,7 @@ Worker connects to the nfd-master service to advertise hardware features. When run as a daemonset, nodes are re-labeled at an interval specified using the `-sleep-interval` option. In the -[template](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{ site.release }}/nfd-worker-daemonset.yaml.template#L26) +[template](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{site.release}}/nfd-worker-daemonset.yaml.template#L26) the default interval is set to 60s which is also the default when no `-sleep-interval` is specified. Also, the configuration file is re-read on each iteration providing a simple mechanism of run-time reconfiguration. @@ -258,7 +263,7 @@ nfd-master args, in which case nfd-master verifies that the NodeName presented by nfd-worker matches the Common Name (CN) of its certificate. This means that each nfd-worker requires a individual node-specific TLS certificate. -## Configuration +## Worker Configuration NFD-Worker supports dynamic configuration through a configuration file. The default location is `/etc/kubernetes/node-feature-discovery/nfd-worker.conf`, @@ -274,7 +279,7 @@ re-configurability. The provided nfd-worker deployment templates create an empty configmap and mount it inside the nfd-worker containers. Configuration can be edited with: -``` +```bash kubectl -n ${NFD_NS} edit configmap nfd-worker-conf ``` @@ -282,7 +287,7 @@ See [nfd-worker configuration file reference](../advanced/worker-configuration-reference.md) for more details. The (empty-by-default) -[example config](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{ site.release }}/nfd-worker.conf.example) +[example config](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{site.release}}/nfd-worker.conf.example) contains all available configuration options and can be used as a reference for creating creating a configuration. @@ -290,7 +295,7 @@ Configuration options can also be specified via the `-options` command line flag, in which case no mounts need to be used. The same format as in the config file must be used, i.e. JSON (or YAML). For example: -``` +```bash -options='{"sources": { "pci": { "deviceClassWhitelist": ["12"] } } }' ``` diff --git a/docs/get-started/examples-and-demos.md b/docs/get-started/examples-and-demos.md index 6e23a5205..277492192 100644 --- a/docs/get-started/examples-and-demos.md +++ b/docs/get-started/examples-and-demos.md @@ -5,9 +5,11 @@ sort: 5 --- # Examples And Demos + {: .no_toc } ## Table of Contents + {: .no_toc .text-delta } 1. TOC @@ -27,4 +29,4 @@ This page contains usage examples and demos. A demo on the benefits of using node feature discovery can be found in the source code repository under -[demo/](https://github.com/kubernetes-sigs/node-feature-discovery/tree/{{ site.release }}/demo). +[demo/](https://github.com/kubernetes-sigs/node-feature-discovery/tree/{{site.release}}/demo). diff --git a/docs/get-started/features.md b/docs/get-started/features.md index 4cd6906bf..cdd6bb9d3 100644 --- a/docs/get-started/features.md +++ b/docs/get-started/features.md @@ -5,9 +5,11 @@ sort: 4 --- # Feature Discovery + {: .no_toc } ## Table of Contents + {: .no_toc .text-delta } 1. TOC @@ -33,7 +35,7 @@ The published node labels encode a few pieces of information: Feature label names adhere to the following pattern: -``` +```plaintext /-[.] ``` @@ -147,7 +149,7 @@ ConfigMap, mounted into the `custom.d` directory. #### General Nomenclature & Definitions -``` +```plaintext Rule :Represents a matching logic that is used to match on a feature. Rule Input :The input a Rule is provided. This determines how a Rule performs the match operation. Matcher :A composition of Rules, each Matcher may be composed of at most one instance of each Rule. @@ -190,7 +192,7 @@ between Rules of a given Matcher. ###### Nomenclature -``` +```plaintext Attribute :A PCI attribute. Element :An identifier of the PCI attribute. ``` @@ -217,7 +219,7 @@ partake in the matching process. ###### Nomenclature -``` +```plaintext Attribute :A USB attribute. Element :An identifier of the USB attribute. ``` @@ -244,7 +246,7 @@ partake in the matching process. ###### Nomenclature -``` +```plaintext Element :A kernel module ``` @@ -265,7 +267,7 @@ system. ###### Nomenclature -``` +```plaintext Element :A CPUID flag ``` @@ -286,7 +288,7 @@ the system. ###### Nomenclature -``` +```plaintext Element :A Kconfig option ``` @@ -307,7 +309,7 @@ Rule will match if all provided Elements (kernel config options) are enabled ###### Nomenclature -``` +```plaintext Element :A nodename regexp pattern ``` @@ -426,7 +428,7 @@ The **kernel** feature source supports the following labels: | Feature | Attribute | Description | | ------- | ------------------- | -------------------------------------------- | -| config | <option name> | Kernel config option is enabled (set 'y' or 'm').
Default options are `NO_HZ`, `NO_HZ_IDLE`, `NO_HZ_FULL` and `PREEMPT` +| config | <option name> | Kernel config option is enabled (set 'y' or 'm'). Default options are `NO_HZ`, `NO_HZ_IDLE`, `NO_HZ_FULL` and `PREEMPT` | selinux | enabled | Selinux is enabled on the node | version | full | Full kernel version as reported by `/proc/sys/kernel/osrelease` (e.g. '4.5.6-7-g123abcde') | | major | First component of the kernel version (e.g. '4') @@ -471,7 +473,7 @@ of fields used in `` is configurable, valid fields being `class`, `vendor`, `device`, `subsystem_vendor` and `subsystem_device`. Defaults are `class` and `vendor`. An example label using the default label fields: -``` +```plaintext feature.node.kubernetes.io/pci-1200_8086.present=true ``` @@ -492,7 +494,7 @@ of fields used in `` is configurable, valid fields being `class`, `vendor`, and `device`. Defaults are `class`, `vendor` and `device`. An example label using the default label fields: -``` +```plaintext feature.node.kubernetes.io/usb-fe_1a6e_089a.present=true ``` @@ -575,7 +577,7 @@ Pods outside NFD, e.g. in Kubernetes device plugins. It is possible to mount the `source.d` and/or `features.d` directories common with the NFD Pod and deploy the custom hooks/features there. NFD will periodically scan the directories and run any hooks and read any feature files it finds. The -[example nfd-worker deployment template](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{ site.release }}/nfd-worker-daemonset.yaml.template#L69) +[example nfd-worker deployment template](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{site.release}}/nfd-worker-daemonset.yaml.template#L69) contains `hostPath` mounts for `sources.d` and `features.d` directories. By using the same mounts in the secondary Pod (e.g. device plugin) you have created a shared area for delivering hooks and feature files to NFD. @@ -586,7 +588,7 @@ User has a shell script `/etc/kubernetes/node-feature-discovery/source.d/my-source` which has the following `stdout` output: -``` +```plaintext MY_FEATURE_1 MY_FEATURE_2=myvalue /override_source-OVERRIDE_BOOL @@ -596,7 +598,7 @@ override.namespace/value=456 which, in turn, will translate into the following node labels: -``` +```plaintext feature.node.kubernetes.io/my-source-MY_FEATURE_1=true feature.node.kubernetes.io/my-source-MY_FEATURE_2=myvalue feature.node.kubernetes.io/override_source-OVERRIDE_BOOL=true @@ -609,7 +611,7 @@ override.namespace/value=456 User has a file `/etc/kubernetes/node-feature-discovery/features.d/my-source` which contains the following lines: -``` +```plaintext MY_FEATURE_1 MY_FEATURE_2=myvalue /override_source-OVERRIDE_BOOL @@ -619,7 +621,7 @@ override.namespace/value=456 which, in turn, will translate into the following node labels: -``` +```plaintext feature.node.kubernetes.io/my-source-MY_FEATURE_1=true feature.node.kubernetes.io/my-source-MY_FEATURE_2=myvalue feature.node.kubernetes.io/override_source-OVERRIDE_BOOL=true @@ -670,7 +672,7 @@ Example usage of the command line arguments, using a new namespace: The above would result in following extended resources provided that related labels exist: -``` +```plaintext sgx.some.ns/epc: