diff options
Diffstat (limited to 'packaging/docker/README.md')
| -rw-r--r-- | packaging/docker/README.md | 138 |
1 files changed, 127 insertions, 11 deletions
diff --git a/packaging/docker/README.md b/packaging/docker/README.md index 528ef5926..204e17ad1 100644 --- a/packaging/docker/README.md +++ b/packaging/docker/README.md @@ -12,6 +12,16 @@ import TabItem from '@theme/TabItem'; # Install Netdata with Docker +## 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 +`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. + +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. + ## Create a new Netdata Agent container You can create a new Agent container using either `docker run` or `docker-compose`. After using any method, you can @@ -24,12 +34,13 @@ along with their descriptions. <details open> <summary>Privileges</summary> -| Component | Privileges | Description | -|:---------------:|:-----------------------------:|--------------------------------------------------------------------------------------------------------------------------| -| cgroups.plugin | host PID mode, SYS_ADMIN | Container network interfaces monitoring. Map virtual interfaces in the system namespace to interfaces inside containers. | -| proc.plugin | host network mode | Host system networking stack monitoring. | -| go.d.plugin | host network mode | Monitoring applications running on the host and inside containers. | -| local-listeners | host network mode, SYS_PTRACE | Discovering local services/applications. Map open (listening) ports to running services/applications. | +| Component | Privileges | Description | +|:---------------------:|:-----------------------------:|--------------------------------------------------------------------------------------------------------------------------| +| cgroups.plugin | host PID mode, SYS_ADMIN | Container network interfaces monitoring. Map virtual interfaces in the system namespace to interfaces inside containers. | +| proc.plugin | host network mode | Host system networking stack monitoring. | +| go.d.plugin | host network mode | Monitoring applications running on the host and inside containers. | +| local-listeners | host network mode, SYS_PTRACE | Discovering local services/applications. Map open (listening) ports to running services/applications. | +| network-viewer.plugin | host network mode, SYS_ADMIN | Discovering all current network sockets and building a network-map. | </details> @@ -39,6 +50,7 @@ along with their descriptions. | 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. | @@ -69,6 +81,7 @@ docker run -d --name=netdata \ -v netdataconfig:/etc/netdata \ -v netdatalib:/var/lib/netdata \ -v netdatacache:/var/cache/netdata \ + -v /:/host/root:ro,rslave \ -v /etc/passwd:/host/etc/passwd:ro \ -v /etc/group:/host/etc/group:ro \ -v /etc/localtime:/etc/localtime:ro \ @@ -110,6 +123,7 @@ services: - netdataconfig:/etc/netdata - netdatalib:/var/lib/netdata - netdatacache:/var/cache/netdata + - /:/host/root:ro,rslave - /etc/passwd:/host/etc/passwd:ro - /etc/group:/host/etc/group:ro - /etc/localtime:/etc/localtime:ro @@ -161,6 +175,43 @@ Add `- /run/dbus:/run/dbus:ro` to the netdata service `volumes`. </TabItem> </Tabs> +### With NVIDIA GPUs monitoring + + +Monitoring NVIDIA GPUs requires: + +- Using official [NVIDIA driver](https://www.nvidia.com/Download/index.aspx). +- Installing [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html). +- Allowing the Netdata container to access GPU resources. + + +<Tabs> +<TabItem value="docker_run" label="docker run"> + +<h3> Using the <code>docker run</code> command </h3> + +Add `--gpus 'all,capabilities=utility'` to your `docker run`. + +</TabItem> +<TabItem value="docker compose" label="docker-compose"> + +<h3> Using the <code>docker-compose</code> command</h3> + +Add the following to the netdata service. + +```yaml + deploy: + resources: + reservations: + devices: + - driver: nvidia + count: all + capabilities: [gpu] +``` + +</TabItem> +</Tabs> + ### With host-editable configuration Use a [bind mount](https://docs.docker.com/storage/bind-mounts/) for `/etc/netdata` rather than a volume. @@ -185,6 +236,7 @@ docker run -d --name=netdata \ -v $(pwd)/netdataconfig/netdata:/etc/netdata \ -v netdatalib:/var/lib/netdata \ -v netdatacache:/var/cache/netdata \ + -v /:/host/root:ro,rslave \ -v /etc/passwd:/host/etc/passwd:ro \ -v /etc/group:/host/etc/group:ro \ -v /etc/localtime:/etc/localtime:ro \ @@ -226,6 +278,7 @@ services: - ./netdataconfig/netdata:/etc/netdata - netdatalib:/var/lib/netdata - netdatacache:/var/cache/netdata + - /:/host/root:ro,rslave - /etc/passwd:/host/etc/passwd:ro - /etc/group:/host/etc/group:ro - /etc/localtime:/etc/localtime:ro @@ -246,7 +299,7 @@ volumes: ### With SSL/TLS enabled HTTP Proxy For a permanent installation on a public server, you -should [secure the Netdata instance](https://github.com/netdata/netdata/blob/master/docs/netdata-security.md). This +should [secure the Netdata instance](/docs/netdata-agent/securing-netdata-agents.md). This section contains an example of how to install Netdata with an SSL reverse proxy and basic authentication. You can use the following `docker-compose.yml` and Caddyfile files to run Netdata with Docker. Replace the domains and @@ -260,7 +313,7 @@ executed internally by the caddy server. ```caddyfile netdata.example.org { - reverse_proxy netdata:19999 + reverse_proxy host.docker.internal:19999 tls admin@example.org } ``` @@ -270,11 +323,15 @@ netdata.example.org { After setting Caddyfile run this with `docker-compose up -d` to have a fully functioning Netdata setup behind an HTTP reverse proxy. +Make sure Netdata bind to docker0 interface if you've custom `web.bind to` setting in `netdata.conf`. + ```yaml version: '3' services: caddy: image: caddy:2 + extra_hosts: + - "host.docker.internal:host-gateway" # To access netdata running with "network_mode: host". ports: - "80:80" - "443:443" @@ -285,9 +342,9 @@ services: netdata: image: netdata/netdata container_name: netdata - hostname: example.com # set to fqdn of host - restart: always pid: host + network_mode: host + restart: unless-stopped cap_add: - SYS_PTRACE - SYS_ADMIN @@ -297,6 +354,7 @@ services: - netdataconfig:/etc/netdata - netdatalib:/var/lib/netdata - netdatacache:/var/cache/netdata + - /:/host/root:ro,rslave - /etc/passwd:/host/etc/passwd:ro - /etc/group:/host/etc/group:ro - /etc/localtime:/etc/localtime:ro @@ -321,7 +379,7 @@ to Caddyfile. ### With Docker socket proxy Deploy a Docker socket proxy that accepts and filters out requests using something like -[HAProxy](https://github.com/netdata/netdata/blob/master/docs/Running-behind-haproxy.md) or +[HAProxy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-haproxy.md) or [CetusGuard](https://github.com/hectorm/cetusguard) so that it restricts connections to read-only access to the `/containers` endpoint. @@ -348,6 +406,7 @@ services: - netdataconfig:/etc/netdata - netdatalib:/var/lib/netdata - netdatacache:/var/cache/netdata + - /:/host/root:ro,rslave - /etc/passwd:/host/etc/passwd:ro - /etc/group:/host/etc/group:ro - /etc/localtime:/etc/localtime:ro @@ -395,6 +454,7 @@ services: - netdataconfig:/etc/netdata - netdatalib:/var/lib/netdata - netdatacache:/var/cache/netdata + - /:/host/root:ro,rslave - /etc/passwd:/host/etc/passwd:ro - /etc/group:/host/etc/group:ro - /etc/localtime:/etc/localtime:ro @@ -426,6 +486,62 @@ volumes: You can run the socket proxy in its own Docker Compose file and leave it on a private network that you can add to other services that require access. +### Rootless mode + +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: + +- container network interfaces monitoring (cgroup-network helper) +- disk I/O and file descriptors of applications and processes (apps.plugin) +- debugfs.plugin +- freeipmi.plugin +- perf.plugin +- slabinfo.plugin +- systemd-journal.plugin + +This method creates a [volume](https://docs.docker.com/storage/volumes/) for Netdata's configuration files +_within the container_ at `/etc/netdata`. +See the [configure section](#configure-agent-containers) for details. If you want to access the configuration files from +your _host_ machine, see [host-editable configuration](#with-host-editable-configuration). + +<Tabs> +<TabItem value="docker_run" label="docker run"> + +<h3> Using the <code>docker run</code> command </h3> + +Run the following command in your terminal to start a new container. + +```bash +docker run -d --name=netdata \ + --hostname=$(hostname) \ + -p 19999:19999 \ + -v netdataconfig:/etc/netdata \ + -v netdatalib:/var/lib/netdata \ + -v netdatacache:/var/cache/netdata \ + -v /etc/passwd:/host/etc/passwd:ro \ + -v /etc/group:/host/etc/group:ro \ + -v /etc/localtime:/etc/localtime:ro \ + -v /proc:/host/proc:ro \ + -v /sys:/host/sys:ro \ + -v /etc/os-release:/host/etc/os-release:ro \ + -v /run/user/$UID/docker.sock:/var/run/docker.sock:ro \ + --restart unless-stopped \ + --security-opt apparmor=unconfined \ + netdata/netdata +``` + +</TabItem> + +</Tabs> + +> :bookmark_tabs: Note +> +> If you plan to Claim 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 See our full list of Docker images at [Docker Hub](https://hub.docker.com/r/netdata/netdata). |