Skip to content

Commit 20972db

Browse files
yhabteabyhabteab
committed
docs: Add For-Container.md 
1 parent a9afa77 commit 20972db

File tree

1 file changed

+179
-0
lines changed

1 file changed

+179
-0
lines changed

‎doc/02-installation.md.d/For-Container.md

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# Installing Icinga 2 in Containers
2+
3+
To be able to run Icinga 2 in a containerized environment, you'll need to set up a few things.
4+
This guide will help you get started with running Icinga 2 in a container using our official images.
5+
6+
## Prerequisites
7+
8+
- A container runtime such as [Docker](https://www.docker.com) or [Podman](https://podman.io) installed on your system.
9+
- Basic knowledge of how to use Docker or Podman commands.
10+
- A basic understanding of Icinga 2 and its configuration.
11+
12+
## Getting Started
13+
14+
First, create a dedicated docker network for Icinga 2 to ensure that all containers can communicate with each other:
15+
16+
```
17+
docker network create icinga
18+
```
19+
20+
Next, start an Icinga 2 master container using the official Icinga 2 image. By default, all Icinga 2 containers will
21+
listen on port `5665` from within the docker network, but you can expose this port on a different port on your host
22+
system if needed. The following command will start an Icinga 2 master container with the necessary configurations:
23+
24+
```
25+
docker run --rm --detach \
26+
--network icinga \
27+
--name icinga-master \
28+
--hostname icinga-master \
29+
--publish 5665:5665 \
30+
--volume icinga-master:/data \
31+
--env ICINGA_MASTER=1 \
32+
icinga/icinga2
33+
```
34+
35+
This command will run the Icinga 2 master container in detached mode, exposing port 5665 for communication and mounting
36+
the `/data` directory to a persistent volume named `icinga-master`. You can adjust the volume name and other parameters
37+
as needed. You can also set additional environment variables to configure the Icinga 2 instance,
38+
see [Environment Variables](#environment-variables) for a list of available options.
39+
40+
Alternatively, if you're used to using the `icinga2 node wizard` command to set up Icinga 2 nodes, you can still run
41+
the `icinga2 node wizard` command to set up the containers interactively.
42+
43+
```
44+
docker run --rm -it --hostname icinga-master --volume icinga-master:/data icinga/icinga2 icinga2 node wizard
45+
```
46+
47+
This command will run the Icinga 2 master container in interactive mode, allowing you to answer the prompts from the
48+
`icinga2 node wizard` command.
49+
50+
Another option is to mount all the necessary configuration files from your host system into the container.
51+
This way, you can use your existing Icinga 2 configuration files without needing any additional setup steps.
52+
By default, the container will be populated with the default Icinga 2 configuration files, but you can override
53+
them by creating bind mounts from your host system to the respective directories in the container. For example, to
54+
replace the default `constants.conf` file with your own one, you can start the Icinga 2 master container with the
55+
following command:
56+
57+
```
58+
docker run --rm -d \
59+
--network icinga \
60+
--name icinga-master \
61+
--hostname icinga-master \
62+
--publish 5665:5665 \
63+
--volume icinga-master:/data \
64+
--mount=type=bind,source=/absolute/path/to/your/constants.conf,target=/data/etc/icinga2/constants.conf \
65+
--env ICINGA_MASTER=1 \
66+
icinga/icinga2
67+
```
68+
69+
!!! info
70+
71+
If you [mount an empty](https://docs.docker.com/engine/storage/bind-mounts/#mount-into-a-non-empty-directory-on-the-container)
72+
directory from your host into the container’s `/data` directory using `--volume /path/to/empty-directory:/data`,
73+
all files in `/data` inside the container will be obscured. The container may not start correctly because its
74+
important files are no longer visible. This happens because Docker replaces the container's `/data` directory with
75+
your empty host directory. To avoid this, either use `--mount` to bind only specific files or subdirectories, or
76+
use `--volume` with a named volume (like `icinga-master:/data`) so the container's default files are preserved and
77+
only your specified files are replaced.
78+
79+
## Adding Icinga 2 Agents
80+
81+
To add Icinga 2 agents to your setup, you can run additional containers for each agent. In order your agents be able
82+
to successfully connect to the master, they need to have a copy of the master's `ca.crt` file created during the master
83+
setup. You can first copy this file from the master container to your host system using the following command:
84+
85+
```
86+
docker cp icinga-master:/var/lib/icinga2/certs/ca.crt icinga-ca.crt
87+
```
88+
89+
If you didn't use `icinga-master` as the name of your master container, replace it with the actual name you used.
90+
For easier setup, you may want to also obtain a `ticket` from the master container, which will allow the agent to
91+
authenticate itself without needing you to manually sign a certificate signing request (CSR).
92+
93+
You can create a ticket for the agent by running the following command on your host system:
94+
95+
```
96+
docker exec icinga-master icinga2 pki ticket --cn icinga-agent > icinga-agent.ticket
97+
```
98+
99+
Again, replace `icinga-master` with the actual name of your master container if necessary. Additionally, you may want
100+
to adjust the `--cn` parameter to match the hostname of your agent containers. For non-ticket based setups, the required
101+
steps are described in the [On-Demand CSR Signing](https://icinga.com/docs/icinga-2/latest/doc/06-distributed-monitoring/#on-demand-csr-signing)
102+
section of the Icinga 2 documentation. So, we won't cover that here.
103+
104+
Now, you can start an Icinga 2 agent container using the following command:
105+
106+
```
107+
docker run --rm --detach \
108+
--network icinga \
109+
--hostname icinga-agent \
110+
--volume icinga-agent:/data \
111+
--env ICINGA_ZONE=icinga-agent \
112+
--env ICINGA_ENDPOINT=icinga-master,icinga-master,5665 \
113+
--env ICINGA_CACERT="$(< icinga-ca.crt)" \
114+
--env ICINGA_TICKET="$(< icinga-agent.ticket)" \
115+
icinga/icinga2
116+
```
117+
118+
This command will run the Icinga 2 agent container in detached mode, mounting the `/data` directory to a persistent
119+
volume named `icinga-agent`. As with the master container, you can adjust the volume name and other parameters as
120+
needed. The environment variables will be processed by the container's entrypoint script and perform a `icinga2 node setup`
121+
on your behalf, configuring the agent to connect to the master.
122+
123+
You can repeat this step for each additional agent you want to add, ensuring that each agent has a unique hostname and
124+
zone name.
125+
126+
## Icinga 2 API
127+
128+
By default, if the `icinga2 node setup` command is run when starting the container, the Icinga 2 API will be enabled,
129+
and it will use a default API user named `root` with a randomly generated password. If you want to use your own API
130+
users and passwords, you can bind mount your api-users file from your host system into the
131+
`/etc/icinga2/conf.d/api-users.conf` in the container as described above.
132+
133+
## Notifications
134+
135+
By default, Icinga 2 does not send notifications when running in a containerized environment. However, it is possible
136+
to enable mail notifications by configuring [msmtp](https://wiki.archlinux.org/title/Msmtp) client in the container.
137+
The binary is already included in the official Icinga 2 container image, so it just needs to be configured. In order
138+
to do this, you can either mount the `/etc/msmtprc` file from your host system into the container or provide the
139+
necessary configuration for the `~/icinga/.msmtprc` file via the `MSMTPRC` environment variable.
140+
141+
## Environment Variables
142+
143+
Most of the environment variables are used as parameters for the `icinga2 node setup` command. If you set any of these
144+
variables, and the `node setup` has not been run yet, the entrypoint script will automatically run the command for you.
145+
146+
The following environment variables are available:
147+
148+
| Variable | Node setup CLI |
149+
|----------------------------------------------------------|-----------------------------------------------------|
150+
| `ICINGA_ACCEPT_COMMANDS=1` | `--accept-commands` |
151+
| `ICINGA_ACCEPT_CONFIG=1` | `--accept-config` |
152+
| `ICINGA_DISABLE_CONFD=1` | `--disable-confd` |
153+
| `ICINGA_MASTER=1` | `--master` |
154+
| `ICINGA_CN=icinga-master` | `--cn icinga-master` |
155+
| `ICINGA_ENDPOINT=icinga-master,2001:db8::192.0.2.9,5665` | `--endpoint icinga-master,2001:db8::192.0.2.9,5665` |
156+
| `ICINGA_GLOBAL_ZONES=global-config` | `--global_zones global-config` |
157+
| `ICINGA_LISTEN=::,5665` | `--listen ::,5665` |
158+
| `ICINGA_PARENT_HOST=2001:db8::192.0.2.9,5665` | `--parent_host 2001:db8::192.0.2.9,5665` |
159+
| `ICINGA_PARENT_ZONE=master` | `--parent_zone master` |
160+
| `ICINGA_TICKET=0123456789abcdef0123456789abcdef01234567` | `--ticket 0123456789abcdef0123456789abcdef01234567` |
161+
| `ICINGA_ZONE=master` | `--zone master` |
162+
163+
Special variables:
164+
165+
* `ICINGA_TRUSTEDCERT`'s value is written to a temporary file in the container, which is then used
166+
as the `--trustedcert` parameter for the `icinga2 node setup` command.
167+
* `ICINGA_CACERT`'s value is directly written to the `/var/lib/icinga2/certs/ca.crt` file in the container.
168+
169+
## Build Your Own Image
170+
171+
If you want to build your own Icinga 2 container image, you can use the provided `Containerfile` in the Icinga 2
172+
repository. Additionally, there's a `docker-build.sh` helper script that simplifies the build process. The parameters
173+
used below for the script are explained within the script itself, so you can adjust them as needed.
174+
175+
```
176+
git clone https:github.com/Icinga/icinga2.git
177+
cd icinga2
178+
./tools/container/docker-build.sh load custom-tag linux/amd64
179+
```

0 commit comments

Comments
 (0)