Further documentation fixes/cleanup based on review comments

Signed-off-by: Swati Sehgal <[email protected]>
kubernetes-sigs · Oct 21, 2021 · 97667b4 · 97667b4
1 parent 9185de3
commit 97667b4
Show file tree

Hide file tree

Showing 4 changed files with 91 additions and 69 deletions.
diff --git a/docs/advanced/topology-updater-commandline-reference.md b/docs/advanced/topology-updater-commandline-reference.md
@@ -17,14 +17,14 @@ sort: 5
 
 ---
 
-To quickly view available command line flags execute `nfd-topology-updater --help`.
+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
+docker run gcr.io/k8s-staging-nfd/node-feature-discovery:master nfd-topology-updater -help
 ```
 
-### -h, --help
+### -h, -help
 
 Print usage and exit.
 
@@ -34,71 +34,71 @@ Print version and exit.
 
 ### -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
 
 Example:
 
 ```bash
-nfd-topology-updater --server=nfd-master.nfd.svc.cluster.local:443
+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.
+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`
+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
+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
+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`
+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
+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
+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.
+(`-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-topology-updater --key-file=/opt/nfd/updater.key --cert-file=/opt/nfd/updater.crt --ca-file=/opt/nfd/ca.crt
+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
+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.
 
@@ -107,12 +107,12 @@ Default: *empty*
 Example:
 
 ```bash
-nfd-topology-updater --server-name-override=localhost
+nfd-topology-updater -server-name-override=localhost
 ```
 
 ### -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-topology-updater. NFD-Topology-Updater runs
 resource hardware topology detection normally, but no CR requests are sent to
 nfd-master.
@@ -122,25 +122,25 @@ Default: *false*
 Example:
 
 ```bash
-nfd-topology-updater --no-publish
+nfd-topology-updater -no-publish
 ```
 
 ### -oneshot
 
-The `--oneshot` flag causes nfd-topology-updater to exit after one pass of
+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
+nfd-topology-updater -oneshot -no-publish
 ```
 
 ### -sleep-interval
 
-The `--sleep-interval` specifies the interval between resource hardware
+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.
 
@@ -149,12 +149,12 @@ Default: 60s
 Example:
 
 ```bash
-nfd-topology-updater --sleep-interval=1h
+nfd-topology-updater -sleep-interval=1h
 ```
 
 ### -watch-namespace
 
-The `--watch-namespace` specifies the namespace to ensure that resource
+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
@@ -166,25 +166,25 @@ Default: "*"
 Example:
 
 ```bash
-nfd-topology-updater --watch-namespace=rte
+nfd-topology-updater -watch-namespace=rte
 ```
 
 ### -kubelet-config-file
 
-The `--kubelet-config-file` specifies the path to the Kubelet's configuration
+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
+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
+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.
 
@@ -193,5 +193,5 @@ Default:  /host-var/liblib/kubelet/pod-resources/kubelet.sock
 Example:
 
 ```bash
-nfd-topology-updater --podresources-socket=/var/lib/kubelet/pod-resources/kubelet.sock
+nfd-topology-updater -podresources-socket=/var/lib/kubelet/pod-resources/kubelet.sock
 ```
diff --git a/docs/get-started/deployment-and-usage.md b/docs/get-started/deployment-and-usage.md
@@ -121,8 +121,6 @@ scenarios under
   see [Master-worker pod](#master-worker-pod) below
 - [`default-job`](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{site.release}}/deployment/overlays/default-job):
   see [Worker one-shot](#worker-one-shot) below
-- [`topologyupdater`](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{site.release}}/deployment/overlays/topologyupdater)
-  see [Topologyupdater pod](#topologyupdater-pod) below
 - [`master-worker-topologyupdater`](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{site.release}}/deployment/overlays/master-worker-topologyupdater):
   see [Master Worker Topologyupdater](#master-worker-topologyupdater) below
 - [`topologyupdater`](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{site.release}}/deployment/overlays/topologyupdater):
@@ -175,24 +173,6 @@ this approach does not guarantee running once on every node. For example,
 tainted, non-ready nodes or some other reasons in Job scheduling may cause some
 node(s) will run extra job instance(s) to satisfy the request.
 
-#### Topologyupdater pod
-
-NFD Topologyupdater can be configured along with the default overlay, all
-deployed as separate pods. The `topologyupdater` overlay may be used along
-with `default` overlay to achieve this:
-
-Deploy the `default` overlay:
-
-```bash
-kubectl apply -k https://github.com/kubernetes-sigs/node-feature-discovery/deployment/overlays/default?ref={{ site.release }}
-```
-
-Deploy the `topologyupdater` overlay:
-
-```bash
-kubectl apply -k https://github.com/kubernetes-sigs/node-feature-discovery/deployment/overlays/master-worker-topologyupdater?ref={{ site.release }}
-```
-
 #### Master Worker Topologyupdater
 
 NFD Master, NFD worker and NFD Topologyupdater can be configured to be deployed
@@ -207,7 +187,8 @@ kubectl apply -k https://github.com/kubernetes-sigs/node-feature-discovery/deplo
 #### Topologyupdater
 
 NFD master and NFD Topologyupdater can be configured to be deployed
-as separate pods. The `topologyupdater` overlay may be used to achieve this:
+as separate pods. The `topologyupdater` overlay may be used to
+achieve this:
 
 ```bash
 kubectl apply -k https://github.com/kubernetes-sigs/node-feature-discovery/deployment/overlays/topologyupdater?ref={{ site.release }}

diff --git a/docs/get-started/introduction.md b/docs/get-started/introduction.md
@@ -45,7 +45,7 @@ NFD-Topology-Updater is a daemon responsible for examining allocated
 resourceson a worker node to account for resources available to be allocated
 to new pod on a per-zone basis (where a zone can be a NUMA node). It then
 communicates the information to nfd-master which does the
-[NodeResourceTopology CR](#nodeResourceTopology-cr) creation corresponding
+[NodeResourceTopology CR](#noderesourcetopology-cr) 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.
 

diff --git a/docs/get-started/quick-start.md b/docs/get-started/quick-start.md
@@ -11,21 +11,20 @@ Minimal steps to deploy latest released version of NFD in your cluster.
 ## Installation
 
 Deploy with kustomize -- creates a new namespace, service and required RBAC
-rules and deploys nfd-master,nfd-worker and nfd-topology-updater daemons.
+rules and deploys nfd-master and nfd-worker daemons.
 
 ```bash
-kubectl apply -k https://github.com/kubernetes-sigs/node-feature-discovery/deployment/overlays/master-worker-topologyupdater?ref={{ site.release }}
+kubectl apply -k https://github.com/kubernetes-sigs/node-feature-discovery/deployment/overlays/default?ref={{ site.release }}
 ```
 
 ## Verify
 
-Wait until NFD master, NFD topologyupdater and NFD worker are running.
+Wait until NFD master and NFD worker are running.
 
 ```bash
 $ kubectl -n node-feature-discovery get ds,deploy
-NAME                                  DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR   AGE
-daemonset.apps/nfd-topology-updater   2         2         2       2            2           <none>          5s
-daemonset.apps/nfd-worker             2         2         2       2            2           <none>          10s
+NAME                         DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR   AGE
+daemonset.apps/nfd-worker    2         2         2       2            2           <none>          10s
 
 NAME                         READY   UP-TO-DATE   AVAILABLE   AGE
 deployment.apps/nfd-master   1/1     1            1           17s
@@ -45,15 +44,6 @@ $ kubectl get no -o json | jq .items[].metadata.labels
 ...
 ```
 
-Check that the NodeResourceTopology CR instances are created
-
-```bash
-$ kubectl get noderesourcetopologies.topology.node.k8s.io
-NAME                 AGE
-kind-control-plane   23s
-kind-worker          23s
-```
-
 ## Use node labels
 
 Create a pod targeting a distinguishing feature (select a valid feature from
@@ -84,6 +74,53 @@ NAME                    READY   STATUS    RESTARTS   AGE   IP          NODE
 feature-dependent-pod   1/1     Running   0          23s   10.36.0.4   node-2   <none>           <none>
 ```
 
+## Additional Optional Installation Steps
+
+In order to deploy nfd-master and nfd-topology-updater daemons
+use `topologyupdater` overlay.
+
+Deploy with kustomize -- creates a new namespace, service and required RBAC
+rules and nfd-master and nfd-topology-updater daemons.
+
+```bash
+kubectl apply -k https://github.com/kubernetes-sigs/node-feature-discovery/deployment/overlays/topologyupdater?ref={{ site.release }}
+```
+
+**NOTE:**
+
+[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 from Kubernetes v1.23, the `GetAllocatableResources` is enabled by default through
+`KubeletPodResourcesGetAllocatable` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/).
+
+
+## Verify
+
+Wait until NFD master and NFD topologyupdater are running.
+
+```bash
+$ kubectl -n node-feature-discovery get ds,deploy
+NAME                                  DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR   AGE
+daemonset.apps/nfd-topology-updater   2         2         2       2            2           <none>          5s
+
+NAME                         READY   UP-TO-DATE   AVAILABLE   AGE
+deployment.apps/nfd-master   1/1     1            1           17s
+
+```
+
+Check that the NodeResourceTopology CR instances are created
+
+```bash
+$ kubectl get noderesourcetopologies.topology.node.k8s.io
+NAME                 AGE
+kind-control-plane   23s
+kind-worker          23s
+```
+
 ## Show the CR instances
 
 ```bash
@@ -142,3 +179,7 @@ resources along with the granularity of those resources at a per-zone level
 (represented by node-0 and node-1 in the above example) or can be used by an
 external entity (e.g. topology-aware scheduler plugin) to take an action based
 on the gathered information.
+
+
+<!-- Links -->
+[podresource-api]: https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/#monitoring-device-plugin-resources