Documentation capturing enablement of NFD-Topology-Updater in NFD

Prior to this feature, NFD consisted of only software components namely
nfd-master and nfd-worker. We have introduced another software component
called nfd-topology-updater.

NFD-Topology-Updater is a daemon responsible for examining allocated resources
on a worker node to account for allocatable resources on a per-zone basis (where
a zone can be a NUMA node). It then communicates the information to nfd-master
which does the CRD creation corresponding to all the nodes in the cluster. One
instance of nfd-topology-updater is supposed to be running on each node of the
cluster.

Signed-off-by: Swati Sehgal <swsehgal@redhat.com>

docs/advanced/developer-guide.md

@@ -184,6 +184,8 @@ Usage of nfd-master:
         Comma separated list of labels to be exposed as extended resources.
   -verify-node-name
         Verify worker node name against the worker's TLS certificate. Only takes effect when TLS authentication has been enabled.
+  -nrt-namespace
+        Namespace in which Node Resource Topology CR are created. Ensure that the namespace specified already exists
   -version
         Print version and exit.
 ```
@@ -242,6 +244,96 @@ stand-alone directly with `docker run`. See the
 [default deployment](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{site.release}}/deployment/components/common/worker-mounts.yaml)
 for up-to-date information about the required volume mounts.
 
+### NFD-Topology-Updater
+
+In order to run nfd-topology-updater as a "stand-alone" container against your
+standalone nfd-master you need to run them in the same network namespace:
+
+```bash
+$ docker run --rm --network=container:nfd-test ${NFD_CONTAINER_IMAGE} nfd-topology-updater
+2019/02/01 14:48:56 Node Feature Discovery Topology Updater <NFD_VERSION>
+...
+```
+
+If you just want to try out feature discovery without connecting to nfd-master,
+pass the `-no-publish` flag to nfd-topology-updater.
+
+Command line flags of nfd-topology-updater:
+
+```bash
+$ docker run --rm ${NFD_CONTAINER_IMAGE} nfd-topology-updater -help
+docker run --rm  quay.io/swsehgal/node-feature-discovery:v0.10.0-devel-64-g93a0a9f-dirty nfd-topology-updater -help
+Usage of nfd-topology-updater:
+  -add_dir_header
+       If true, adds the file directory to the header of the log messages
+  -alsologtostderr
+       log to standard error as well as files
+  -ca-file string
+       Root certificate for verifying connections
+  -cert-file string
+       Certificate used for authenticating connections
+  -key-file string
+       Private key matching -cert-file
+  -kubeconfig string
+       Kube config file.
+  -kubelet-config-file string
+       Kubelet config file path. (default "/host-var/lib/kubelet/config.yaml")
+  -log_backtrace_at value
+       when logging hits line file:N, emit a stack trace
+  -log_dir string
+       If non-empty, write log files in this directory
+  -log_file string
+       If non-empty, use this log file
+  -log_file_max_size uint
+       Defines the maximum size a log file can grow to. Unit is megabytes. If the value is 0, the maximum file size is unlimited. (default 1800)
+  -logtostderr
+       log to standard error instead of files (default true)
+  -no-publish
+       Do not publish discovered features to the cluster-local Kubernetes API server.
+  -one_output
+       If true, only write logs to their native severity level (vs also writing to each lower severity level)
+  -oneshot
+       Update once and exit
+  -podresources-socket string
+       Pod Resource Socket path to use. (default "/host-var/lib/kubelet/pod-resources/kubelet.sock")
+  -server string
+       NFD server address to connecto to. (default "localhost:8080")
+  -server-name-override string
+       Hostname expected from server certificate, useful in testing
+  -skip_headers
+       If true, avoid header prefixes in the log messages
+  -skip_log_headers
+       If true, avoid headers when opening log files
+  -sleep-interval duration
+       Time to sleep between CR updates. Non-positive value implies no CR updatation (i.e. infinite sleep). [Default: 60s] (default 1m0s)
+  -stderrthreshold value
+       logs at or above this threshold go to stderr (default 2)
+  -v value
+       number for the log level verbosity
+  -version
+       Print version and exit.
+  -vmodule value
+       comma-separated list of pattern=N settings for file-filtered logging
+  -watch-namespace string
+       Namespace to watch pods (for testing/debugging purpose). Use * for all namespaces. (default "*")
+```
+
+NOTE:
+
+* NFD topology updater needs 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}}/deployment/components/topology-updater/topologyupdater-mounts.yaml)
+for up-to-date information about the required volume mounts.
+
+* [PodResource API][podresource-api] is a prerequisite for nfd-topology-updater.
+Preceding Kubernetes v1.23, the `kubelet` must be started with the following flag:
+
+`--feature-gates=KubeletPodResourcesGetAllocatable=true`.
+Starting Kubernetes v1.23, the `GetAllocatableResources` is enabled by default
+through `KubeletPodResourcesGetAllocatable` [feature gate][feature-gate].
+
 ## Documentation
 
 All documentation resides under the
@@ -271,4 +363,6 @@ 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.example.yaml
+[e2e-config-sample]: https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{site.release}}/test/e2e/e2e-test-config.exapmle.yaml
+[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/advanced/topology-updater-commandline-reference.md

@@ -0,0 +1,197 @@
+---
+title: "Topology Updater Cmdline Reference"
+layout: default
+sort: 5
+---
+
+# NFD-Topology-Updater Commandline Flags
+
+{: .no_toc }
+
+## Table of Contents
+
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+To quickly view available command line flags execute `nfd-topology-updater -help`.
+In a docker container:
+
+```bash
+docker run gcr.io/k8s-staging-nfd/node-feature-discovery:master nfd-topology-updater -help
+```
+
+### -h, -help
+
+Print usage and exit.
+
+### -version
+
+Print version and exit.
+
+### -server
+
+The `-server` flag specifies the address of the nfd-master endpoint where to
+connect to.
+
+Default: localhost:8080
+
+Example:
+
+```bash
+nfd-topology-updater -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 topology-updater 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-topology-updater -ca-file=/opt/nfd/ca.crt -cert-file=/opt/nfd/updater.crt -key-file=/opt/nfd/updater.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 topology-updater
+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-topology-updater -cert-file=/opt/nfd/updater.crt -key-file=/opt/nfd/updater.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 topology-updater
+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-topology-updater -key-file=/opt/nfd/updater.key -cert-file=/opt/nfd/updater.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-topology-updater -server-name-override=localhost
+```
+
+### -no-publish
+
+The `-no-publish` flag disables all communication with the nfd-master, making
+it a "dry-run" flag for nfd-topology-updater. NFD-Topology-Updater runs
+resource hardware topology detection normally, but no CR requests are sent to
+nfd-master.
+
+Default: *false*
+
+Example:
+
+```bash
+nfd-topology-updater -no-publish
+```
+
+### -oneshot
+
+The `-oneshot` flag causes nfd-topology-updater to exit after one pass of
+resource hardware topology detection.
+
+Default: *false*
+
+Example:
+
+```bash
+nfd-topology-updater -oneshot -no-publish
+```
+
+### -sleep-interval
+
+The `-sleep-interval` specifies the interval between resource hardware
+topology re-examination (and CR updates). A non-positive value implies
+infinite sleep interval, i.e. no re-detection is done.
+
+Default: 60s
+
+Example:
+
+```bash
+nfd-topology-updater -sleep-interval=1h
+```
+
+### -watch-namespace
+
+The `-watch-namespace` specifies the namespace to ensure that resource
+hardware topology examination only happens for the pods running in the
+specified namespace. Pods that are not running in the specified namespace
+are not considered during resource accounting. This is particularly useful
+for testing/debugging purpose. A "*" value would mean that all the pods would
+be considered during the accounting process.
+
+Default: "*"
+
+Example:
+
+```bash
+nfd-topology-updater -watch-namespace=rte
+```
+
+### -kubelet-config-file
+
+The `-kubelet-config-file` specifies the path to the Kubelet's configuration
+file.
+
+Default:  /host-var/lib/kubelet/config.yaml
+
+Example:
+
+```bash
+nfd-topology-updater -kubelet-config-file=/var/lib/kubelet/config.yaml
+```
+
+### -podresources-socket
+
+The `-podresources-socket` specifies the path to the Unix socket where kubelet
+exports a gRPC service to enable discovery of in-use CPUs and devices, and to
+provide metadata for them.
+
+Default:  /host-var/liblib/kubelet/pod-resources/kubelet.sock
+
+Example:
+
+```bash
+nfd-topology-updater -podresources-socket=/var/lib/kubelet/pod-resources/kubelet.sock
+```