Add documentation for topology garbage collector

Signed-off-by: PiotrProkop <[email protected]>
kubernetes-sigs · Jan 11, 2023 · 3143faf · 3143faf
1 parent 59afae5
commit 3143faf
Show file tree

Hide file tree

Showing 7 changed files with 105 additions and 3 deletions.
diff --git a/docs/deployment/helm.md b/docs/deployment/helm.md
@@ -173,5 +173,24 @@ We have introduced the following Chart parameters.
 | `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)                                                                                                                                |
 
+### Topology garbage collector parameters
+
+| Name                                          | Type   | Default | description                                                                                                                                                                                           |
+|-----------------------------------------------|--------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `topologyGC.*`                                | dict   |         | NFD Topology Garbage Collector configuration                                                                                                                                                          |
+| `topologyGC.enable`                           | bool   | true    | Specifies whether the NFD Topology Garbage Collector should be created                                                                                                                                |
+| `topologyGC.serviceAccount.create`            | bool   | true    | Specifies whether the service account for topology garbage collector should be created                                                                                                                |
+| `topologyGC.serviceAccount.annotations`       | dict   | {}      | Annotations to add to the service account for topology garbage collector                                                                                                                              |
+| `topologyGC.serviceAccount.name`              | string |         | The name of the service account for topology garbage collector to use. If not set and create is true, a name is generated using the fullname template and `-topology-gc` suffix                       |
+| `topologyGC.rbac.create`                      | bool   | false   | Specifies whether to create [RBAC][rbac] configuration for topology garbage collector                                                                                                                 |
+| `topologyGC.interval`                         | string | 1h      | Time between periodic garbage collector runs                                                                                                                                                          |
+| `topologyGC.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 |
+| `topologyGC.securityContext`                  | dict   | {}      | Container [security settings](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-container)                                                    |
+| `topologyGC.resources`                        | dict   | {}      | Topology garbage collector pod [resources management](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/)                                                                 |
+| `topologyGC.nodeSelector`                     | dict   | {}      | Topology garbage collector pod [node selector](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector)                                                                 |
+| `topologyGC.tolerations`                      | dict   | {}      | Topology garbage collector pod [node tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/)                                                                      |
+| `topologyGC.annotations`                      | dict   | {}      | Topology garbage collector pod [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/)                                                                          |
+| `topologyGC.affinity`                         | dict   | {}      | Topology garbage collector pod [affinity](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes-using-node-affinity/)                                                            |
+
 <!-- Links -->
 [rbac]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/
diff --git a/docs/get-started/introduction.md b/docs/get-started/introduction.md
@@ -47,6 +47,14 @@ creates or updates a
 resource object specific to this node. One instance of nfd-topology-updater is
 supposed to be running on each node of the cluster.
 
+## NFD-Topology-Garbage-Collector
+
+NFD-Topology-Garbage-Collector is a daemon responsible for cleaning obsolete
+[NodeResourceTopology](../usage/custom-resources#noderesourcetopology) objects,
+obsolete means that there is no corresponding worker node.
+
+One instance of nfd-topology-gc is supposed to be running in the cluster.
+
 ## Feature Discovery
 
 Feature discovery is divided into domain-specific feature sources:

diff --git a/docs/reference/topology-gc-commandline-reference.md b/docs/reference/topology-gc-commandline-reference.md
@@ -0,0 +1,46 @@
+---
+title: "Topology Garbage Collector Cmdline Reference"
+layout: default
+sort: 6
+---
+
+# NFD-Topology-Garbage-Collector Commandline Flags
+
+{: .no_toc }
+
+## Table of Contents
+
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+To quickly view available command line flags execute `nfd-topology-gc -help`.
+In a docker container:
+
+```bash
+docker run {{ site.container_image }} \
+nfd-topology-gc -help
+```
+
+### -h, -help
+
+Print usage and exit.
+
+### -version
+
+Print version and exit.
+
+### -gc-interval
+
+The `-gc-interval` specifies the interval between periodic garbage collector runs.
+
+Default: 1h
+
+Example:
+
+```bash
+nfd-topology-gc -gc-interval=1h
+```
diff --git a/docs/usage/custom-resources.md b/docs/usage/custom-resources.md
@@ -1,7 +1,7 @@
 ---
 title: "CRDs"
 layout: default
-sort: 6
+sort: 7
 ---
 
 # Custom Resources

diff --git a/docs/usage/customization-guide.md b/docs/usage/customization-guide.md
@@ -1,7 +1,7 @@
 ---
 title: "Customization guide"
 layout: default
-sort: 7
+sort: 8
 ---
 
 # Customization guide

diff --git a/docs/usage/examples-and-demos.md b/docs/usage/examples-and-demos.md
@@ -1,7 +1,7 @@
 ---
 title: "Examples and demos"
 layout: default
-sort: 8
+sort: 9
 ---
 
 # Examples and demos

diff --git a/docs/usage/nfd-topology-gc.md b/docs/usage/nfd-topology-gc.md
@@ -0,0 +1,29 @@
+---
+title: "NFD-Topology-Garbage-Collector"
+layout: default
+sort: 6
+---
+
+# NFD-Topology-Garbage-Collector
+{: .no_toc}
+
+---
+
+NFD-Topology-Garbage-Collector is preferably run as a Kubernetes deployment
+with one replica. It makes sure that all
+[NodeResourceTopology](custom-resources#noderesourcetopology)
+have corresponding worker nodes and removes stale objects for worker nodes
+which are no longer part of Kubernetes cluster.
+
+This service watches for Node deletion events and removes NodeResourceTopology
+objects upon them. It is also running periodically to make sure no event was
+missed or NodeResourceTopology object was created without corresponding worker
+node. The default garbage collector interval is set to 1h which is the value
+when no -gc-interval is specified.
+
+## Topology-Garbage-Collector Configuration
+
+In Helm deployments,
+(see [Topology Garbage Collector](../deployment/helm.md#topology-garbage-collector-parameters)
+for parameters). NFD-Topology-Garbage-Collector will only be deployed when
+topologyUpdater.enable is set to true.