From a6643d7aefcb87706a2f66be8bade76edc1f639d Mon Sep 17 00:00:00 2001 From: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> Date: Tue, 17 Feb 2026 15:28:47 +0200 Subject: [PATCH] docs: Update prometheus.exporter.cadvisor to add information about permissions (#5009) This PR adds information about how to set permissions to run Alloy in local, Docker and K8s. It was compared against the related Issues, and compared against advice give in the Alloy forums. Fixes: * https://github.com/grafana/alloy/issues/990 * https://github.com/grafana/alloy/issues/3482 --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Piotr <17101802+thampiotr@users.noreply.github.com> (cherry picked from commit 4f096f5066ee714d9a1b8b5a5e3ec974268c499a) --- .../prometheus.exporter.cadvisor.md | 244 +++++++++++++++++- 1 file changed, 240 insertions(+), 4 deletions(-) diff --git a/docs/sources/reference/components/prometheus/prometheus.exporter.cadvisor.md b/docs/sources/reference/components/prometheus/prometheus.exporter.cadvisor.md index db00987befc..c416ada3ebf 100644 --- a/docs/sources/reference/components/prometheus/prometheus.exporter.cadvisor.md +++ b/docs/sources/reference/components/prometheus/prometheus.exporter.cadvisor.md @@ -2,7 +2,7 @@ canonical: https://grafana.com/docs/alloy/latest/reference/components/prometheus/prometheus.exporter.cadvisor/ aliases: - ../prometheus.exporter.cadvisor/ # /docs/alloy/latest/reference/components/prometheus.exporter.cadvisor/ -description: Learn about the prometheus.exporter.cadvisor +description: Learn about prometheus.exporter.cadvisor labels: stage: general-availability products: @@ -12,10 +12,102 @@ title: prometheus.exporter.cadvisor # `prometheus.exporter.cadvisor` -The `prometheus.exporter.cadvisor` component collects container metrics using [cAdvisor](https://github.com/google/cadvisor). +The `prometheus.exporter.cadvisor` component collects container metrics with [cAdvisor](https://github.com/google/cadvisor). {{< docs/shared lookup="reference/components/exporter-clustering-warning.md" source="alloy" version="" >}} +{{< admonition type="note" >}} +The `prometheus.exporter.cadvisor` component only works on Linux systems. +On other operating systems, {{< param "PRODUCT_NAME" >}} writes a warning to the logs and the component doesn't collect container metrics. +{{< /admonition >}} + +The component requires specific permissions and configuration depending on your deployment environment. + +{{< tabs >}} +{{< tab-content name="Linux binary" >}} + +When you run {{< param "PRODUCT_NAME" >}} as a Linux binary, systemd service, or with the [non-root][nonroot] `alloy` user, you must grant the `alloy` user permissions to access the container runtime socket and related directories to collect metrics from containers on the host. + +The component works with Docker, `containerd`, Container Runtime Interface for OpenShift (CRI-O), and systemd container runtimes. + +For Docker, grant permissions using one of these approaches: + +- **Add to docker group (recommended)**: Add the `alloy` user to the `docker` group: + + ```bash + sudo usermod -aG docker alloy + ``` + + Then restart the {{< param "PRODUCT_NAME" >}} service: + + ```bash + sudo systemctl restart alloy + ``` + + {{< admonition type="note" >}} + The `docker` group grants privileges equivalent to the `root` user. + For more information about the security implications, refer to [Docker security](https://docs.docker.com/engine/security/#docker-daemon-attack-surface). + {{< /admonition >}} + +- **Using ACLs**: Grant the `alloy` user read and execute permissions to `/var/lib/docker/`: + + ```bash + sudo setfacl -R -m d:u:alloy:rx /var/lib/docker/ + sudo setfacl -R -m u:alloy:rx /var/lib/docker/ + ``` + + {{< admonition type="note" >}} + You must rerun these commands when adding containers, as they don't automatically apply to newly created directories. + {{< /admonition >}} + +- **Running as root**: Modify the systemd service to run {{< param "PRODUCT_NAME" >}} as root: + + ```bash + sudo systemctl edit alloy.service + ``` + + Add the following override: + + ```ini + [Service] + User=root + ``` + + {{< admonition type="caution" >}} + Running {{< param "PRODUCT_NAME" >}} as root has security implications. + Only use this approach if necessary for your environment. + {{< /admonition >}} + +For more information about running {{< param "PRODUCT_NAME" >}} without root privileges, refer to [Configure {{< param "PRODUCT_NAME" >}} to run as a nonroot user][nonroot]. + +[nonroot]: ../../../configure/nonroot/ + +{{< /tab-content >}} +{{< tab-content name="Kubernetes" >}} + +When you run {{< param "PRODUCT_NAME" >}} in Kubernetes to collect container metrics, deploy {{< param "PRODUCT_NAME" >}} as a DaemonSet to collect metrics from each node. + +The DaemonSet requires: + +* **Host network access**: To access the container runtime +* **Volume mounts**: Access to the container runtime socket and system directories +* **Security context**: Privileged access or specific capabilities + +For detailed Kubernetes Deployment guidance, refer to the [Kubernetes Deployment example](#kubernetes-deployment-example) section. + +{{< /tab-content >}} +{{< tab-content name="Docker container" >}} + +When you run {{< param "PRODUCT_NAME" >}} itself as a Docker container to monitor other containers on the host, the {{< param "PRODUCT_NAME" >}} container requires: + +* **Privileged mode**: Access to host resources +* **Volume mounts**: Access to the container runtime socket and system directories + +For a complete Docker container deployment example, refer to the [Docker deployment example](#docker-deployment-example) section. + +{{< /tab-content >}} +{{< /tabs >}} + ## Usage ```alloy @@ -52,7 +144,7 @@ For `allowlisted_container_labels` to take effect, `store_container_labels` must `env_metadata_allowlist` is only supported for containerd and Docker runtimes. -If `perf_events_config` is not set, measurement of `perf` events is disabled. +If `perf_events_config` isn't set, measurement of `perf` events is disabled. A `resctrl_interval` of `0` disables updating mon groups. @@ -123,7 +215,9 @@ In those cases, exported fields retain their last healthy values. `prometheus.exporter.cadvisor` doesn't expose any component-specific debug metrics. -## Example +## Examples + +### Component configuration This example uses a [`prometheus.scrape` component][scrape] to collect metrics from `prometheus.exporter.cadvisor`: @@ -160,6 +254,148 @@ Replace the following: [scrape]: ../prometheus.scrape/ +### Docker deployment example + +To collect container metrics with {{< param "PRODUCT_NAME" >}} in Docker, you must mount the necessary host directories and run the container in privileged mode. + +{{< admonition type="note" >}} +The `prometheus.exporter.cadvisor` component only works when the {{< param "PRODUCT_NAME" >}} container runs on a Linux Docker host. +Docker Desktop for Mac and Docker Desktop for Windows run containers in a Linux VM, which prevents direct host monitoring. +{{< /admonition >}} + +The following Docker Compose example shows the required configuration: + +```yaml +services: + alloy: + image: grafana/alloy:latest + privileged: true + ports: + - "12345:12345" + volumes: + - ./config.alloy:/etc/alloy/config.alloy + - /var/run/docker.sock:/var/run/docker.sock + - /:/rootfs:ro + - /var/run:/var/run:rw + - /sys:/sys:ro + - /var/lib/docker/:/var/lib/docker:ro + - /dev/disk/:/dev/disk:ro + command: run --server.http.listen-addr=0.0.0.0:12345 --storage.path=/var/lib/alloy/data /etc/alloy/config.alloy +``` + +The required volume mounts are: + +* `/var/run/docker.sock`: Docker socket for container discovery and API access +* `/`: Host root filesystem (read-only) for system metrics +* `/var/run`: Host runtime data (read-write) for accessing container state +* `/sys`: Host system information (read-only) for cgroup and device metrics +* `/var/lib/docker/`: Docker storage directory (read-only) for container metadata and layer information +* `/dev/disk/`: Disk device information (read-only) for disk I/O metrics + +{{< admonition type="caution" >}} +Running in privileged mode grants the container access to all host devices. +Only use privileged mode when necessary and ensure proper network isolation. +{{< /admonition >}} + +For a complete working example with Grafana and Prometheus, refer to the [alloy-scenarios repository][alloy-scenarios]. + +[alloy-scenarios]: https://github.com/grafana/alloy-scenarios/tree/main/docker-monitoring + +### Kubernetes Deployment example + +When you run {{< param "PRODUCT_NAME" >}} in Kubernetes, deploy it as a DaemonSet to collect container metrics from each node. + +The following example shows the required configuration for a DaemonSet: + +```yaml +apiVersion: apps/v1 +kind: DaemonSet +metadata: + name: alloy + namespace: monitoring +spec: + selector: + matchLabels: + app: alloy + template: + metadata: + labels: + app: alloy + spec: + serviceAccountName: alloy + hostNetwork: true + hostPID: true + containers: + - name: alloy + image: grafana/alloy:latest + args: + - run + - /etc/alloy/config.alloy + - --server.http.listen-addr=0.0.0.0:12345 + - --storage.path=/var/lib/alloy/data + ports: + - containerPort: 12345 + name: http-metrics + securityContext: + privileged: true + volumeMounts: + - name: config + mountPath: /etc/alloy + - name: rootfs + mountPath: /rootfs + readOnly: true + - name: var-run + mountPath: /var/run + - name: sys + mountPath: /sys + readOnly: true + - name: docker + mountPath: /var/lib/docker + readOnly: true + - name: dev-disk + mountPath: /dev/disk + readOnly: true + volumes: + - name: config + configMap: + name: alloy-config + - name: rootfs + hostPath: + path: / + - name: var-run + hostPath: + path: /var/run + - name: sys + hostPath: + path: /sys + - name: docker + hostPath: + path: /var/lib/docker + - name: dev-disk + hostPath: + path: /dev/disk +``` + +Key configuration requirements: + +* **hostNetwork: true**: Allows access to the host network stack +* **hostPID: true**: Enables process-level metrics collection +* **privileged: true**: Grants access to host resources +* **Volume mounts**: Provide access to container runtime and system directories + +{{< admonition type="note" >}} +For container runtimes other than Docker, such as `containerd` or CRI-O, adjust the volume mounts and `docker_host` or `containerd_host` arguments accordingly. +{{< /admonition >}} + +{{< admonition type="caution" >}} +Running containers with privileged access in Kubernetes has security implications. +Consider using Pod Security Standards and RBAC to limit exposure, and only deploy to dedicated monitoring namespaces. +{{< /admonition >}} + +For more information about deploying {{< param "PRODUCT_NAME" >}} on Kubernetes, refer to [Deploy {{< param "FULL_PRODUCT_NAME" >}}][deploy]. + +[deploy]: ../../../set-up/deploy/ + ## Compatible components