Skip to content

Commit

Permalink
docs: move /run/dbus mount to Docker recommended way (netdata#19645)
Browse files Browse the repository at this point in the history 
* docs: move /run/dbus mount to Docker recommended way

* minor fixes

* typo

* update deploy.yaml
  • Loading branch information
@ilyam8
ilyam8 authored Feb 14, 2025
1 parent fa0b2dd commit 885a51f
Show file tree
Hide file tree
Showing 2 changed files with 33 additions and 53 deletions.
6 changes: 6 additions & 0 deletions integrations/deploy.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -254,6 +254,7 @@
-v /etc/os-release:/host/etc/os-release:ro \
-v /var/log:/host/var/log:ro \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-v /run/dbus:/run/dbus:ro \
--restart unless-stopped \
--cap-add SYS_PTRACE \
--cap-add SYS_ADMIN \
Expand Down Expand Up @@ -281,6 +282,7 @@
-v /etc/os-release:/host/etc/os-release:ro \
-v /var/log:/host/var/log:ro \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-v /run/dbus:/run/dbus:ro \
--restart unless-stopped \
--cap-add SYS_PTRACE \
--cap-add SYS_ADMIN \
Expand Down Expand Up @@ -321,6 +323,7 @@
- /etc/os-release:/host/etc/os-release:ro
- /var/log:/host/var/log:ro
- /var/run/docker.sock:/var/run/docker.sock:ro
- /run/dbus:/run/dbus:ro
{% if $showClaimingOptions %}
environment:
- NETDATA_CLAIM_TOKEN={% claim_token %}
Expand Down Expand Up @@ -359,6 +362,7 @@
- /etc/os-release:/host/etc/os-release:ro
- /var/log:/host/var/log:ro
- /var/run/docker.sock:/var/run/docker.sock:ro
- /run/dbus:/run/dbus:ro
{% if $showClaimingOptions %}
environment:
- NETDATA_CLAIM_TOKEN={% claim_token %}
Expand Down Expand Up @@ -398,6 +402,7 @@
- /etc/hostname:/etc/hostname:ro
- /var/log:/host/var/log:ro
- /var/run/docker.sock:/var/run/docker.sock:ro
- /run/dbus:/run/dbus:ro
{% if $showClaimingOptions %}
environment:
- NETDATA_CLAIM_TOKEN={% claim_token %}
Expand Down Expand Up @@ -439,6 +444,7 @@
- /etc/hostname:/etc/hostname:ro
- /var/log:/host/var/log:ro
- /var/run/docker.sock:/var/run/docker.sock:ro
- /run/dbus:/run/dbus:ro
{% if $showClaimingOptions %}
environment:
- NETDATA_CLAIM_TOKEN={% claim_token %}
Expand Down
80 changes: 27 additions & 53 deletions packaging/docker/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,13 @@ import TabItem from '@theme/TabItem';

## Limitations running the Agent in Docker

We do not officially support running our Docker images with the Docker CLI `--user` option or the Docker Compose
We don’t officially support running our Docker images with the Docker CLI `--user` option or the Docker Compose
`user:` parameter. Such usage will usually still work, but some features will not be available when run this
way. Note that the Agent will drop privileges appropriately inside the container during startup, meaning that even
when run without these options almost nothing in the container will actually run with an effective UID of 0.
when run without these options, almost nothing in the container will actually run with an effective UID of 0.

Our POWER8+ Docker images do not support our FreeIPMI collector. This is a technical limitation in FreeIPMI itself,
and unfortunately not something we can realistically work around.
Our POWER8+ Docker images don’t support our FreeIPMI collector. This is a technical limitation in FreeIPMI itself,
and unfortunately, not something we can realistically work around.

## Create a new Netdata Agent container

Expand All @@ -38,16 +38,18 @@ along with their descriptions.
<details open>
<summary>Mounts</summary>

| Component | Mounts | Description |
|:----------------------:|:--------------------------:|--------------------------------------------------------------------------------------------------------------------------------------------|
| netdata | /etc/os-release | Host info detection. |
| diskspace.plugin | / | Host mount points monitoring. |
| cgroups.plugin | /sys, /var/run/docker.sock | Docker containers monitoring and name resolution. |
| 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. |
| go.d.plugin | /var/log | Web servers logs tailing. See [weblog](https://github.com/netdata/go.d.plugin/tree/master/modules/weblog#readme) collector. |
| apps.plugin | /etc/passwd, /etc/group | Monitoring of host system resource usage by each user and user group. |
| proc.plugin | /proc | Host system monitoring (CPU, memory, network interfaces, disks, etc.). |
| systemd-journal.plugin | /var/log | Viewing, exploring and analyzing systemd journal logs. |
| Component | Mounts | Description |
|:----------------------:|:--------------------------:|--------------------------------------------------------------------------------------------------------------------------------------------------|
| netdata | /etc/os-release | Host info detection. |
| diskspace.plugin | / | Host mount points monitoring. |
| cgroups.plugin | /sys, /var/run/docker.sock | Docker containers monitoring and name resolution. |
| 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. |
| go.d.plugin | /var/log | Web servers logs tailing. See [weblog](https://github.com/netdata/go.d.plugin/tree/master/modules/weblog#readme) collector. |
| apps.plugin | /etc/passwd, /etc/group | Monitoring of host system resource usage by each user and user group. |
| proc.plugin | /proc | Host system monitoring (CPU, memory, network interfaces, disks, etc.). |
| systemd-journal.plugin | /var/log | Viewing, exploring and analyzing systemd journal logs. |
| 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. |
| go.d.plugin | /run/dbus | [go.d/systemdunits](https://github.com/netdata/go.d.plugin/tree/master/modules/systemdunits#readme) |

</details>

Expand Down Expand Up @@ -81,6 +83,7 @@ docker run -d --name=netdata \
-v /etc/os-release:/host/etc/os-release:ro \
-v /var/log:/host/var/log:ro \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-v /run/dbus:/run/dbus:ro \
--restart unless-stopped \
--cap-add SYS_PTRACE \
--cap-add SYS_ADMIN \
Expand Down Expand Up @@ -123,6 +126,7 @@ services:
- /etc/os-release:/host/etc/os-release:ro
- /var/log:/host/var/log:ro
- /var/run/docker.sock:/var/run/docker.sock:ro
- /run/dbus:/run/dbus:ro

volumes:
netdataconfig:
Expand All @@ -135,36 +139,7 @@ volumes:
> :bookmark_tabs: Note
>
> 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.
### With systemd units monitoring
Monitoring systemd units requires mounting `/run/dbus`. This mount is not available on non-systemd systems, so we cannot
use it in the Recommended Way.

Mounting `/run/dbus` provides:

- [go.d/systemdunits](https://github.com/netdata/go.d.plugin/tree/master/modules/systemdunits#readme).
- Systemd-list-units function: information about all systemd units, including their active state, description, whether
they are enabled, and more.

<Tabs>
<TabItem value="docker_run" label="docker run">

<h3> Using the <code>docker run</code> command </h3>

Add `-v /run/dbus:/run/dbus:ro` to your `docker run`.

</TabItem>
<TabItem value="docker compose" label="docker-compose">

<h3> Using the <code>docker-compose</code> command</h3>

Add `- /run/dbus:/run/dbus:ro` to the netdata service `volumes`.

</TabItem>
</Tabs>
> 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.
### With NVIDIA GPUs monitoring
Expand Down Expand Up @@ -205,7 +180,7 @@ Add the following to the netdata service.

Use a [bind mount](https://docs.docker.com/storage/bind-mounts/) for `/etc/netdata` rather than a volume.

This example assumes that you have created `netdataconfig/` in your home directory.
This example assumes that you’ve created `netdataconfig/` in your home directory.

```bash
mkdir netdataconfig
Expand Down Expand Up @@ -483,8 +458,8 @@ other services that require access.
Netdata can be run successfully in a non-root environment, such as [rootless Docker](https://docs.docker.com/engine/security/rootless/).

However, it should be noted that Netdata's data collection capabilities are considerably restricted in rootless Docker
due to its inherent limitations. While Netdata can function in a rootless environment, it cannot access certain
resources that require elevated privileges. The following components do not work:
due to its inherent limitations. While Netdata can function in a rootless environment, it can’t access certain
resources that require elevated privileges. The following components don’t work:

- container network interfaces monitoring (cgroup-network helper)
- disk I/O and file descriptors of applications and processes (apps.plugin)
Expand Down Expand Up @@ -531,8 +506,7 @@ docker run -d --name=netdata \

> :bookmark_tabs: Note
>
> 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.
> 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.

## Docker tags

Expand Down Expand Up @@ -599,12 +573,12 @@ how you created the container.

Alternatively, you can directly use the hostname from the node running the container by mounting `/etc/hostname` from
the host in the container. With `docker run`, this can be done by adding `--volume /etc/hostname:/host/etc/hostname:ro` to
the options. If you are using Docker Compose, you can add an entry to the container's `volumes` section
the options. If you’re using Docker Compose, you can add an entry to the container's `volumes` section
reading `- /etc/hostname:/host/etc/hostname:ro`.

## Adding extra packages at runtime

By default, the official Netdata container images do not include a number of optional runtime dependencies. You
By default, the official Netdata container images don’t include a number of optional runtime dependencies. You
can add these dependencies, or any other APT packages, at runtime by listing them in the environment variable
`NETDATA_EXTRA_DEB_PACKAGES`.

Expand All @@ -622,12 +596,12 @@ You can control how the health checks run by using the environment variable `NET

- If left unset, the health check will attempt to access the `/api/v1/info` endpoint of the Agent.
- If set to the exact value 'cli', the health check script will use `netdatacli ping` to determine if the Agent is
running correctly or not. This is sufficient to ensure that Netdata did not hang during startup, but does not provide
running correctly or not. This is sufficient to ensure that Netdata didn’t hang during startup, but doesn’t provide
a rigorous verification that the daemon is collecting data or is otherwise usable.
- 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
cases, this should start with `http://localhost:19999/` to check the Agent running in the container.

In most cases, the default behavior of checking the `/api/v1/info` endpoint will be sufficient. If you are using a
In most cases, the default behavior of checking the `/api/v1/info` endpoint will be enough. If you’re using a
configuration which disables the web server or restricts access to certain APIs, you will need to use a non-default
configuration for health checks to work.

Expand Down

0 comments on commit 885a51f

Please sign in to comment.