As some of you might have already noticed, we recently gave our official Icinga 2 container image builds a complete overhaul. These new images are currently available only as snapshot builds but will replace the existing stable images with the next Icinga 2 v2.16.0 release. In this blog post, we’ll walk you through the key changes and improvements that come with the new images, as well as the reasons behind these changes. We’ll also provide you with some guidance on how to use the new images effectively, including some important caveats to keep in mind when mounting volumes. So, without further ado, let’s dive right in!
What’s New?
The new Icinga 2 container images come with several significant changes and improvements. First and foremost, we’ll no longer use the extra docker-icinga2 repository for building the images. Instead, we’ve streamlined the build process to use a single Containerfile that is maintained directly within the main Icinga 2 repository. So, if you’re looking to contribute to the container images or have issues to report, you can now do so directly in the main Icinga 2 repository.
Secondly, as now of this writing, we will not be publishing updated images for the master tag anymore. It’s still available on Docker Hub, but the last update was made over a week ago, and will completely be removed from Docker Hub in the coming weeks. Instead, we will be using the edge (as in bleeding edge 😉) tag to publish the latest development builds of Icinga 2. Therefore, if you have been using the master tag in your deployments, we encourage you to switch to the edge tag instead. Additionally, as part of this major overhaul, we’ve also started to publish the same set of images to GitHub Container Registry as well. This means that you can now pull the images from either Docker Hub or GitHub Container Registry (GHCR), depending on your preference.
Last but not least, we’ve bumped the base image to Debian 13 (Trixie) as well.
Why the Changes?
The decision to overhaul the Icinga 2 container images was driven by several factors. The docker-icinga2 repository with its complex scripts to build the images started to show its shortcomings over time, and frustrated both users and maintainers alike as the image build process is evolving beyond what the original repository was designed for. For instance, even the images had a complex entrypoint script to perform various initialization tasks at container startup, it often caused more problems to its users than it actually solved. Since the entrypoint populated the /data volume with the default configuration files at startup, you could not simply mount your own configuration files into the container without running into issues. This was a common pain point for many users, and we wanted to address it in the new images.
From now on, the /data volume is populated with the default configuration files and the necessary permissions are set at build time, eliminating the need for complex initialization logic at startup. The new entrypoint (which is a simple bash script) focuses solely on starting the Icinga 2 daemon, and only if necessary, performs some basic initialization tasks, such as running the icinga2 api setup command based on the environment variables you provide. This allows us to eliminate, probably, the most prominent issues that users faced with the previous images, which is the inability to mount their own configuration files into the container without running into permission issues or other problems.
With the updated images, you can now mount your own configuration files or directories into the container without any issues, as long as you ensure that the necessary permissions are set correctly on your host system, and you’re aware of the caveats described in the next section. For instance, if you want to run an Icinga 2 master container with a custom api-users.conf file, you can do so using the following command:
docker run --detach \
--name icinga-master \
--hostname icinga-master \
--publish 5665:5665 \
--mount /path/to/your/api-users.conf:/data/etc/icinga2/conf.d/api-users.conf:ro \
--volume icinga-master:/data \
--env ICINGA_MASTER=1 \
icinga/icinga2:edge
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 . The api-users.conf file from your host system will be mounted into the container, replacing the default one. You can adjust the volume name and other parameters as needed. That’s it! The container should start up without any issues, and you can now connect to the Icinga 2 API using the credentials defined in your custom api-users.conf file. You can also mount other configuration files or directories into the container as needed, just make sure to set the correct permissions and be aware of the caveats mentioned below.
Important Note on Volume Mounting
One important thing to note is that if you mount a host directory to the /data volume in the container, it will completely override the default configuration files that are baked into the image. Previously, the entrypoint script would just copy the default configuration files from an intermediate location to the /data volume, since it always verified whether the /data directory was empty or not. Now, since that volume is already populated at build time, the entrypoint script does not perform this check anymore. Therefore, if you mount a host directory to the /data volume as shown below, all files in /data inside the container will be obscured, causing the container to fail to start correctly.
docker run --detach \
--name icinga-master \
--hostname icinga-master \
--publish 5665:5665 \
--mount /path/to/empty-directory:/data \
--env ICINGA_MASTER=1 \
icinga/icinga2:edge
To avoid this, you either need to use --mount to bind only specific files or subdirectories, or let the container first start with a named volume (like icinga-master:/data), and then copy the entire content of the /data directory to your host system as follows:
docker cp icinga-master:/data /path/to/your/host/copied-data-dir
After that, you can stop and remove the container, and then start a new one with the host directory mounted to /data:
docker run --detach \
--name icinga-master \
--hostname icinga-master \
--publish 5665:5665 \
--mount /path/to/your/host/copied-data-dir:/data \
icinga/icinga2:edge
These steps pretty much replicate the behavior of moving local Icinga 2 environment to a containerized one, even though you first let the container populate the /data volume with the default configuration files for you. Note that all these workarounds are avoidable if you only mount specific files or subdirectories from your host system into the container, and not the entire /data directory. We have documented these changes and caveats in our official documentation as well, but we didn’t upload it to Docker Hub yet, in order not to confuse users who are still using the old images.
Conclusion
To sum it up, the new Icinga 2 container images come with several significant changes and improvements that aim to make your life easier. We encourage you to test the new snapshot images (tagged as edge) and provide us with feedback whether they work well for your use cases. If you encounter any issues or have suggestions for further improvements, please don’t hesitate to submit an issue in the Icinga 2 GitHub repository because as long as the new images are in snapshot state, we can still address any issues that might arise before they land in a stable release. So, this is your chance to help us deliver better container images for everyone!
