Monitoring Podman

On the Podman host, the Checkmk agent must already be installed and registered.

In addition to the agent, you will also need the agent plugin mk_podman.py, which you can find in Checkmk Community under Setup > Agents > Linux > Plug-ins. In the commercial editions, go to the Setup menu via Agents > Windows, Linux, Solaris, AIX to first access the Agent Bakery, where you will find the baked packages. From there, use the menu entry Related > Linux, Solaris, AIX files to access the list of agent files.

Install the plugin on the Podman host in the agent’s plugin directory (by default /usr/lib/check_mk_agent/plugins):

For more detailed information on installing an agent plugin, see the article on the Linux agent.

If you then perform a service discovery on the corresponding host in Checkmk, you should already see several services that include the word Podman in their names:

However, if you do not see any Podman services listed here, it may be because the agent plugin’s automatic detection was unable to communicate with your Podman instance through the usual channels. In this case—and also if you want to change certain parameters—you must provide the agent plugin with a configuration. You can learn how to do this in the following chapter Configure agent plug-in.

The agent plug-in usually figures out on its own how to communicate with Podman on the respective host. However, if this automatic detection fails or if you want to specify that only certain sockets—or, for example, only the root socket—should be queried, you can configure the plugin accordingly.

To do this, create a configuration file named mk_podman.cfg on the Podman host in the agent’s configuration directory. By default, this is /etc/check_mk/.

As a site user of your Checkmk site, you can find a template for this configuration file with detailed explanations in the directory ~/share/check_mk/agents/cfg_examples/mk_podman.cfg. In the Checkmk Community graphical interface, you can find the sample configuration under Setup > Agents > Linux > Plug-ins. In the commercial editions, you can access the Setup menu via Agents > Windows, Linux, Solaris, AIX to first enter the Agent Bakery. From there, use the menu item Related > Linux, Solaris, AIX files to access the list of agent files.

However, we’d like to briefly touch on a key configuration option here. This is the connection_method, which determines how mk_podman.py attempts to communicate with your Podman instance. By default, the agent plugin attempts to communicate with the Podman API via a Unix socket. Alternatively, you can instruct the plugin to perform monitoring via the podman command. A corresponding configuration might look like this:

The really interesting part of monitoring Podman is, of course, monitoring the containers. This data is also provided by the agent plugin. However, the services are not assigned to the Podman host; instead, Checkmk assumes a separate host for each container.

The assignment is handled via the piggyback mechanism. All you need to do is create hosts with the correct names during setup, and the services will be automatically assigned to them.

In the commercial editions, you can have these hosts created automatically. To do this, use the Piggyback data connection type in dynamic host management. You can also create the hosts manually.

Please note the following:

After you have created the container hosts and performed service discovery, additional services will appear here.

The agent plugin mk_podman.py already generates the names for the container hosts. By default, the plugin concatenates the name of the Podman host with the name of the container, separated by an underscore. Alternatively, you can instruct the agent plugin to combine the container name with the container ID, or to use only the container name. To do this, you must set the piggyback_name_method option in the agent plugin’s configuration file to either name or name_id. However, if you choose one of these two methods, you must ensure elsewhere that no name collisions occur in Checkmk. In Checkmk, each host name can only exist exactly once.

If you later want to change these names—for example, to extract specific information directly from the host name—you can use the rule set Host name translation for piggybacked hosts. This allows you to define rules quite flexibly for renaming host names contained in piggyback data. In the following example, the string mypodmanhost- is prepended to all containers that are piggybacked via the host mypodmanhost.

For more options and a more detailed description, see the article the piggyback mechanism.

By default, every Checkmk site already contains a rule in the Host check command rule set that ensures each container host receives the status of the respective service Status. This rule should remain unchanged or be configured exactly as shown:

The service Status checks whether the container is running and can therefore be used as a reliable means of determining the host status. Since every container host is automatically assigned the host label cmk/podman/object:container, this is used as a condition here.

If the setup does not work, there are several ways to troubleshoot the issue.

First, check the output of the Checkmk agent. You can access this in the host view in Monitoring via the Download agent output entry in the action menu.

Or you can search the agent cache directly.

If the agent’s output does not contain any sections that begin with <<<podman, you’ll need to continue troubleshooting on the Podman host.

To do this, manually run the agent plugin on the Podman host:

The output of mk_podman.py will also provide information about what went wrong in the event of an error. For example, if the agent plugin cannot find Podman on the host, it will state this fact plainly:

If only a container host is not receiving data or no services are detected for it, first check whether the piggyback data for that host is available. To do this, review the agent output again to see if there are sections for the container host. You can search the agent output, for example, by the container’s ID.

As an instance user, you can check whether Piggyback data has been created for a container. In the tmp/check_mk/piggyback directory, you should find directories that belong to your containers.

If you do not change the host names via Host name translation for piggybacked hosts, you should find directories here that consist of the container’s name and its ID.