diff options
Diffstat (limited to 'packaging/docker/README.md')
| -rw-r--r-- | packaging/docker/README.md | 209 |
1 files changed, 123 insertions, 86 deletions
diff --git a/packaging/docker/README.md b/packaging/docker/README.md index aec5723e..ef7dd6de 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. |