Forge Home


Manage podman containers with puppet


767 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.6.7 (latest)
  • 0.6.6
  • 0.6.5
  • 0.6.4
  • 0.6.3
  • 0.6.2
  • 0.6.1 (deleted)
  • 0.6.0
  • 0.5.7
  • 0.5.6
  • 0.5.5
  • 0.5.4
  • 0.5.3
  • 0.5.2
  • 0.5.1
  • 0.5.0
  • 0.4.0
  • 0.3.0
  • 0.2.7
  • 0.2.6
  • 0.2.5
  • 0.2.4
  • 0.2.3
  • 0.2.2
  • 0.2.1
  • 0.2.0
  • 0.1.4
  • 0.1.1
  • 0.1.0
released Jun 27th 2023
This version is compatible with:
  • Puppet Enterprise 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2016.4.x
  • Puppet >= 4.10.0 < 9.0.0
  • Archlinux, CentOS, Debian, OracleLinux, RedHat, Fedora, Ubuntu

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'southalc-podman', '0.6.7'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add southalc-podman
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install southalc-podman --version 0.6.7

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



southalc/podman — version 0.6.7 Jun 27th 2023


Table of Contents

  1. Description
  2. Setup - Getting started with podman
  3. Usage - Configuration options and additional functionality
  4. Examples - Example configurations
  5. Limitations - OS compatibility, etc.
  6. Development - Guide for contributing to the module


Podman enables running standard docker containers without the usual docker daemon. This has some benefits from a security perspective, with the key point of enabling containers to run as an unprivileged user. Podman also has the concept of a 'pod', which is a shared namespace where multiple containers can be deployed and communicate with each other over the loopback address of ''. Be aware when running rootless containers that published ports are not automatically added to the host firewall. Use another module like firewalld to open ports on the host and the inbound traffic will reach the rootless container.

The defined types 'pod', 'image', 'volume', and 'container' are essentially wrappers around the respective podman "create" commands (podman <type> create). The defined types support all flags for the command, but require them to be expressed using the long form (--env instead of -e). Flags that don't require values should set the value to undef (use ~ or null in YAML). Flags that are used more than once should be expressed as an array. The Jenkins example configuration below demonstrates some of this in the flags and service_flags hashes.


The module installs packages including 'podman', 'skopeo', and optionally 'podman-docker'. The 'podman' package provides core functionality for running containers, while 'skopeo' is used to check for container image updates. The 'podman-docker' package provides a 'docker' command for those that are used to typing 'docker' instead of 'podman' (the 'podman' command is purposefully compatible with 'docker').

Simply including the module is enough to install the packages. There is no service associated with podman, so the module just installs the packages. Management of 'pods', 'images', 'volumes', and 'containers' is done using defined types. The module's defined types are all implemented in the main 'podman' class, allowing resources to be declared as hiera hashes. See the reference for usage of the defined types.


Assign the module to node(s):

include podman

With the module assigned you can manage podman resources using hiera data. When podman defined types are used with the user parameter the resources will be owned by the defined user to support rootless containers. Using rootless containers this way also enables 'loginctl enable-linger' on the user so rootless containers can start and run automatically under the assigned user account when the system boots.

General podman and systemd notes

Be aware of how to work with podman and systemd user services when running rootless containers. The systemd and podman commands rely on the 'XDG_RUNTIME_DIR' environment variable that is normally set during login by pam_systemd. When you switch users this value will likely need to be set in the shell as follows:

su - <container_user>
export XDG_RUNTIME_DIR=/run/user/$(id -u)

Systemd user services use the same 'systemctl' commands, but with the --user flag. As the container user with the environment set, you an run podman and 'systemctl' commands.

podman container list [-a]

systemctl --user status podman-<container_name>

containerd configuration

This module also contains minimal support for editing the containerd configuration files that control some of the lower level settings for how containers are created. Currently, the only supported configuration file is /etc/containers/storage.conf. You should be able to set any of the settings with that file using the $podman::storage_options parameter. For example (if using Hiera):

    rootless_storage_path: '"/tmp/containers-user-$UID/storage"'

Note the use of double quotes inside single quotes above. This is due to the way the puppetlabs/inifile module works currently.


The following example is a hiera-based role that leverages the types module to manage some dependent resources, then uses this module to deploy a rootless Jenkins container. Note that the environment here is using hiera lookup for class assignments. The example will perform the following configuration:

  • Create the jenkins user, group, and home directory using the types module
  • Manage the /etc/subuid and /etc/subgid files, creating entries for the jenkins user
  • Use loginctl to enable-linger on the 'jenkins' user so the user's containers can run as a systemd user service
  • Creates volume jenkins owned by user jenkins
  • Creates container jenkins from the defined image source owned by user jenkins
  • Sets container flags to label the container, publish ports, and attach the previously created jenkins volume
  • Set service flags for the systemd service to timeout at 60 seconds
  • A systemd service podman-<container_name> is created, enabled, and started that runs as a user service
  • The container will be re-deployed any time the image source digest does not match the running container image because the default defined type parameter podman::container::update defaults to true
  • Creates a firewall rule on the host to allow connections to port 8080, which is published by the container. The rule is created with the firewalld_port type from the firewalld module, using the types module again so it can be defined entirely in hiera.
# Hiera based role for Jenkins container deployment

  - types
  - podman
  - firewalld

  - firewalld_port

    ensure: present
    forcelocal: true
    uid:  222001
    gid:  222001
    password: '!!'
    home: /home/jenkins

    ensure: present
    forcelocal: true
    gid:  222001

    ensure: directory
    owner: 222001
    group: 222001
    mode: '0700'
    require: 'User[jenkins]'

podman::manage_subuid: true
    subuid: 12300000
    count: 65535

    user: jenkins

    user: jenkins
    image: ''
        - purpose=dev
        - '8080:8080'
        - '50000:50000'
      volume: 'jenkins:/var/jenkins_home'
      timeout: '60'
      - Podman::Volume[jenkins]

    ensure: present
    zone: public
    port: 8080
    protocol: tcp

Several additional examples are in a separate github project, including a Traefik container configuration that enables SSL termination and proxy access to other containers running on the host, with a dynamic configuration directory enabling updates to proxy rules as new containers are added and/or removed.


The module was written and tested with RedHat/CentOS, but should work with any distribution that uses systemd and includes the podman and skopeo packages


I'd appreciate any feedback. To contribute to development, fork the source and submit a pull request.