diff --git a/docs/advanced/master-commandline-reference.md b/docs/advanced/master-commandline-reference.md new file mode 100644 index 000000000..3344c1f6e --- /dev/null +++ b/docs/advanced/master-commandline-reference.md @@ -0,0 +1,190 @@ +--- +title: "Master Cmdline Reference" +layout: default +sort: 2 +--- + +# NFD-Master Commandline Flags +{: .no_toc } + +## Table of Contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +To quickly view available command line flags execute `nfd-master --help`. +In a docker container: + +```bash +docker run gcr.io/k8s-staging-nfd/node-feature-discovery:master nfd-master --help +``` + +### -h, --help + +Print usage and exit. + +### --version + +Print version and exit. + +### --prune + +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 + +The `--port` flag specifies the TCP port that nfd-master listens for incoming requests. + +Default: 8080 + +Example: + +```bash +nfd-master --port=443 +``` + +### --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 +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` + +Example: + +```bash +nfd-master --ca-file=/opt/nfd/ca.crt --cert-file=/opt/nfd/master.crt --key-file=/opt/nfd/master.key +``` + +### --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 +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` + +Example: + +```bash +nfd-master --cert-file=/opt/nfd/master.crt --key-file=/opt/nfd/master.key --ca-file=/opt/nfd/ca.crt +``` + +### --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 +nfd-master side. This flag specifies the private key corresponding the given +certificate file (`--cert-file`) that is used for authenticating outgoing +traffic. + +Default: *empty* + +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 +``` + +### --verify-node-name + +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 +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 +certificate. + +Node Name based authorization is disabled by default and thus it is possible +for all nfd-worker pods in the cluster to use one shared certificate, making +NFD deployment much easier. + +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 +``` + +### --no-publish + +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. + +Default: *false* + +Example: + +```bash +nfd-master --no-publish +``` + +### --label-whitelist + +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. + +Note: The regular expression is only matches against the "basename" part of the +label, i.e. to the part of the name after '/'. The label namespace is omitted. + +Default: *empty* + +Example: + +```bash +nfd-master --label-whitelist='.*cpuid\.' +``` + +### --extra-label-ns + +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. + +Default: *empty* + +Example: + +```bash +nfd-master --extra-label-ns=vendor-1.com,vendor-2.io +``` + +### --resource-labels + +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. + +Default: *empty* + +Example: + +```bash +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 new file mode 100644 index 000000000..a19fb111b --- /dev/null +++ b/docs/advanced/worker-commandline-reference.md @@ -0,0 +1,208 @@ +--- +title: "Worker Cmdline Reference" +layout: default +sort: 3 +--- + +# NFD-Worker Commandline Flags +{: .no_toc } + +## Table of Contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +To quickly view available command line flags execute `nfd-worker --help`. +In a docker container: + +```bash +docker run gcr.io/k8s-staging-nfd/node-feature-discovery:master nfd-worker --help +``` + +### -h, --help + +Print usage and exit. + +### --version + +Print version and exit. + +### --config + +The `--config` flag specifies the path of the nfd-worker configuration file to +use. + +Default: /etc/kubernetes/node-feature-discovery/nfd-worker.conf + +Example: + +```bash +nfd-worker --config=/opt/nfd/worker.conf +``` + +### --options + +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: + +Default: *empty* + +Example: + +```bash +nfd-worker --options='{"sources":{"cpu":{"cpuid":{"attributeWhitelist":["AVX","AVX2"]}}}}' +``` + +### --server + +The `--server` flag specifies the address of the nfd-master endpoint where to +connect to. + +Default: localhost:8080 + +Example: + +```bash +nfd-worker --server=nfd-master.nfd.svc.cluster.local:443 +``` + +### --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. +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` + +Example: + +```bash +nfd-worker --ca-file=/opt/nfd/ca.crt --cert-file=/opt/nfd/worker.crt --key-file=/opt/nfd/worker.key +``` + +### --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 +flag specifies the TLS certificate presented for authenticating outgoing +requests. + +Default: *empty* + +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 +``` + +### --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. +This flag specifies the private key corresponding the given certificate file +(`--cert-file`) that is used for authenticating outgoing requests. + +Default: *empty* + +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 +``` + +### --server-name-override + +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. + +Default: *empty* + +Example: + +```bash +nfd-worker --server-name-override=localhost +``` + +### --sources + +The `--sources` flag specifies a comma-separated list of enabled feature +sources. + +Default: cpu,custom,iommu,kernel,local,memory,network,pci,storage,system,usb + +Example: + +```bash +nfd-worker --sources=kernel,system,local +``` + +### --no-publish + +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. + +Default: *false* + +Example: + +```bash +nfd-worker --no-publish +``` + +### --label-whitelist + +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. + +Note: The regular expression is only matches against the "basename" part of the +label, i.e. to the part of the name after '/'. The label namespace is omitted. + +Default: *empty* + +Example: + +```bash +nfd-worker --label-whitelist='.*cpuid\.' +``` + +### --oneshot + +The `--oneshot` flag causes nfd-worker to exit after one pass of feature +detection. + +Default: *false* + +Example: + +```bash +nfd-worker --oneshot --no-publish +``` + +### --sleep-interval + +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. + +Default: 60s + +Example: + +```bash +nfd-worker --sleep-interval=1h +```