docs: move /run/dbus mount to Docker recommended way (#19645)
* docs: move /run/dbus mount to Docker recommended way * minor fixes * typo * update deploy.yaml
Ilya Mashchenko committed
Feb 14, 2025 at 11:04 UTC
885a51fc143563d3e89c8078aebd759805d7806f
2 files changed
+33
-53
integrations/deploy.yaml
+6
@@ -254,6 +254,7 @@
254
-v /etc/os-release:/host/etc/os-release:ro \
255
-v /var/log:/host/var/log:ro \
256
-v /var/run/docker.sock:/var/run/docker.sock:ro \
257
+ -v /run/dbus:/run/dbus:ro \
258
--restart unless-stopped \
259
--cap-add SYS_PTRACE \
260
--cap-add SYS_ADMIN \
@@ -281,6 +282,7 @@
282
-v /etc/os-release:/host/etc/os-release:ro \
283
-v /var/log:/host/var/log:ro \
284
-v /var/run/docker.sock:/var/run/docker.sock:ro \
285
+ -v /run/dbus:/run/dbus:ro \
286
--restart unless-stopped \
287
--cap-add SYS_PTRACE \
288
--cap-add SYS_ADMIN \
@@ -321,6 +323,7 @@
323
- /etc/os-release:/host/etc/os-release:ro
324
- /var/log:/host/var/log:ro
325
- /var/run/docker.sock:/var/run/docker.sock:ro
326
+ - /run/dbus:/run/dbus:ro
327
{% if $showClaimingOptions %}
328
environment:
329
- NETDATA_CLAIM_TOKEN={% claim_token %}
@@ -359,6 +362,7 @@
362
- /etc/os-release:/host/etc/os-release:ro
363
- /var/log:/host/var/log:ro
364
- /var/run/docker.sock:/var/run/docker.sock:ro
365
+ - /run/dbus:/run/dbus:ro
366
{% if $showClaimingOptions %}
367
environment:
368
- NETDATA_CLAIM_TOKEN={% claim_token %}
@@ -398,6 +402,7 @@
402
- /etc/hostname:/etc/hostname:ro
403
- /var/log:/host/var/log:ro
404
- /var/run/docker.sock:/var/run/docker.sock:ro
405
+ - /run/dbus:/run/dbus:ro
406
{% if $showClaimingOptions %}
407
environment:
408
- NETDATA_CLAIM_TOKEN={% claim_token %}
@@ -439,6 +444,7 @@
444
- /etc/hostname:/etc/hostname:ro
445
- /var/log:/host/var/log:ro
446
- /var/run/docker.sock:/var/run/docker.sock:ro
447
+ - /run/dbus:/run/dbus:ro
448
{% if $showClaimingOptions %}
449
environment:
450
- NETDATA_CLAIM_TOKEN={% claim_token %}
packaging/docker/README.md
+27
-53
@@ -5,13 +5,13 @@ import TabItem from '@theme/TabItem';
5
6
## Limitations running the Agent in Docker
7
8
-We do not officially support running our Docker images with the Docker CLI `--user` option or the Docker Compose
8
+We don’t officially support running our Docker images with the Docker CLI `--user` option or the Docker Compose
9
`user:` parameter. Such usage will usually still work, but some features will not be available when run this
10
way. Note that the Agent will drop privileges appropriately inside the container during startup, meaning that even
11
-when run without these options almost nothing in the container will actually run with an effective UID of 0.
11
+when run without these options, almost nothing in the container will actually run with an effective UID of 0.
12
13
-Our POWER8+ Docker images do not support our FreeIPMI collector. This is a technical limitation in FreeIPMI itself,
14
-and unfortunately not something we can realistically work around.
13
+Our POWER8+ Docker images don’t support our FreeIPMI collector. This is a technical limitation in FreeIPMI itself,
14
+and unfortunately, not something we can realistically work around.
15
16
## Create a new Netdata Agent container
17
@@ -38,16 +38,18 @@ along with their descriptions.
38
<details open>
39
<summary>Mounts</summary>
40
41
-| Component | Mounts | Description |
42
-|:----------------------:|:--------------------------:|--------------------------------------------------------------------------------------------------------------------------------------------|
43
-| netdata | /etc/os-release | Host info detection. |
44
-| diskspace.plugin | / | Host mount points monitoring. |
45
-| cgroups.plugin | /sys, /var/run/docker.sock | Docker containers monitoring and name resolution. |
46
-| go.d.plugin | /var/run/docker.sock | Docker Engine and containers monitoring. See [docker](https://github.com/netdata/go.d.plugin/tree/master/modules/docker#readme) collector. |
47
-| go.d.plugin | /var/log | Web servers logs tailing. See [weblog](https://github.com/netdata/go.d.plugin/tree/master/modules/weblog#readme) collector. |
48
-| apps.plugin | /etc/passwd, /etc/group | Monitoring of host system resource usage by each user and user group. |
49
-| proc.plugin | /proc | Host system monitoring (CPU, memory, network interfaces, disks, etc.). |
50
-| systemd-journal.plugin | /var/log | Viewing, exploring and analyzing systemd journal logs. |
41
+| Component | Mounts | Description |
42
+|:----------------------:|:--------------------------:|--------------------------------------------------------------------------------------------------------------------------------------------------|
43
+| netdata | /etc/os-release | Host info detection. |
44
+| diskspace.plugin | / | Host mount points monitoring. |
45
+| cgroups.plugin | /sys, /var/run/docker.sock | Docker containers monitoring and name resolution. |
46
+| go.d.plugin | /var/run/docker.sock | Docker Engine and containers monitoring. See [docker](https://github.com/netdata/go.d.plugin/tree/master/modules/docker#readme) collector. |
47
+| go.d.plugin | /var/log | Web servers logs tailing. See [weblog](https://github.com/netdata/go.d.plugin/tree/master/modules/weblog#readme) collector. |
48
+| apps.plugin | /etc/passwd, /etc/group | Monitoring of host system resource usage by each user and user group. |
49
+| proc.plugin | /proc | Host system monitoring (CPU, memory, network interfaces, disks, etc.). |
50
+| systemd-journal.plugin | /var/log | Viewing, exploring and analyzing systemd journal logs. |
51
+| systemd-journal.plugin | /run/dbus | Systemd-list-units function: information about all systemd units, including their active state, description, whether they are enabled, and more. |
52
+| go.d.plugin | /run/dbus | [go.d/systemdunits](https://github.com/netdata/go.d.plugin/tree/master/modules/systemdunits#readme) |
53
54
</details>
55
@@ -81,6 +83,7 @@ docker run -d --name=netdata \
83
-v /etc/os-release:/host/etc/os-release:ro \
84
-v /var/log:/host/var/log:ro \
85
-v /var/run/docker.sock:/var/run/docker.sock:ro \
86
+ -v /run/dbus:/run/dbus:ro \
87
--restart unless-stopped \
88
--cap-add SYS_PTRACE \
89
--cap-add SYS_ADMIN \
@@ -123,6 +126,7 @@ services:
126
- /etc/os-release:/host/etc/os-release:ro
127
- /var/log:/host/var/log:ro
128
- /var/run/docker.sock:/var/run/docker.sock:ro
129
+ - /run/dbus:/run/dbus:ro
130
131
volumes:
132
netdataconfig:
@@ -135,36 +139,7 @@ volumes:
139
140
> :bookmark_tabs: Note
141
>
138
-> If you plan to connect the node to Netdata Cloud, you can find the command with the right parameters by clicking the "
139
-> Add Nodes" button in your Space's "Nodes" view.
140
-
141
-### With systemd units monitoring
142
-
143
-Monitoring systemd units requires mounting `/run/dbus`. This mount is not available on non-systemd systems, so we cannot
144
-use it in the Recommended Way.
145
-
146
-Mounting `/run/dbus` provides:
147
-
148
-- [go.d/systemdunits](https://github.com/netdata/go.d.plugin/tree/master/modules/systemdunits#readme).
149
-- Systemd-list-units function: information about all systemd units, including their active state, description, whether
150
- they are enabled, and more.
151
-
152
-<Tabs>
153
-<TabItem value="docker_run" label="docker run">
154
-
155
-<h3> Using the <code>docker run</code> command </h3>
156
-
157
-Add `-v /run/dbus:/run/dbus:ro` to your `docker run`.
158
-
159
-</TabItem>
160
-<TabItem value="docker compose" label="docker-compose">
161
-
162
-<h3> Using the <code>docker-compose</code> command</h3>
163
-
164
-Add `- /run/dbus:/run/dbus:ro` to the netdata service `volumes`.
165
-
166
-</TabItem>
167
-</Tabs>
142
+> If you plan to connect the node to Netdata Cloud, you can find the command with the right parameters by clicking the "Add Nodes" button in your Space's "Nodes" view.
143
144
### With NVIDIA GPUs monitoring
145
@@ -205,7 +180,7 @@ Add the following to the netdata service.
180
181
Use a [bind mount](https://docs.docker.com/storage/bind-mounts/) for `/etc/netdata` rather than a volume.
182
208
-This example assumes that you have created `netdataconfig/` in your home directory.
183
+This example assumes that you’ve created `netdataconfig/` in your home directory.
184
185
```bash
186
mkdir netdataconfig
@@ -483,8 +458,8 @@ other services that require access.
458
Netdata can be run successfully in a non-root environment, such as [rootless Docker](https://docs.docker.com/engine/security/rootless/).
459
460
However, it should be noted that Netdata's data collection capabilities are considerably restricted in rootless Docker
486
-due to its inherent limitations. While Netdata can function in a rootless environment, it cannot access certain
487
-resources that require elevated privileges. The following components do not work:
461
+due to its inherent limitations. While Netdata can function in a rootless environment, it can’t access certain
462
+resources that require elevated privileges. The following components don’t work:
463
464
- container network interfaces monitoring (cgroup-network helper)
465
- disk I/O and file descriptors of applications and processes (apps.plugin)
@@ -531,8 +506,7 @@ docker run -d --name=netdata \
506
507
> :bookmark_tabs: Note
508
>
534
-> If you plan to connect the node to Netdata Cloud, you can find the command with the right parameters by clicking the "
535
-> Add Nodes" button in your Space's "Nodes" view.
509
+> If you plan to connect the node to Netdata Cloud, you can find the command with the right parameters by clicking the "Add Nodes" button in your Space's "Nodes" view.
510
511
## Docker tags
512
@@ -599,12 +573,12 @@ how you created the container.
573
574
Alternatively, you can directly use the hostname from the node running the container by mounting `/etc/hostname` from
575
the host in the container. With `docker run`, this can be done by adding `--volume /etc/hostname:/host/etc/hostname:ro` to
602
-the options. If you are using Docker Compose, you can add an entry to the container's `volumes` section
576
+the options. If you’re using Docker Compose, you can add an entry to the container's `volumes` section
577
reading `- /etc/hostname:/host/etc/hostname:ro`.
578
579
## Adding extra packages at runtime
580
607
-By default, the official Netdata container images do not include a number of optional runtime dependencies. You
581
+By default, the official Netdata container images don’t include a number of optional runtime dependencies. You
582
can add these dependencies, or any other APT packages, at runtime by listing them in the environment variable
583
`NETDATA_EXTRA_DEB_PACKAGES`.
584
@@ -622,12 +596,12 @@ You can control how the health checks run by using the environment variable `NET
596
597
- If left unset, the health check will attempt to access the `/api/v1/info` endpoint of the Agent.
598
- If set to the exact value 'cli', the health check script will use `netdatacli ping` to determine if the Agent is
625
- running correctly or not. This is sufficient to ensure that Netdata did not hang during startup, but does not provide
599
+ running correctly or not. This is sufficient to ensure that Netdata didn’t hang during startup, but doesn’t provide
600
a rigorous verification that the daemon is collecting data or is otherwise usable.
601
- If set to anything else, the health check will treat the value as a URL to check for a 200 status code on. In most
602
cases, this should start with `http://localhost:19999/` to check the Agent running in the container.
603
630
-In most cases, the default behavior of checking the `/api/v1/info` endpoint will be sufficient. If you are using a
604
+In most cases, the default behavior of checking the `/api/v1/info` endpoint will be enough. If you’re using a
605
configuration which disables the web server or restricts access to certain APIs, you will need to use a non-default
606
configuration for health checks to work.
607