From b921791549cc5f41381d96427037efbb49220d04 Mon Sep 17 00:00:00 2001 From: Talor Itzhak Date: Wed, 9 Nov 2022 19:25:58 +0200 Subject: [PATCH] docs: update docs Update the docs with explanations and examples about the exclude-list feature. Signed-off-by: Talor Itzhak --- docs/deployment/helm.md | 43 ++++++++++--------- .../topology-updater-commandline-reference.md | 16 ++++++- ...opology-updater-configuration-reference.md | 41 ++++++++++++++++++ docs/usage/nfd-topology-updater.md | 36 +++++++++++++++- docs/usage/nfd-worker.md | 2 +- 5 files changed, 114 insertions(+), 24 deletions(-) create mode 100644 docs/reference/topology-updater-configuration-reference.md diff --git a/docs/deployment/helm.md b/docs/deployment/helm.md index 0cd5842448..824f3c72bf 100644 --- a/docs/deployment/helm.md +++ b/docs/deployment/helm.md @@ -142,24 +142,25 @@ We have introduced the following Chart parameters. ### Topology updater parameters -| Name | Type | Default | description | -|-----------------------------------------------|--------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `topologyUpdater.*` | dict | | NFD Topology Updater configuration | -| `topologyUpdater.enable` | bool | false | Specifies whether the NFD Topology Updater should be created | -| `topologyUpdater.createCRDs` | bool | false | Specifies whether the NFD Topology Updater CRDs should be created | -| `topologyUpdater.serviceAccount.create` | bool | true | Specifies whether the service account for topology updater should be created | -| `topologyUpdater.serviceAccount.annotations` | dict | {} | Annotations to add to the service account for topology updater | -| `topologyUpdater.serviceAccount.name` | string | | The name of the service account for topology updater to use. If not set and create is true, a name is generated using the fullname template and `-topology-updater` suffix | -| `topologyUpdater.rbac` | dict | | RBAC [parameters](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) for the topology updater | -| `topologyUpdater.rbac.create` | bool | false | Specifies whether the cluster role and binding for topology updater should be created | -| `topologyUpdater.kubeletConfigPath` | string | "" | Specifies the kubelet config host path | -| `topologyUpdater.kubeletPodResourcesSockPath` | string | "" | Specifies the kubelet sock path to read pod resources | -| `topologyUpdater.updateInterval` | string | 60s | Time to sleep between CR updates. Non-positive value implies no CR update. | -| `topologyUpdater.watchNamespace` | string | `*` | Namespace to watch pods, `*` for all namespaces | -| `topologyUpdater.podSecurityContext` | dict | {} | [PodSecurityContext](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod) holds pod-level security attributes and common container settings | -| `topologyUpdater.securityContext` | dict | {} | Container [security settings](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-container) | -| `topologyUpdater.resources` | dict | {} | Topology updater pod [resources management](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) | -| `topologyUpdater.nodeSelector` | dict | {} | Topology updater pod [node selector](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) | -| `topologyUpdater.tolerations` | dict | {} | Topology updater pod [node tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) | -| `topologyUpdater.annotations` | dict | {} | Topology updater pod [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) | -| `topologyUpdater.affinity` | dict | {} | Topology updater pod [affinity](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes-using-node-affinity/) | +| Name | Type | Default | description | +|-----------------------------------------------|--------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `topologyUpdater.*` | dict | | NFD Topology Updater configuration | +| `topologyUpdater.enable` | bool | false | Specifies whether the NFD Topology Updater should be created | +| `topologyUpdater.createCRDs` | bool | false | Specifies whether the NFD Topology Updater CRDs should be created | +| `topologyUpdater.serviceAccount.create` | bool | true | Specifies whether the service account for topology updater should be created | +| `topologyUpdater.serviceAccount.annotations` | dict | {} | Annotations to add to the service account for topology updater | +| `topologyUpdater.serviceAccount.name` | string | | The name of the service account for topology updater to use. If not set and create is true, a name is generated using the fullname template and `-topology-updater` suffix | +| `topologyUpdater.rbac` | dict | | RBAC [parameters](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) for the topology updater | +| `topologyUpdater.rbac.create` | bool | false | Specifies whether the cluster role and binding for topology updater should be created | +| `topologyUpdater.kubeletConfigPath` | string | "" | Specifies the kubelet config host path | +| `topologyUpdater.kubeletPodResourcesSockPath` | string | "" | Specifies the kubelet sock path to read pod resources | +| `topologyUpdater.updateInterval` | string | 60s | Time to sleep between CR updates. Non-positive value implies no CR update. | +| `topologyUpdater.watchNamespace` | string | `*` | Namespace to watch pods, `*` for all namespaces | +| `topologyUpdater.podSecurityContext` | dict | {} | [PodSecurityContext](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod) holds pod-level security attributes and common container settings | +| `topologyUpdater.securityContext` | dict | {} | Container [security settings](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-container) | +| `topologyUpdater.resources` | dict | {} | Topology updater pod [resources management](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) | +| `topologyUpdater.nodeSelector` | dict | {} | Topology updater pod [node selector](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) | +| `topologyUpdater.tolerations` | dict | {} | Topology updater pod [node tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) | +| `topologyUpdater.annotations` | dict | {} | Topology updater pod [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) | +| `topologyUpdater.affinity` | dict | {} | Topology updater pod [affinity](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes-using-node-affinity/) | +| `topologyUpdater.config` | dict | | [configuration](../reference/topology-updater-configuration-reference) | diff --git a/docs/reference/topology-updater-commandline-reference.md b/docs/reference/topology-updater-commandline-reference.md index 742d36c66d..197d950421 100644 --- a/docs/reference/topology-updater-commandline-reference.md +++ b/docs/reference/topology-updater-commandline-reference.md @@ -21,7 +21,8 @@ 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 {{ site.container_image }} \ +nfd-topology-updater -help ``` ### -h, -help @@ -32,6 +33,19 @@ Print usage and exit. Print version and exit. +### -config + +The `-config` flag specifies the path of the nfd-topology-updater +configuration file to use. + +Default: /etc/kubernetes/node-feature-discovery/nfd-topology-updater.conf + +Example: + +```bash +nfd-topology-updater -config=/opt/nfd/nfd-topology-updater.conf +``` + ### -server The `-server` flag specifies the address of the nfd-master endpoint where to diff --git a/docs/reference/topology-updater-configuration-reference.md b/docs/reference/topology-updater-configuration-reference.md new file mode 100644 index 0000000000..1752dc8532 --- /dev/null +++ b/docs/reference/topology-updater-configuration-reference.md @@ -0,0 +1,41 @@ +--- +title: "Topology-Updater config reference" +layout: default +sort: 5 +--- + +# Configuration file reference of nfd-topology-updater +{: .no_toc} + +## Table of contents +{: .no_toc .text-delta} + +1. TOC +{:toc} + +--- + +See the +[sample configuration file](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{site.release}}/deployment/components/topology-updater-config/nfd-topology-updater.conf.example) +for a full example configuration. + +## excludeList + +The `excludeList` specifies a key-value map of allocated resources +that should not be examined by the topology-updater +agent per node. +Each key is a node name with a value as a list of resources +that should not be examined by the agent for that specific node. + +### excludeList.* +`excludeList.*` is a special value that use to specify all nodes. +A resource that would be listed under this key, would be excluded from all nodes. + +Default: *empty* + +Example: + +```yaml +excludeList: + '*': [hugepages-2Mi] +``` diff --git a/docs/usage/nfd-topology-updater.md b/docs/usage/nfd-topology-updater.md index fab56715c1..d1654f2b56 100644 --- a/docs/usage/nfd-topology-updater.md +++ b/docs/usage/nfd-topology-updater.md @@ -20,5 +20,39 @@ When run as a daemonset, nodes are re-examined for the allocated resources (to determine the information of the allocatable resources on a per zone basis where a zone can be a NUMA node) at an interval specified using the [`-sleep-interval`](../reference/topology-updater-commandline-reference.html#-sleep-interval) -option. The default sleep interval is set to 60s which is the the value when no +option. The default sleep interval is set to 60s which is the value when no -sleep-interval is specified. +In addition, it can avoid examining specific allocated resources +given a configuration of resources to exclude via [`-excludeList`](../reference/topology-updater-configuration-reference.md#excludelist) + +## Topology-Updater Configuration + +NFD-Topology-Updater supports configuration through a configuration file. The +default location is `/etc/kubernetes/node-feature-discovery/topology-updater.conf`, +but, this can be changed by specifying the`-config` command line flag. +unlike nfd-worker, dynamic updates are not supported ATM + +Topology-Updater configuration file is read inside the container, and thus, Volumes and +VolumeMounts are needed to make your configuration available for NFD. The +preferred method is to use a ConfigMap which provides easy deployment and +re-configurability. + +The provided nfd-topology-updater deployment templates create an empty configmap and +mount it inside the nfd-topology-updater containers. In kustomize deployments, +configuration can be edited with: + +```bash +kubectl -n ${NFD_NS} edit configmap nfd-topology-updater-conf +``` + +In Helm deployments, +[Topology Updater parameters](../deployment/helm.md#topology-updater-parameters) +`toplogyUpdater.config` can be used to edit the respective configuration. + +See +[nfd-topology-updater configuration file reference](../reference/topology-updater-configuration-reference.md) +for more details. +The (empty-by-default) +[example config](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{site.release}}/deployment/components/topology-updater-config/nfd-topology-updater.conf.example) +contains all available configuration options and can be used as a reference +for creating a configuration. \ No newline at end of file diff --git a/docs/usage/nfd-worker.md b/docs/usage/nfd-worker.md index 6a22eb330d..4a662dbf7c 100644 --- a/docs/usage/nfd-worker.md +++ b/docs/usage/nfd-worker.md @@ -62,7 +62,7 @@ for more details. The (empty-by-default) [example config](https://github.com/kubernetes-sigs/node-feature-discovery/blob/{{site.release}}/deployment/components/worker-config/nfd-worker.conf.example) contains all available configuration options and can be used as a reference -for creating creating a configuration. +for creating a configuration. 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