diff --git a/docs/advanced/topology-updater-commandline-reference.md b/docs/advanced/topology-updater-commandline-reference.md index fe449ea83a..6f64776308 100644 --- 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,7 +34,7 @@ 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 @@ -42,63 +42,63 @@ 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,12 +122,12 @@ 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* @@ -135,12 +135,12 @@ 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,12 +166,12 @@ 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 @@ -179,12 +179,12 @@ 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 index 506135cdcd..27907a80f6 100644 --- 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 index 5c95ff3d12..755e9a2250 100644 --- 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 index 7ce8eacb47..50ddbf69bc 100644 --- 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 5s -daemonset.apps/nfd-worker 2 2 2 2 2 10s +NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE +daemonset.apps/nfd-worker 2 2 2 2 2 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 ``` +## 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 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. + + + +[podresource-api]: https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/#monitoring-device-plugin-resources