summaryrefslogtreecommitdiffstats
path: root/packaging/docker
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2023-05-08 16:27:04 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2023-05-08 16:27:04 +0000
commita836a244a3d2bdd4da1ee2641e3e957850668cea (patch)
treecb87c75b3677fab7144f868435243f864048a1e6 /packaging/docker
parentAdding upstream version 1.38.1. (diff)
downloadnetdata-a836a244a3d2bdd4da1ee2641e3e957850668cea.tar.xz
netdata-a836a244a3d2bdd4da1ee2641e3e957850668cea.zip
Adding upstream version 1.39.0.upstream/1.39.0
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'packaging/docker')
-rw-r--r--packaging/docker/Dockerfile9
-rw-r--r--packaging/docker/README.md209
-rwxr-xr-xpackaging/docker/run.sh15
3 files changed, 146 insertions, 87 deletions
diff --git a/packaging/docker/Dockerfile b/packaging/docker/Dockerfile
index ce5a0b932..fcd9432b5 100644
--- a/packaging/docker/Dockerfile
+++ b/packaging/docker/Dockerfile
@@ -51,7 +51,9 @@ RUN mkdir -p /app/usr/sbin/ \
mv /usr/sbin/netdatacli /app/usr/sbin/ && \
mv packaging/docker/run.sh /app/usr/sbin/ && \
mv packaging/docker/health.sh /app/usr/sbin/ && \
- cp -rp /deps/* /app/usr/local/ && \
+ mkdir -p /deps/etc && \
+ cp -rp /deps/etc /app/usr/local/etc && \
+ chmod -R o+rX /app && \
chmod +x /app/usr/sbin/run.sh
#####################################################################
@@ -106,6 +108,9 @@ RUN chown -R root:root \
if [ -f /usr/libexec/netdata/plugins.d/freeipmi.plugin ]; then \
chmod 4755 /usr/libexec/netdata/plugins.d/freeipmi.plugin; \
fi && \
+ if [ -f /usr/libexec/netdata/plugins.d/go.d.plugin ] && command -v setcap 1>/dev/null 2>&1; then \
+ setcap "cap_net_raw=eip" /usr/libexec/netdata/plugins.d/go.d.plugin 2>/dev/null; \
+ fi && \
# Group write permissions due to: https://github.com/netdata/netdata/pull/6543
find /var/lib/netdata /var/cache/netdata -type d -exec chmod 0770 {} \; && \
find /var/lib/netdata /var/cache/netdata -type f -exec chmod 0660 {} \; && \
@@ -114,6 +119,8 @@ RUN chown -R root:root \
ENV NETDATA_LISTENER_PORT 19999
EXPOSE $NETDATA_LISTENER_PORT
+ENV NETDATA_EXTRA_APK_PACKAGES=""
+
ENTRYPOINT ["/usr/sbin/run.sh"]
HEALTHCHECK --interval=60s --timeout=10s --retries=3 CMD /usr/sbin/health.sh
diff --git a/packaging/docker/README.md b/packaging/docker/README.md
index aec5723e3..ef7dd6de7 100644
--- a/packaging/docker/README.md
+++ b/packaging/docker/README.md
@@ -1,26 +1,16 @@
<!--
title: "Install Netdata with Docker"
-date: "2020-04-23"
custom_edit_url: "https://github.com/netdata/netdata/edit/master/packaging/docker/README.md"
-sidebar_label: "Install Netdata with Docker"
+sidebar_label: "Docker"
learn_status: "Published"
-learn_topic_type: "Tasks"
-learn_rel_path: "Installation"
+learn_rel_path: "Installation/Installation methods"
+sidebar_position: 40
-->
-# Install the Netdata Agent with Docker
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
-Running the Netdata Agent in a container works best for an internal network or to quickly analyze a host. Docker helps
-you get set up quickly, and doesn't install anything permanent on the system, which makes uninstalling the Agent easy.
-
-See our full list of Docker images at [Docker Hub](https://hub.docker.com/r/netdata/netdata).
-
-Starting with v1.30, Netdata collects anonymous usage information by default and sends it to a self-hosted PostHog instance within the Netdata infrastructure. Read
-about the information collected, and learn how to-opt, on our [anonymous statistics](https://github.com/netdata/netdata/blob/master/docs/anonymous-statistics.md)
-page.
-
-The usage statistics are _vital_ for us, as we use them to discover bugs and prioritize new features. We thank you for
-_actively_ contributing to Netdata's future.
+# Install Netdata with Docker
## Limitations running the Agent in Docker
@@ -41,22 +31,7 @@ and unfortunately not something we can realistically work around.
## Create a new Netdata Agent container
-> **Notice**: all `docker run` commands and `docker-compose` configurations explicitly set the `nofile` limit. This is
-> required on some distros until [14177](https://github.com/netdata/netdata/issues/14177) is resolved. Failure to do so
-> may cause a task running in a container to hang and consume 100% of the CPU core.
-
-<details>
-<summary>What are these "some distros"?</summary>
-
-If `LimitNOFILE=infinity` results in an open file limit of 1073741816:
-
-```bash
-[fedora37 ~]$ docker run --rm busybox grep open /proc/self/limits
-Max open files 1073741816 1073741816 files
-```
-</details>
-
-You can create a new Agent container using either `docker run` or Docker Compose. After using either method, you can
+You can create a new Agent container using either `docker run` or `docker-compose`. After using either method, you can
visit the Agent dashboard `http://NODE:19999`.
Both methods create a [bind mount](https://docs.docker.com/storage/bind-mounts/) for Netdata's configuration files
@@ -64,7 +39,12 @@ _within the container_ at `/etc/netdata`. See the [configuration section](#confi
you want to access the configuration files from your _host_ machine, see [host-editable
configuration](#host-editable-configuration).
-**`docker run`**: Use the `docker run` command, along with the following options, to start a new container.
+<Tabs>
+<TabItem value="docker_run" label="docker run">
+
+<h3> Using the <code>docker run</code> command </h3>
+
+Run the following command along with the following options on your terminal, to start a new container.
```bash
docker run -d --name=netdata \
@@ -80,48 +60,65 @@ docker run -d --name=netdata \
--restart unless-stopped \
--cap-add SYS_PTRACE \
--security-opt apparmor=unconfined \
- --ulimit nofile=4096 \
netdata/netdata
```
-**Docker Compose**: Copy the following code and paste into a new file called `docker-compose.yml`, then run
-`docker-compose up -d` in the same directory as the `docker-compose.yml` file to start the container.
-
-```yaml
-version: '3'
-services:
- netdata:
- image: netdata/netdata
- container_name: netdata
- hostname: example.com # set to fqdn of host
- ports:
- - 19999:19999
- restart: unless-stopped
- cap_add:
- - SYS_PTRACE
- security_opt:
- - apparmor:unconfined
- ulimits:
- nofile:
- soft: 4096
- volumes:
- - netdataconfig:/etc/netdata
- - netdatalib:/var/lib/netdata
- - netdatacache:/var/cache/netdata
- - /etc/passwd:/host/etc/passwd:ro
- - /etc/group:/host/etc/group:ro
- - /proc:/host/proc:ro
- - /sys:/host/sys:ro
- - /etc/os-release:/host/etc/os-release:ro
-
-volumes:
- netdataconfig:
- netdatalib:
- netdatacache:
-```
+> ### 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 tab.
+
+</TabItem>
+<TabItem value="docker compose" label="docker-compose">
+
+<h3> Using the <code>docker-compose</code> command</h3>
+
+#### Steps
+
+1. Copy the following code and paste into a new file called `docker-compose.yml`
+
+ ```yaml
+ version: '3'
+ services:
+ netdata:
+ image: netdata/netdata
+ container_name: netdata
+ hostname: example.com # set to fqdn of host
+ ports:
+ - 19999:19999
+ restart: unless-stopped
+ cap_add:
+ - SYS_PTRACE
+ security_opt:
+ - apparmor:unconfined
+ volumes:
+ - netdataconfig:/etc/netdata
+ - netdatalib:/var/lib/netdata
+ - netdatacache:/var/cache/netdata
+ - /etc/passwd:/host/etc/passwd:ro
+ - /etc/group:/host/etc/group:ro
+ - /proc:/host/proc:ro
+ - /sys:/host/sys:ro
+ - /etc/os-release:/host/etc/os-release:ro
+
+ volumes:
+ netdataconfig:
+ netdatalib:
+ netdatacache:
+ ```
+
+2. Run `docker-compose up -d` in the same directory as the `docker-compose.yml` file to start the container.
+
+> :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.
+
+</TabItem>
+</Tabs>
## Docker tags
+See our full list of Docker images at [Docker Hub](https://hub.docker.com/r/netdata/netdata).
+
The official `netdata/netdata` Docker image provides the following named tags:
* `stable`: The `stable` tag will always point to the most recently published stable build.
@@ -136,6 +133,20 @@ Additionally, for each stable release, three tags are pushed, one with the full
that would match that tag (for example, if `v1.30.1` were to be published, the `v1.30` tag would be updated to
point to that instead of `v1.30.0`).
+## Adding extra packages at runtime
+
+By default, the official Netdata container images do not include a number of optional runtime dependencies. You
+can add these dependencies, or any other APK packages, at runtime by listing them in the environment variable
+`NETDATA_EXTRA_APK_PACKAGES`.
+
+Commonly useful packages include:
+
+- `apcupsd`: For monitoring APC UPS devices.
+- `libvirt-daemon`: For resolving cgroup names for libvirt domains.
+- `lm-sensors`: For monitoring hardware sensors.
+- `msmtp`: For email alert support.
+- `netcat-openbsd`: For IRC alert support.
+
## Health Checks
Our Docker image provides integrated support for health checks through the standard Docker interfaces.
@@ -176,7 +187,9 @@ to restart the container: `docker restart netdata`.
### Host-editable configuration
-> **Warning**: [edit-config](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory) script doesn't work when executed on
+> :warning: Warning
+>
+> The [edit-config](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory) script doesn't work when executed on
> the host system.
If you want to make your container's configuration directory accessible from the host system, you need to use a
@@ -208,7 +221,6 @@ docker run -d --name=netdata \
--restart unless-stopped \
--cap-add SYS_PTRACE \
--security-opt apparmor=unconfined \
- --ulimit nofile=4096 \
netdata/netdata
```
@@ -230,9 +242,6 @@ services:
- SYS_PTRACE
security_opt:
- apparmor:unconfined
- ulimits:
- nofile:
- soft: 4096
volumes:
- ./netdataconfig/netdata:/etc/netdata:ro
- netdatalib:/var/lib/netdata
@@ -322,17 +331,17 @@ your machine from within the container. Please read the following carefully.
#### Docker socket proxy (safest option)
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) so that it restricts connections to read-only access to the CONTAINERS
+[HAProxy](https://github.com/netdata/netdata/blob/master/docs/Running-behind-haproxy.md) or
+[CetusGuard](https://github.com/hectorm/cetusguard) so that it restricts connections to read-only access to the `/containers`
endpoint.
The reason it's safer to expose the socket to the proxy is because Netdata has a TCP port exposed outside the Docker
network. Access to the proxy container is limited to only within the network.
-Below is [an example repository (and image)](https://github.com/Tecnativa/docker-socket-proxy) that provides a proxy to
-the socket.
+Here are two examples, the first using [a Docker image based on HAProxy](https://github.com/Tecnativa/docker-socket-proxy)
+and the second using [CetusGuard](https://github.com/hectorm/cetusguard).
-You run the Docker 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.
+##### Docker Socket Proxy (HAProxy)
```yaml
version: '3'
@@ -347,17 +356,46 @@ services:
proxy:
image: tecnativa/docker-socket-proxy
volumes:
- - /var/run/docker.sock:/var/run/docker.sock:ro
+ - /var/run/docker.sock:/var/run/docker.sock:ro
environment:
- CONTAINERS=1
-
```
**Note:** Replace `2375` with the port of your proxy.
+##### CetusGuard
+
+```yaml
+version: '3'
+services:
+ netdata:
+ image: netdata/netdata
+ # ... rest of your config ...
+ ports:
+ - 19999:19999
+ environment:
+ - DOCKER_HOST=cetusguard:2375
+ cetusguard:
+ image: hectorm/cetusguard:v1
+ read_only: true
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock:ro
+ environment:
+ CETUSGUARD_BACKEND_ADDR: unix:///var/run/docker.sock
+ CETUSGUARD_FRONTEND_ADDR: tcp://:2375
+ CETUSGUARD_RULES: |
+ ! Inspect a container
+ GET %API_PREFIX_CONTAINERS%/%CONTAINER_ID_OR_NAME%/json
+```
+
+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.
+
#### Giving group access to the Docker socket (less safe)
+> :warning: Caution
+>
> You should seriously consider the necessity of activating this option, as it grants to the `netdata`
-user access to the privileged socket connection of docker service and therefore your whole machine.
+> user access to the privileged socket connection of docker service and therefore your whole machine.
If you want to have your container names resolved by Netdata, make the `netdata` user be part of the group that owns the
socket.
@@ -386,6 +424,8 @@ grep docker /etc/group | cut -d ':' -f 3
#### Running as root (unsafe)
+> :warning: Caution
+>
> You should seriously consider the necessity of activating this option, as it grants to the `netdata` user access to
> the privileged socket connection of docker service, and therefore your whole machine.
@@ -495,9 +535,6 @@ services:
- SYS_PTRACE
security_opt:
- apparmor:unconfined
- ulimits:
- nofile:
- soft: 4096
volumes:
- netdatalib:/var/lib/netdata
- netdatacache:/var/cache/netdata
@@ -520,4 +557,4 @@ Caddyfile.
## Publish a test image to your own repository
At Netdata, we provide multiple ways of testing your Docker images using your own repositories.
-You may either use the command line tools available or take advantage of our GitHub Acions infrastructure.
+You may either use the command line tools available or take advantage of our GitHub Actions infrastructure.
diff --git a/packaging/docker/run.sh b/packaging/docker/run.sh
index 9029e22b6..ed77c394a 100755
--- a/packaging/docker/run.sh
+++ b/packaging/docker/run.sh
@@ -21,6 +21,8 @@ if [ ! "${DISABLE_TELEMETRY:-0}" -eq 0 ] ||
touch /etc/netdata/.opt-out-from-anonymous-statistics
fi
+chmod o+rX / # Needed to fix permissions issues in some cases.
+
BALENA_PGID=$(stat -c %g /var/run/balena.sock 2>/dev/null || true)
DOCKER_PGID=$(stat -c %g /var/run/docker.sock 2>/dev/null || true)
@@ -67,4 +69,17 @@ if [ -n "${NETDATA_CLAIM_URL}" ] && [ -n "${NETDATA_CLAIM_TOKEN}" ] && [ ! -f /v
-daemon-not-running
fi
+if [ -n "${NETDATA_EXTRA_APK_PACKAGES}" ]; then
+ echo "Fetching APK repository metadata."
+ if ! apk update; then
+ echo "Failed to fetch APK repository metadata."
+ else
+ echo "Installing supplementary packages."
+ # shellcheck disable=SC2086
+ if ! apk add --no-cache ${NETDATA_EXTRA_APK_PACKAGES}; then
+ echo "Failed to install supplementary packages."
+ fi
+ fi
+fi
+
exec /usr/sbin/netdata -u "${DOCKER_USR}" -D -s /host -p "${NETDATA_LISTENER_PORT}" "$@"