From 20972db44d560f82c2c52c0ae6861b8441cb3a07 Mon Sep 17 00:00:00 2001 From: Yonas Habteab Date: Mon, 21 Jul 2025 09:14:37 +0200 Subject: [PATCH] docs: Add `For-Container.md` --- doc/02-installation.md.d/For-Container.md | 179 ++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 doc/02-installation.md.d/For-Container.md diff --git a/doc/02-installation.md.d/For-Container.md b/doc/02-installation.md.d/For-Container.md new file mode 100644 index 000000000..06967a712 --- /dev/null +++ b/doc/02-installation.md.d/For-Container.md @@ -0,0 +1,179 @@ +# Installing Icinga 2 in Containers + +To be able to run Icinga 2 in a containerized environment, you'll need to set up a few things. +This guide will help you get started with running Icinga 2 in a container using our official images. + +## Prerequisites + +- A container runtime such as [Docker](https://www.docker.com) or [Podman](https://podman.io) installed on your system. +- Basic knowledge of how to use Docker or Podman commands. +- A basic understanding of Icinga 2 and its configuration. + +## Getting Started + +First, create a dedicated docker network for Icinga 2 to ensure that all containers can communicate with each other: + +``` +docker network create icinga +``` + +Next, start an Icinga 2 master container using the official Icinga 2 image. By default, all Icinga 2 containers will +listen on port `5665` from within the docker network, but you can expose this port on a different port on your host +system if needed. The following command will start an Icinga 2 master container with the necessary configurations: + +``` +docker run --rm --detach \ + --network icinga \ + --name icinga-master \ + --hostname icinga-master \ + --publish 5665:5665 \ + --volume icinga-master:/data \ + --env ICINGA_MASTER=1 \ + icinga/icinga2 +``` + +This command will run the Icinga 2 master container in detached mode, exposing port 5665 for communication and mounting +the `/data` directory to a persistent volume named `icinga-master`. You can adjust the volume name and other parameters +as needed. You can also set additional environment variables to configure the Icinga 2 instance, +see [Environment Variables](#environment-variables) for a list of available options. + +Alternatively, if you're used to using the `icinga2 node wizard` command to set up Icinga 2 nodes, you can still run +the `icinga2 node wizard` command to set up the containers interactively. + +``` +docker run --rm -it --hostname icinga-master --volume icinga-master:/data icinga/icinga2 icinga2 node wizard +``` + +This command will run the Icinga 2 master container in interactive mode, allowing you to answer the prompts from the +`icinga2 node wizard` command. + +Another option is to mount all the necessary configuration files from your host system into the container. +This way, you can use your existing Icinga 2 configuration files without needing any additional setup steps. +By default, the container will be populated with the default Icinga 2 configuration files, but you can override +them by creating bind mounts from your host system to the respective directories in the container. For example, to +replace the default `constants.conf` file with your own one, you can start the Icinga 2 master container with the +following command: + +``` +docker run --rm -d \ + --network icinga \ + --name icinga-master \ + --hostname icinga-master \ + --publish 5665:5665 \ + --volume icinga-master:/data \ + --mount=type=bind,source=/absolute/path/to/your/constants.conf,target=/data/etc/icinga2/constants.conf \ + --env ICINGA_MASTER=1 \ + icinga/icinga2 +``` + +!!! info + + If you [mount an empty](https://docs.docker.com/engine/storage/bind-mounts/#mount-into-a-non-empty-directory-on-the-container) + directory from your host into the container’s `/data` directory using `--volume /path/to/empty-directory:/data`, + all files in `/data` inside the container will be obscured. The container may not start correctly because its + important files are no longer visible. This happens because Docker replaces the container's `/data` directory with + your empty host directory. To avoid this, either use `--mount` to bind only specific files or subdirectories, or + use `--volume` with a named volume (like `icinga-master:/data`) so the container's default files are preserved and + only your specified files are replaced. + +## Adding Icinga 2 Agents + +To add Icinga 2 agents to your setup, you can run additional containers for each agent. In order your agents be able +to successfully connect to the master, they need to have a copy of the master's `ca.crt` file created during the master +setup. You can first copy this file from the master container to your host system using the following command: + +``` +docker cp icinga-master:/var/lib/icinga2/certs/ca.crt icinga-ca.crt +``` + +If you didn't use `icinga-master` as the name of your master container, replace it with the actual name you used. +For easier setup, you may want to also obtain a `ticket` from the master container, which will allow the agent to +authenticate itself without needing you to manually sign a certificate signing request (CSR). + +You can create a ticket for the agent by running the following command on your host system: + +``` +docker exec icinga-master icinga2 pki ticket --cn icinga-agent > icinga-agent.ticket +``` + +Again, replace `icinga-master` with the actual name of your master container if necessary. Additionally, you may want +to adjust the `--cn` parameter to match the hostname of your agent containers. For non-ticket based setups, the required +steps are described in the [On-Demand CSR Signing](https://icinga.com/docs/icinga-2/latest/doc/06-distributed-monitoring/#on-demand-csr-signing) +section of the Icinga 2 documentation. So, we won't cover that here. + +Now, you can start an Icinga 2 agent container using the following command: + +``` +docker run --rm --detach \ + --network icinga \ + --hostname icinga-agent \ + --volume icinga-agent:/data \ + --env ICINGA_ZONE=icinga-agent \ + --env ICINGA_ENDPOINT=icinga-master,icinga-master,5665 \ + --env ICINGA_CACERT="$(< icinga-ca.crt)" \ + --env ICINGA_TICKET="$(< icinga-agent.ticket)" \ + icinga/icinga2 +``` + +This command will run the Icinga 2 agent container in detached mode, mounting the `/data` directory to a persistent +volume named `icinga-agent`. As with the master container, you can adjust the volume name and other parameters as +needed. The environment variables will be processed by the container's entrypoint script and perform a `icinga2 node setup` +on your behalf, configuring the agent to connect to the master. + +You can repeat this step for each additional agent you want to add, ensuring that each agent has a unique hostname and +zone name. + +## Icinga 2 API + +By default, if the `icinga2 node setup` command is run when starting the container, the Icinga 2 API will be enabled, +and it will use a default API user named `root` with a randomly generated password. If you want to use your own API +users and passwords, you can bind mount your api-users file from your host system into the +`/etc/icinga2/conf.d/api-users.conf` in the container as described above. + +## Notifications + +By default, Icinga 2 does not send notifications when running in a containerized environment. However, it is possible +to enable mail notifications by configuring [msmtp](https://wiki.archlinux.org/title/Msmtp) client in the container. +The binary is already included in the official Icinga 2 container image, so it just needs to be configured. In order +to do this, you can either mount the `/etc/msmtprc` file from your host system into the container or provide the +necessary configuration for the `~/icinga/.msmtprc` file via the `MSMTPRC` environment variable. + +## Environment Variables + +Most of the environment variables are used as parameters for the `icinga2 node setup` command. If you set any of these +variables, and the `node setup` has not been run yet, the entrypoint script will automatically run the command for you. + +The following environment variables are available: + +| Variable | Node setup CLI | +|----------------------------------------------------------|-----------------------------------------------------| +| `ICINGA_ACCEPT_COMMANDS=1` | `--accept-commands` | +| `ICINGA_ACCEPT_CONFIG=1` | `--accept-config` | +| `ICINGA_DISABLE_CONFD=1` | `--disable-confd` | +| `ICINGA_MASTER=1` | `--master` | +| `ICINGA_CN=icinga-master` | `--cn icinga-master` | +| `ICINGA_ENDPOINT=icinga-master,2001:db8::192.0.2.9,5665` | `--endpoint icinga-master,2001:db8::192.0.2.9,5665` | +| `ICINGA_GLOBAL_ZONES=global-config` | `--global_zones global-config` | +| `ICINGA_LISTEN=::,5665` | `--listen ::,5665` | +| `ICINGA_PARENT_HOST=2001:db8::192.0.2.9,5665` | `--parent_host 2001:db8::192.0.2.9,5665` | +| `ICINGA_PARENT_ZONE=master` | `--parent_zone master` | +| `ICINGA_TICKET=0123456789abcdef0123456789abcdef01234567` | `--ticket 0123456789abcdef0123456789abcdef01234567` | +| `ICINGA_ZONE=master` | `--zone master` | + +Special variables: + +* `ICINGA_TRUSTEDCERT`'s value is written to a temporary file in the container, which is then used + as the `--trustedcert` parameter for the `icinga2 node setup` command. +* `ICINGA_CACERT`'s value is directly written to the `/var/lib/icinga2/certs/ca.crt` file in the container. + +## Build Your Own Image + +If you want to build your own Icinga 2 container image, you can use the provided `Containerfile` in the Icinga 2 +repository. Additionally, there's a `docker-build.sh` helper script that simplifies the build process. The parameters +used below for the script are explained within the script itself, so you can adjust them as needed. + +``` +git clone https:github.com/Icinga/icinga2.git +cd icinga2 +./tools/container/docker-build.sh load custom-tag linux/amd64 +```