diff --git a/docs/advanced/developer-guide.md b/docs/advanced/developer-guide.md index ce472f50a..484209823 100644 --- a/docs/advanced/developer-guide.md +++ b/docs/advanced/developer-guide.md @@ -151,12 +151,12 @@ features-detection. ### NFD-Master When running as a standalone container labeling is expected to fail because -Kubernetes API is not available. Thus, it is recommended to use `--no-publish` +Kubernetes API is not available. Thus, it is recommended to use `-no-publish` command line flag. E.g. ```bash $ export NFD_CONTAINER_IMAGE={{ site.container_image }} -$ docker run --rm --name=nfd-test ${NFD_CONTAINER_IMAGE} nfd-master --no-publish +$ docker run --rm --name=nfd-test ${NFD_CONTAINER_IMAGE} nfd-master -no-publish 2019/02/01 14:48:21 Node Feature Discovery Master 2019/02/01 14:48:21 gRPC server serving on port: 8080 ``` @@ -206,7 +206,7 @@ $ docker run --rm --network=container:nfd-test ${NFD_CONTAINER_IMAGE} nfd-worker ``` If you just want to try out feature discovery without connecting to nfd-master, -pass the `--no-publish` flag to nfd-worker. +pass the `-no-publish` flag to nfd-worker. Command line flags of nfd-worker: diff --git a/docs/advanced/master-commandline-reference.md b/docs/advanced/master-commandline-reference.md index 58089b0de..7cf641585 100644 --- a/docs/advanced/master-commandline-reference.md +++ b/docs/advanced/master-commandline-reference.md @@ -15,42 +15,42 @@ sort: 2 --- -To quickly view available command line flags execute `nfd-master --help`. +To quickly view available command line flags execute `nfd-master -help`. In a docker container: ```bash -docker run {{ site.container_image }} nfd-master --help +docker run {{ site.container_image }} nfd-master -help ``` -### -h, --help +### -h, -help Print usage and exit. -### --version +### -version Print version and exit. -### --prune +### -prune -The `--prune` flag is a sub-command like option for cleaning up the cluster. It +The `-prune` flag is a sub-command like option for cleaning up the cluster. It causes nfd-master to remove all NFD related labels, annotations and extended resources from all Node objects of the cluster and exit. -### --port +### -port -The `--port` flag specifies the TCP port that nfd-master listens for incoming requests. +The `-port` flag specifies the TCP port that nfd-master listens for incoming requests. Default: 8080 Example: ```bash -nfd-master --port=443 +nfd-master -port=443 ``` -### --instance +### -instance -The `--instance` flag makes it possible to run multiple NFD deployments in +The `-instance` flag makes it possible to run multiple NFD deployments in parallel. In practice, it separates the node annotations between deployments so that each of them can store metadata independently. The instance name must start and end with an alphanumeric character and may only contain alphanumeric @@ -61,67 +61,67 @@ Default: *empty* Example: ```bash -nfd-master --instance=network +nfd-master -instance=network ``` -### --ca-file +### -ca-file -The `--ca-file` is one of the three flags (together with `--cert-file` and -`--key-file`) controlling master-worker mutual TLS authentication on the +The `-ca-file` is one of the three flags (together with `-cert-file` and +`-key-file`) controlling master-worker mutual TLS authentication on the nfd-master side. This flag specifies the TLS root certificate that is used for authenticating incoming connections. NFD-Worker side needs to have matching key and cert files configured in order for the incoming requests to be accepted. Default: *empty* -Note: Must be specified together with `--cert-file` and `--key-file` +Note: Must be specified together with `-cert-file` and `-key-file` Example: ```bash -nfd-master --ca-file=/opt/nfd/ca.crt --cert-file=/opt/nfd/master.crt --key-file=/opt/nfd/master.key +nfd-master -ca-file=/opt/nfd/ca.crt -cert-file=/opt/nfd/master.crt -key-file=/opt/nfd/master.key ``` -### --cert-file +### -cert-file -The `--cert-file` is one of the three flags (together with `--ca-file` and -`--key-file`) controlling master-worker mutual TLS authentication on the +The `-cert-file` is one of the three flags (together with `-ca-file` and +`-key-file`) controlling master-worker mutual TLS authentication on the nfd-master side. This flag specifies the TLS certificate presented for authenticating outgoing traffic towards nfd-worker. Default: *empty* -Note: Must be specified together with `--ca-file` and `--key-file` +Note: Must be specified together with `-ca-file` and `-key-file` Example: ```bash -nfd-master --cert-file=/opt/nfd/master.crt --key-file=/opt/nfd/master.key --ca-file=/opt/nfd/ca.crt +nfd-master -cert-file=/opt/nfd/master.crt -key-file=/opt/nfd/master.key -ca-file=/opt/nfd/ca.crt ``` -### --key-file +### -key-file -The `--key-file` is one of the three flags (together with `--ca-file` and -`--cert-file`) controlling master-worker mutual TLS authentication on the +The `-key-file` is one of the three flags (together with `-ca-file` and +`-cert-file`) controlling master-worker mutual TLS authentication on the nfd-master side. This flag specifies the private key corresponding the given -certificate file (`--cert-file`) that is used for authenticating outgoing +certificate file (`-cert-file`) that is used for authenticating outgoing traffic. Default: *empty* -Note: Must be specified together with `--cert-file` and `--ca-file` +Note: Must be specified together with `-cert-file` and `-ca-file` Example: ```bash -nfd-master --key-file=/opt/nfd/master.key --cert-file=/opt/nfd/master.crt --ca-file=/opt/nfd/ca.crt +nfd-master -key-file=/opt/nfd/master.key -cert-file=/opt/nfd/master.crt -ca-file=/opt/nfd/ca.crt ``` -### --verify-node-name +### -verify-node-name -The `--verify-node-name` flag controls the NodeName based authorization of +The `-verify-node-name` flag controls the NodeName based authorization of incoming requests and only has effect when mTLS authentication has been enabled -(with `--ca-file`, `--cert-file` and `--key-file`). If enabled, the worker node +(with `-ca-file`, `-cert-file` and `-key-file`). If enabled, the worker node name of the incoming must match with the CN in its TLS certificate. Thus, workers are only able to label the node they are running on (or the node whose certificate they present), and, each worker must have an individual @@ -136,13 +136,13 @@ Default: *false* Example: ```bash -nfd-master --verify-node-name --ca-file=/opt/nfd/ca.crt \ - --cert-file=/opt/nfd/master.crt --key-file=/opt/nfd/master.key +nfd-master -verify-node-name -ca-file=/opt/nfd/ca.crt \ + -cert-file=/opt/nfd/master.crt -key-file=/opt/nfd/master.key ``` -### --no-publish +### -no-publish -The `--no-publish` flag disables all communication with the Kubernetes API +The `-no-publish` flag disables all communication with the Kubernetes API server, making a "dry-run" flag for nfd-master. No Labels, Annotations or ExtendedResources (or any other properties of any Kubernetes API objects) are modified. @@ -152,12 +152,12 @@ Default: *false* Example: ```bash -nfd-master --no-publish +nfd-master -no-publish ``` -### --label-whitelist +### -label-whitelist -The `--label-whitelist` specifies a regular expression for filtering feature +The `-label-whitelist` specifies a regular expression for filtering feature labels based on their name. Each label must match against the given reqular expression in order to be published. @@ -169,31 +169,31 @@ Default: *empty* Example: ```bash -nfd-master --label-whitelist='.*cpuid\.' +nfd-master -label-whitelist='.*cpuid\.' ``` -### --extra-label-ns +### -extra-label-ns -The `--extra-label-ns` flag specifies a comma-separated list of allowed feature +The `-extra-label-ns` flag specifies a comma-separated list of allowed feature label namespaces. By default, nfd-master only allows creating labels in the default `feature.node.kubernetes.io` label namespace. This option can be used to allow vendor-specific namespaces for custom labels from the local and custom feature sources. The same namespace control and this flag applies Extended Resources (created -with `--resource-labels`), too. +with `-resource-labels`), too. Default: *empty* Example: ```bash -nfd-master --extra-label-ns=vendor-1.com,vendor-2.io +nfd-master -extra-label-ns=vendor-1.com,vendor-2.io ``` -### --resource-labels +### -resource-labels -The `--resource-labels` flag specifies a comma-separated list of features to be +The `-resource-labels` flag specifies a comma-separated list of features to be advertised as extended resources instead of labels. Features that have integer values can be published as Extended Resources by listing them in this flag. @@ -202,5 +202,5 @@ Default: *empty* Example: ```bash -nfd-master --resource-labels=vendor-1.com/feature-1,vendor-2.io/feature-2 +nfd-master -resource-labels=vendor-1.com/feature-1,vendor-2.io/feature-2 ``` diff --git a/docs/advanced/worker-commandline-reference.md b/docs/advanced/worker-commandline-reference.md index bbfed916b..e41c0d7fe 100644 --- a/docs/advanced/worker-commandline-reference.md +++ b/docs/advanced/worker-commandline-reference.md @@ -15,24 +15,24 @@ sort: 3 --- -To quickly view available command line flags execute `nfd-worker --help`. +To quickly view available command line flags execute `nfd-worker -help`. In a docker container: ```bash -docker run {{ site.container_image }} nfd-worker --help +docker run {{ site.container_image }} nfd-worker -help ``` -### -h, --help +### -h, -help Print usage and exit. -### --version +### -version Print version and exit. -### --config +### -config -The `--config` flag specifies the path of the nfd-worker configuration file to +The `-config` flag specifies the path of the nfd-worker configuration file to use. Default: /etc/kubernetes/node-feature-discovery/nfd-worker.conf @@ -40,12 +40,12 @@ Default: /etc/kubernetes/node-feature-discovery/nfd-worker.conf Example: ```bash -nfd-worker --config=/opt/nfd/worker.conf +nfd-worker -config=/opt/nfd/worker.conf ``` -### --options +### -options -The `--options` flag may be used to specify and override configuration file +The `-options` flag may be used to specify and override configuration file options directly from the command line. The required format is the same as in the config file i.e. JSON or YAML. Configuration options specified via this flag will override those from the configuration file: @@ -55,12 +55,12 @@ Default: *empty* Example: ```bash -nfd-worker --options='{"sources":{"cpu":{"cpuid":{"attributeWhitelist":["AVX","AVX2"]}}}}' +nfd-worker -options='{"sources":{"cpu":{"cpuid":{"attributeWhitelist":["AVX","AVX2"]}}}}' ``` -### --server +### -server -The `--server` flag specifies the address of the nfd-master endpoint where to +The `-server` flag specifies the address of the nfd-master endpoint where to connect to. Default: localhost:8080 @@ -68,63 +68,63 @@ Default: localhost:8080 Example: ```bash -nfd-worker --server=nfd-master.nfd.svc.cluster.local:443 +nfd-worker -server=nfd-master.nfd.svc.cluster.local:443 ``` -### --ca-file +### -ca-file -The `--ca-file` is one of the three flags (together with `--cert-file` and -`--key-file`) controlling the mutual TLS authentication on the worker side. +The `-ca-file` is one of the three flags (together with `-cert-file` and +`-key-file`) controlling the mutual TLS authentication on the worker side. This flag specifies the TLS root certificate that is used for verifying the authenticity of nfd-master. Default: *empty* -Note: Must be specified together with `--cert-file` and `--key-file` +Note: Must be specified together with `-cert-file` and `-key-file` Example: ```bash -nfd-worker --ca-file=/opt/nfd/ca.crt --cert-file=/opt/nfd/worker.crt --key-file=/opt/nfd/worker.key +nfd-worker -ca-file=/opt/nfd/ca.crt -cert-file=/opt/nfd/worker.crt -key-file=/opt/nfd/worker.key ``` -### --cert-file +### -cert-file -The `--cert-file` is one of the three flags (together with `--ca-file` and -`--key-file`) controlling mutual TLS authentication on the worker side. This +The `-cert-file` is one of the three flags (together with `-ca-file` and +`-key-file`) controlling mutual TLS authentication on the worker side. This flag specifies the TLS certificate presented for authenticating outgoing requests. Default: *empty* -Note: Must be specified together with `--ca-file` and `--key-file` +Note: Must be specified together with `-ca-file` and `-key-file` Example: ```bash -nfd-workerr --cert-file=/opt/nfd/worker.crt --key-file=/opt/nfd/worker.key --ca-file=/opt/nfd/ca.crt +nfd-workerr -cert-file=/opt/nfd/worker.crt -key-file=/opt/nfd/worker.key -ca-file=/opt/nfd/ca.crt ``` -### --key-file +### -key-file -The `--key-file` is one of the three flags (together with `--ca-file` and -`--cert-file`) controlling the mutual TLS authentication on the worker side. +The `-key-file` is one of the three flags (together with `-ca-file` and +`-cert-file`) controlling the mutual TLS authentication on the worker side. This flag specifies the private key corresponding the given certificate file -(`--cert-file`) that is used for authenticating outgoing requests. +(`-cert-file`) that is used for authenticating outgoing requests. Default: *empty* -Note: Must be specified together with `--cert-file` and `--ca-file` +Note: Must be specified together with `-cert-file` and `-ca-file` Example: ```bash -nfd-worker --key-file=/opt/nfd/worker.key --cert-file=/opt/nfd/worker.crt --ca-file=/opt/nfd/ca.crt +nfd-worker -key-file=/opt/nfd/worker.key -cert-file=/opt/nfd/worker.crt -ca-file=/opt/nfd/ca.crt ``` -### --server-name-override +### -server-name-override -The `--server-name-override` flag specifies the common name (CN) which to +The `-server-name-override` flag specifies the common name (CN) which to expect from the nfd-master TLS certificate. This flag is mostly intended for development and debugging purposes. @@ -133,12 +133,12 @@ Default: *empty* Example: ```bash -nfd-worker --server-name-override=localhost +nfd-worker -server-name-override=localhost ``` -### --sources +### -sources -The `--sources` flag specifies a comma-separated list of enabled feature +The `-sources` flag specifies a comma-separated list of enabled feature sources. A special value `all` enables all feature sources. Note: This flag takes precedence over the `core.sources` configuration @@ -149,15 +149,15 @@ Default: all Example: ```bash -nfd-worker --sources=kernel,system,local +nfd-worker -sources=kernel,system,local ``` **DEPRECATED**: you should use the `core.sources` option in the configuration file, instead. -### --no-publish +### -no-publish -The `--no-publish` flag disables all communication with the nfd-master, making +The `-no-publish` flag disables all communication with the nfd-master, making it a "dry-run" flag for nfd-worker. NFD-Worker runs feature detection normally, but no labeling requests are sent to nfd-master. @@ -166,12 +166,12 @@ Default: *false* Example: ```bash -nfd-worker --no-publish +nfd-worker -no-publish ``` -### --label-whitelist +### -label-whitelist -The `--label-whitelist` specifies a regular expression for filtering feature +The `-label-whitelist` specifies a regular expression for filtering feature labels based on their name. Each label must match against the given reqular expression in order to be published. @@ -186,15 +186,15 @@ Default: *empty* Example: ```bash -nfd-worker --label-whitelist='.*cpuid\.' +nfd-worker -label-whitelist='.*cpuid\.' ``` **DEPRECATED**: you should use the `core.labelWhiteList` option in the configuration file, instead. -### --oneshot +### -oneshot -The `--oneshot` flag causes nfd-worker to exit after one pass of feature +The `-oneshot` flag causes nfd-worker to exit after one pass of feature detection. Default: *false* @@ -202,12 +202,12 @@ Default: *false* Example: ```bash -nfd-worker --oneshot --no-publish +nfd-worker -oneshot -no-publish ``` -### --sleep-interval +### -sleep-interval -The `--sleep-interval` specifies the interval between feature re-detection (and +The `-sleep-interval` specifies the interval between feature re-detection (and node re-labeling). A non-positive value implies infinite sleep interval, i.e. no re-detection or re-labeling is done. @@ -219,7 +219,7 @@ Default: 60s Example: ```bash -nfd-worker --sleep-interval=1h +nfd-worker -sleep-interval=1h ``` **DEPRECATED**: you should use the `core.sleepInterval` option in the diff --git a/docs/get-started/deployment-and-usage.md b/docs/get-started/deployment-and-usage.md index ddccd735e..297ef7000 100644 --- a/docs/get-started/deployment-and-usage.md +++ b/docs/get-started/deployment-and-usage.md @@ -233,10 +233,10 @@ and mames sure that new nodes are labeled as they are added to the cluster. 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 +the `-sleep-interval` option. In the [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 +`-sleep-interval` is specified. Also, the configuration file is re-read on each iteration providing a simple mechanism of run-time reconfiguration. ### TLS authentication @@ -245,15 +245,15 @@ NFD supports mutual TLS authentication between the nfd-master and nfd-worker instances. That is, nfd-worker and nfd-master both verify that the other end presents a valid certificate. -TLS authentication is enabled by specifying `--ca-file`, `--key-file` and -`--cert-file` args, on both the nfd-master and nfd-worker instances. +TLS authentication is enabled by specifying `-ca-file`, `-key-file` and +`-cert-file` args, on both the nfd-master and nfd-worker instances. The template specs provided with NFD contain (commented out) example configuration for enabling TLS authentication. The Common Name (CN) of the nfd-master certificate must match the DNS name of the nfd-master Service of the cluster. By default, nfd-master only check that -the nfd-worker has been signed by the specified root certificate (--ca-file). -Additional hardening can be enabled by specifying --verify-node-name in +the nfd-worker has been signed by the specified root certificate (-ca-file). +Additional hardening can be enabled by specifying -verify-node-name in 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. @@ -262,7 +262,7 @@ each nfd-worker requires a individual node-specific TLS certificate. NFD-Worker supports dynamic configuration through a configuration file. The default location is `/etc/kubernetes/node-feature-discovery/nfd-worker.conf`, -but, this can be changed by specifying the`--config` command line flag. +but, this can be changed by specifying the`-config` command line flag. Configuration file is re-read whenever it is modified which makes run-time re-configuration of nfd-worker straightforward. @@ -286,12 +286,12 @@ The (empty-by-default) contains all available configuration options and can be used as a reference for creating creating a configuration. -Configuration options can also be specified via the `--options` command line +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: ``` ---options='{"sources": { "pci": { "deviceClassWhitelist": ["12"] } } }' +-options='{"sources": { "pci": { "deviceClassWhitelist": ["12"] } } }' ``` Configuration options specified from the command line will override those read @@ -366,7 +366,7 @@ kubectl delete clusterrolebinding nfd-master ### Removing Feature Labels -NFD-Master has a special `--prune` command line flag for removing all +NFD-Master has a special `-prune` command line flag for removing all nfd-related node labels, annotations and extended resources from the cluster. ```bash diff --git a/docs/get-started/features.md b/docs/get-started/features.md index 314892416..4cd6906bf 100644 --- a/docs/get-started/features.md +++ b/docs/get-started/features.md @@ -41,12 +41,12 @@ The last component (i.e. `attribute-name`) is optional, and only used if a feature logically has sub-hierarchy, e.g. `sriov.capable` and `sriov.configure` from the `network` source. -The `--sources` flag controls which sources to use for discovery. +The `-sources` flag controls which sources to use for discovery. *Note: Consecutive runs of nfd-worker will update the labels on a given node. If features are not discovered on a consecutive run, the corresponding label will be removed. This includes any restrictions placed on the consecutive run, -such as restricting discovered features with the --label-whitelist option.* +such as restricting discovered features with the -label-whitelist option.* ## Feature Sources @@ -559,11 +559,11 @@ e.g. for overriding labels created by other feature sources. You can also override the default namespace of your labels using this format: `/[=]`. You must whitelist your namespace using the -`--extra-label-ns` option on the master. In this case, the name of the +`-extra-label-ns` option on the master. In this case, the name of the file will not be added to the label name. For example, if you want to add the label `my.namespace.org/my-label=value`, your hook output or file must contains `my.namespace.org/my-label=value` and you must add -`--extra-label-ns=my.namespace.org` on the master command line. +`-extra-label-ns=my.namespace.org` on the master command line. `stderr` output of the hooks is propagated to NFD log so it can be used for debugging and logging. @@ -649,13 +649,13 @@ This feature is experimental and by no means a replacement for the usage of device plugins. Labels which have integer values, can be promoted to Kubernetes extended -resources by listing them to the master `--resource-labels` command line flag. +resources by listing them to the master `-resource-labels` command line flag. These labels won't then show in the node label section, they will appear only as extended resources. An example use-case for the extended resources could be based on a hook which creates a label for the node SGX EPC memory section size. By giving the name of -that label in the `--resource-labels` flag, that value will then turn into an +that label in the `-resource-labels` flag, that value will then turn into an extended resource of the node, allowing PODs to request that resource and the Kubernetes scheduler to schedule such PODs to only those nodes which have a sufficient capacity of said resource left. @@ -665,7 +665,7 @@ automatically prefixed to the extended resource, if the promoted label doesn't have a namespace. Example usage of the command line arguments, using a new namespace: -`nfd-master --resource-labels=my_source-my.feature,sgx.some.ns/epc --extra-label-ns=sgx.some.ns` +`nfd-master -resource-labels=my_source-my.feature,sgx.some.ns/epc -extra-label-ns=sgx.some.ns` The above would result in following extended resources provided that related labels exist: