[kubernetes] Add hostmetrics recevier doc (#3118)

content/en/docs/kubernetes/collector/components.md

@@ -2,7 +2,7 @@
 title: Important Components for Kubernetes
 linkTitle: Components
 # prettier-ignore
-cSpell:ignore: alertmanagers containerd crio filelog gotime horizontalpodautoscalers iostream k8sattributes kubelet kubeletstats logtag replicasets replicationcontrollers resourcequotas statefulsets varlibdockercontainers varlogpods
+cSpell:ignore: alertmanagers containerd crio filelog gotime horizontalpodautoscalers hostfs hostmetrics iostream k8sattributes kubelet kubeletstats logtag replicasets replicationcontrollers resourcequotas statefulsets varlibdockercontainers varlogpods
 ---
 
 The [OpenTelemetry Collector](/docs/collector/) supports many different
@@ -24,6 +24,8 @@ Components covered in this page:
   such as events, from the Kubernetes API server.
 - [Prometheus Receiver](#prometheus-receiver): receives metrics in
   [Prometheus](https://prometheus.io/) format.
+- [Host Metrics Receiver](#host-metrics-receiver): scrapes host metrics from
+  Kubernetes nodes.
 
 For application traces, metrics, or logs, we recommend the
 [OTLP receiver](https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver),
@@ -708,3 +710,94 @@ to tell a collector which Prometheus endpoints it should scrape.
 
 For more information on the design of the receiver, see
 [Design](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/prometheusreceiver/DESIGN.md).
+
+## Host Metrics Receiver
+
+| Deployment Pattern   | Usable                                                         |
+| -------------------- | -------------------------------------------------------------- |
+| DaemonSet (Agent)    | Preferred                                                      |
+| Deployment (Gateway) | Yes, but only collects metrics from the node it is deployed on |
+| Sidecar              | No                                                             |
+
+The Host Metrics Receiver collects metrics from a host using a variety of
+scrapers. There is some overlap with the
+[Kubeletstats Receiver](#kubeletstats-receiver) so if you decide to use both, it
+may be worth it to disable these duplicate metrics.
+
+In Kubernetes, the receiver needs access to the `hostfs` volume to work
+properly. If you're using the
+[OpenTelemetry Collector Helm chart](../../helm/collector/) you can use the
+[`hostMetrics` preset](../../helm/collector/#host-metrics-preset) to get
+started.
+
+The available scrapers are:
+
+| Scraper    | Supported OSs       | Description                                            |
+| ---------- | ------------------- | ------------------------------------------------------ |
+| cpu        | All except Mac[^1]  | CPU utilization metrics                                |
+| disk       | All except Mac[^1]  | Disk I/O metrics                                       |
+| load       | All                 | CPU load metrics                                       |
+| filesystem | All                 | File System utilization metrics                        |
+| memory     | All                 | Memory utilization metrics                             |
+| network    | All                 | Network interface I/O metrics & TCP connection metrics |
+| paging     | All                 | Paging/Swap space utilization and I/O metrics          |
+| processes  | Linux, Mac          | Process count metrics                                  |
+| process    | Linux, Windows, Mac | Per process CPU, Memory, and Disk I/O metrics          |
+
+[^1]:
+    Not supported on Mac when compiled without cgo, which is the default for the
+    images released by the Collector SIG.
+
+For specific details about which metrics are collected and specific
+configuration details, see
+[Host Metrics Receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver).
+
+If you need to configure the component yourself, make sure to mount the `hostfs`
+volume if you want to collect the node's metrics and not the container's.
+
+```yaml
+---
+apiVersion: apps/v1
+kind: DaemonSet
+...
+spec:
+  ...
+  template:
+    ...
+    spec:
+      ...
+      containers:
+        - name: opentelemetry-collector
+          ...
+          volumeMounts:
+            ...
+            - name: hostfs
+              mountPath: /hostfs
+              readOnly: true
+              mountPropagation: HostToContainer
+      volumes:
+        ...
+        - name: hostfs
+          hostPath:
+            path: /
+      ...
+```
+
+and then configure the Host Metrics Receiver to use the `volumeMount`:
+
+```yaml
+receivers:
+  hostmetrics:
+    root_path: /hostfs
+    collection_interval: 10s
+    scrapers:
+      cpu:
+      load:
+      memory:
+      disk:
+      filesystem:
+      network:
+```
+
+For more details about using the receiver in a container, see
+[Collecting host metrics from inside a container (Linux only)](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver#collecting-host-metrics-from-inside-a-container-linux-only)