1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/node-feature-discovery.git synced 2024-12-14 11:57:51 +00:00

docs: fix mdlint issues

This commit is contained in:
Markus Lehtonen 2021-02-25 13:49:02 +02:00
parent bc289d0783
commit 3886cfb99e
11 changed files with 117 additions and 87 deletions

View file

@ -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.

View file

@ -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.

View file

@ -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=<my custom registry uri>
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/`.
<!-- Links -->
[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

View file

@ -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.

View file

@ -5,9 +5,11 @@ sort: 2
---
# NFD-Master Commandline Flags
{: .no_toc }
## Table of Contents
{: .no_toc .text-delta }
1. TOC

View file

@ -5,9 +5,11 @@ sort: 3
---
# NFD-Worker Commandline Flags
{: .no_toc }
## Table of Contents
{: .no_toc .text-delta }
1. TOC

View file

@ -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

View file

@ -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"] } } }'
```

View file

@ -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).

View file

@ -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
<namespace>/<source name>-<feature name>[.<attribute name>]
```
@ -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 | &lt;option name&gt; | Kernel config option is enabled (set 'y' or 'm').<br> Default options are `NO_HZ`, `NO_HZ_IDLE`, `NO_HZ_FULL` and `PREEMPT`
| config | &lt;option name&gt; | 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 `<device label>` 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 `<device label>` 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: <label value>
feature.node.kubernetes.io/my_source-my.feature: <label value>
```

View file

@ -5,9 +5,11 @@ sort: 1
---
# Introduction
{: .no_toc }
## Table of Contents
{: .no_toc .text-delta }
1. TOC
@ -90,6 +92,7 @@ NFD also annotates nodes it is running on:
NOTE: the [`--instance`](../advanced/master-commandline-reference.md#instance)
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.
Unapplicable annotations are not created, i.e. for example master.version is
only created on nodes running nfd-master.