diff options
Diffstat (limited to 'packaging/docker')
| -rw-r--r-- | packaging/docker/Dockerfile | 4 | ||||
| -rw-r--r-- | packaging/docker/README.md | 118 | ||||
| -rwxr-xr-x | packaging/docker/run.sh | 111 |
3 files changed, 171 insertions, 62 deletions
diff --git a/packaging/docker/Dockerfile b/packaging/docker/Dockerfile index 8e7c9a7b1..b12af313d 100644 --- a/packaging/docker/Dockerfile +++ b/packaging/docker/Dockerfile @@ -29,7 +29,7 @@ RUN chmod +x netdata-installer.sh && \ cp -rp /deps/* /usr/local/ && \ /bin/echo -e "INSTALL_TYPE='oci'\nPREBUILT_ARCH='$(uname -m)'" > ./system/.install-type && \ CFLAGS="$(packaging/docker/gen-cflags.sh)" LDFLAGS="-Wl,--gc-sections" ./netdata-installer.sh --dont-wait --dont-start-it --use-system-protobuf \ - ${EXTRA_INSTALL_OPTS} --disable-ebpf --one-time-build --enable-lto "$([ "$RELEASE_CHANNEL" = stable ] && echo --stable-channel)" + ${EXTRA_INSTALL_OPTS} --disable-ebpf --install-no-prefix / "$([ "$RELEASE_CHANNEL" = stable ] && echo --stable-channel)" # files to one directory RUN mkdir -p /app/usr/sbin/ \ @@ -122,7 +122,9 @@ RUN addgroup --gid ${NETDATA_GID} --system "${DOCKER_GRP}" && \ freeipmi.plugin \ go.d.plugin \ perf.plugin \ + ndsudo \ slabinfo.plugin \ + network-viewer.plugin \ systemd-journal.plugin; do \ [ -f "/usr/libexec/netdata/plugins.d/$name" ] && chmod 4755 "/usr/libexec/netdata/plugins.d/$name"; \ done && \ diff --git a/packaging/docker/README.md b/packaging/docker/README.md index 528ef5926..fbe5ba433 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> @@ -161,6 +172,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. @@ -246,7 +294,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](https://github.com/netdata/netdata/blob/master/docs/category-overview-pages/secure-nodes.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 @@ -426,6 +474,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). diff --git a/packaging/docker/run.sh b/packaging/docker/run.sh index 415573320..6ba16d1ce 100755 --- a/packaging/docker/run.sh +++ b/packaging/docker/run.sh @@ -14,38 +14,6 @@ if [ ! -w / ] && [ "${EUID}" -eq 0 ]; then echo >&2 "WARNING: For more information, see https://learn.netdata.cloud/docs/agent/claim#known-issues-on-older-hosts-with-seccomp-enabled" fi -if [ ! "${DISABLE_TELEMETRY:-0}" -eq 0 ] || - [ -n "$DISABLE_TELEMETRY" ] || - [ ! "${DO_NOT_TRACK:-0}" -eq 0 ] || - [ -n "$DO_NOT_TRACK" ]; then - touch /etc/netdata/.opt-out-from-anonymous-statistics -fi - -chmod o+rX / 2>/dev/null || echo "Unable to change permissions without errors." - -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) - -re='^[0-9]+$' -if [[ $BALENA_PGID =~ $re ]]; then - echo "Netdata detected balena-engine.sock" - DOCKER_HOST='/var/run/balena-engine.sock' - PGID="$BALENA_PGID" -elif [[ $DOCKER_PGID =~ $re ]]; then - echo "Netdata detected docker.sock" - DOCKER_HOST="/var/run/docker.sock" - PGID="$DOCKER_PGID" -fi -export PGID -export DOCKER_HOST - -if [ -n "${PGID}" ]; then - echo "Creating docker group ${PGID}" - addgroup --gid "${PGID}" "docker" || echo >&2 "Could not add group docker with ID ${PGID}, its already there probably" - echo "Assign netdata user to docker group ${PGID}" - usermod --append --groups "docker" "${DOCKER_USR}" || echo >&2 "Could not add netdata user to group docker with ID ${PGID}" -fi - # Needed to read Proxmox VMs and (LXC) containers configuration files (name resolution + CPU and memory limits) function add_netdata_to_proxmox_conf_files_group() { group_guid="$(stat -c %g /host/etc/pve 2>/dev/null || true)" @@ -68,10 +36,65 @@ function add_netdata_to_proxmox_conf_files_group() { fi } -if [ -d "/host/etc/pve" ]; then - add_netdata_to_proxmox_conf_files_group || true +if [ ! "${DISABLE_TELEMETRY:-0}" -eq 0 ] || + [ -n "$DISABLE_TELEMETRY" ] || + [ ! "${DO_NOT_TRACK:-0}" -eq 0 ] || + [ -n "$DO_NOT_TRACK" ]; then + touch /etc/netdata/.opt-out-from-anonymous-statistics fi +chmod o+rX / 2>/dev/null || echo "Unable to change permissions without errors." + +if [ "${EUID}" -eq 0 ]; then + if [ -n "${NETDATA_EXTRA_APK_PACKAGES}" ]; then + echo >&2 "WARNING: Netdata’s Docker images have switched from Alpine to Debian as a base platform. Supplementary package support is now handled through the NETDATA_EXTRA_DEB_PACKAGES variable instead of NETDATA_EXTRA_APK_PACKAGES." + echo >&2 "WARNING: The container will still run, but supplementary packages listed in NETDATA_EXTRA_APK_PACKAGES will not be installed." + echo >&2 "WARNING: To remove these messages, either undefine NETDATA_EXTRA_APK_PACKAGES, or define it to an empty string." + fi + + if [ -n "${NETDATA_EXTRA_DEB_PACKAGES}" ]; then + echo "Fetching APT repository metadata." + if ! apt-get update; then + echo "Failed to fetch APT repository metadata." + else + echo "Installing supplementary packages." + export DEBIAN_FRONTEND="noninteractive" + # shellcheck disable=SC2086 + if ! apt-get install -y --no-install-recommends ${NETDATA_EXTRA_DEB_PACKAGES}; then + echo "Failed to install supplementary packages." + fi + fi + fi + + 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) + + re='^[0-9]+$' + if [[ $BALENA_PGID =~ $re ]]; then + echo "Netdata detected balena-engine.sock" + DOCKER_HOST='/var/run/balena-engine.sock' + PGID="$BALENA_PGID" + elif [[ $DOCKER_PGID =~ $re ]]; then + echo "Netdata detected docker.sock" + DOCKER_HOST="/var/run/docker.sock" + PGID="$DOCKER_PGID" + fi + export PGID + export DOCKER_HOST + + if [ -n "${PGID}" ]; then + echo "Creating docker group ${PGID}" + addgroup --gid "${PGID}" "docker" || echo >&2 "Could not add group docker with ID ${PGID}, its already there probably" + echo "Assign netdata user to docker group ${PGID}" + usermod --append --groups "docker" "${DOCKER_USR}" || echo >&2 "Could not add netdata user to group docker with ID ${PGID}" + fi + + if [ -d "/host/etc/pve" ]; then + add_netdata_to_proxmox_conf_files_group || true + fi +else + echo >&2 "WARNING: Entrypoint started as non-root user. This is not officially supported and some features may not be available." +fi if mountpoint -q /etc/netdata; then echo "Copying stock configuration to /etc/netdata" @@ -97,24 +120,4 @@ if [ -n "${NETDATA_CLAIM_URL}" ] && [ -n "${NETDATA_CLAIM_TOKEN}" ] && [ ! -f /v -daemon-not-running fi -if [ -n "${NETDATA_EXTRA_APK_PACKAGES}" ]; then - echo >&2 "WARNING: Netdata’s Docker images have switched from Alpine to Debian as a base platform. Supplementary package support is now handled through the NETDATA_EXTRA_DEB_PACKAGES variable instead of NETDATA_EXTRA_APK_PACKAGES." - echo >&2 "WARNING: The container will still run, but supplementary packages listed in NETDATA_EXTRA_APK_PACKAGES will not be installed." - echo >&2 "WARNING: To remove these messages, either undefine NETDATA_EXTRA_APK_PACKAGES, or define it to an empty string." -fi - -if [ -n "${NETDATA_EXTRA_DEB_PACKAGES}" ]; then - echo "Fetching APT repository metadata." - if ! apt-get update; then - echo "Failed to fetch APT repository metadata." - else - echo "Installing supplementary packages." - export DEBIAN_FRONTEND="noninteractive" - # shellcheck disable=SC2086 - if ! apt-get install -y --no-install-recommends ${NETDATA_EXTRA_DEB_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}" "$@" |