podman

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

Description

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 '127.0.0.1'. 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.

Setup

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.

Usage

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):

podman::storage_options:
  storage:
    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.

Examples

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

classes:
  - types
  - podman
  - firewalld

types::types:
  - firewalld_port

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

types::group:
  jenkins:
    ensure: present
    forcelocal: true
    gid:  222001

types::file:
  /home/jenkins:
    ensure: directory
    owner: 222001
    group: 222001
    mode: '0700'
    require: 'User[jenkins]'

podman::manage_subuid: true
podman::subid:
  '222001':
    subuid: 12300000
    count: 65535

podman::volumes:
  jenkins:
    user: jenkins

podman::containers:
  jenkins:
    user: jenkins
    image: 'docker.io/jenkins/jenkins:lts'
    flags:
      label:
        - purpose=dev
      publish:
        - '8080:8080'
        - '50000:50000'
      volume: 'jenkins:/var/jenkins_home'
    service_flags:
      timeout: '60'
    require:
      - Podman::Volume[jenkins]

types::firewalld_port:
  podman_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.

Limitations

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

Development

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

Reference

Table of Contents

Classes

Public Classes

• podman: Manage containers, pods, volumes, and images with podman without a docker daemon

Private Classes

• podman::install: Install podman packages
• podman::options: edit container options in /etc/containers
• podman::service: Manage the podman.socket service

Defined types

• podman::container: manage podman container and register as a systemd service
• podman::image: pull or remove container images
• podman::network: Create a podman network with defined flags
• podman::pod: Create a podman pod with defined flags
• podman::rootless: Enable a given user to run rootless podman containers as a systemd user service.
• podman::subgid: Define an entry in the /etc/subgid file.
• podman::subuid: Manage entries in /etc/subuid
• podman::volume: Create a podman volume with defined flags

Classes

podman

Manage containers, pods, volumes, and images with podman without a docker daemon

Examples

Basic usage

include podman

A rootless Jenkins deployment using hiera

podman::subid:
  jenkins:
    subuid: 2000000
    count: 65535
podman::volumes:
  jenkins:
    user: jenkins
podman::containers:
  jenkins:
    user: jenkins
    image: 'docker.io/jenkins/jenkins:lts'
    flags:
      label:
        - purpose=test
      publish:
        - '8080:8080'
        - '50000:50000'
      volume: 'jenkins:/var/jenkins_home'
    service_flags:
      timeout: '60'
    require:
      - Podman::Volume[jenkins]

Parameters

The following parameters are available in the podman class:

• podman_pkg
• skopeo_pkg
• buildah_pkg
• podman_docker_pkg
• compose_pkg
• machinectl_pkg
• buildah_pkg_ensure
• podman_docker_pkg_ensure
• compose_pkg_ensure
• machinectl_pkg_ensure
• nodocker
• storage_options
• rootless_users
• enable_api_socket
• manage_subuid
• file_header
• match_subuid_subgid
• subid
• pods
• volumes
• images
• containers
• networks

podman_pkg

Data type: String

The name of the podman package (default 'podman')

Default value: 'podman'

skopeo_pkg

Data type: String

The name of the skopeo package (default 'skopeo')

Default value: 'skopeo'

buildah_pkg

Data type: String

The name of the buildah package (default 'buildah')

Default value: 'buildah'

podman_docker_pkg

Data type: String

The name of the podman-docker package (default 'podman-docker').

Default value: 'podman-docker'

compose_pkg

Data type: String

The name of the podman-compose package (default 'podman-compose').

Default value: 'podman-compose'

machinectl_pkg

Data type: String

The name of the machinectl package (default 'systemd-container').

Default value: 'systemd-container'

buildah_pkg_ensure

Data type: Enum['absent', 'installed']

The ensure value for the buildah package (default 'absent')

Default value: 'absent'

podman_docker_pkg_ensure

Data type: Enum['absent', 'installed']

The ensure value for the podman docker package (default 'installed')

Default value: 'installed'

compose_pkg_ensure

Data type: Enum['absent', 'installed']

The ensure value for the podman-compose package (default 'absent')

Default value: 'absent'

machinectl_pkg_ensure

Data type: Enum['absent', 'installed']

The ensure value for the machinectl package (default 'installed')

Default value: 'installed'

nodocker

Data type: Enum['absent', 'file']

Should the module create the /etc/containers/nodocker file to quiet Docker CLI messages. Values should be either 'file' or 'absent'. (default is 'absent')

Default value: 'absent'

storage_options

Data type: Hash

A hash containing any storage options you wish to set in /etc/containers/storage.conf

Default value: {}

rootless_users

Data type: Array

An array of users to manage using podman::rootless

Default value: []

enable_api_socket

Data type: Boolean

The enable value of the API socket (default false)

Default value: false

manage_subuid

Data type: Boolean

Should the module manage the /etc/subuid and /etc/subgid files (default is false) The implementation uses concat fragments to build out the subuid/subgid entries. If you have a large number of entries you may want to manage them with another method. You cannot use the subuid and subgid defined types unless this is true.

Default value: false

file_header

Data type: String

Optional header when manage_subuid is true. Ensure you include a leading #. Default file_header is # FILE MANAGED BY PUPPET

Default value: '# FILE MANAGED BY PUPPET'

match_subuid_subgid

Data type: Boolean

Enable the subid parameter to manage both subuid and subgid entries with the same values. This setting requires manage_subuid to be true or it will have no effect. (default is true)

Default value: true

subid

Data type: Hash

A hash of users (or UIDs) with assigned subordinate user ID number and an count. Implemented by using the subuid and subgid defined types with the same data. Hash key subuid is the subordinate UID, and count is the number of subordinate UIDs

Default value: {}

pods

Data type: Hash

A hash of pods to manage using podman::pod

Default value: {}

volumes

Data type: Hash

A hash of volumes to manage using podman::volume

Default value: {}

images

Data type: Hash

A hash of images to manage using podman::image

Default value: {}

containers

Data type: Hash

A hash of containers to manage using podman::container

Default value: {}

networks

Data type: Hash

A hash of networks to manage using podman::network

Default value: {}

Defined types

podman::container

manage podman container and register as a systemd service

Examples

podman::container { 'jenkins':
  image         => 'docker.io/jenkins/jenkins',
  user          => 'jenkins',
  flags         => {
                   publish => [
                              '8080:8080',
                              '50000:50000',
                              ],
                   volume  => 'jenkins:/var/jenkins_home',
                   },
  service_flags => { timeout => '60' },
}

Parameters

The following parameters are available in the podman::container defined type:

• image
• user
• flags
• service_flags
• command
• ensure
• enable
• update
• ruby

image

Data type: String

Container registry source of the image being deployed. Required when ensure is present but optional when ensure is set to absent.

Default value: ''

user

Data type: String

Optional user for running rootless containers. For rootless containers, the user must also be defined as a puppet resource that includes at least 'uid', 'gid', and 'home' attributes.

Default value: ''

flags

Data type: Hash

All flags for the 'podman container create' command are supported via the 'flags' hash parameter, using only the long form of the flag name. The container name will be set as the resource name (namevar) unless the 'name' flag is included in the flags hash. If the flags for a container resource are modified the container will be destroyed and re-deployed during the next puppet run. This is achieved by storing the complete set of flags as a base64 encoded string in a container label named puppet_resource_flags so it can be compared with the assigned resource state. Flags that can be used more than once should be expressed as an array. For flags which take no arguments, set the hash value to be undef. In the YAML representation you can use ~ or null as the value.

Default value: {}

service_flags

Data type: Hash

When a container is created, a systemd unit file for the container service is generated using the 'podman generate systemd' command. All flags for the command are supported using the 'service_flags" hash parameter, again using only the long form of the flag names.

Default value: {}

command

Data type: String

Optional command to be used as the container entry point.

Default value: ''

ensure

Data type: String

Valid values are 'present' or 'absent'

Default value: 'present'

enable

Data type: Boolean

Status of the automatically generated systemd service for the container. Valid values are 'running' or 'stopped'.

Default value: true

update

Data type: Boolean

When true, the container will be redeployed when a new container image is detected in the container registry. This is done by comparing the digest value of the running container image with the digest of the registry image. When false, the container will only be redeployed when the declared state of the puppet resource is changed.

Default value: true

ruby

Data type: Stdlib::Unixpath

The absolute path to the ruby binary to use in scripts. The default path is '/opt/puppetlabs/puppet/bin/ruby' for Puppetlabs packaged puppet, and '/usr/bin/ruby' for all others.

Default value: $facts['ruby']['sitedir']

podman::image

pull or remove container images

Examples

podman::image { 'my_container':
  image => 'my_container:tag',
  flags => {
           creds => 'USERNAME:PASSWORD',
           },
}

Parameters

The following parameters are available in the podman::image defined type:

• image
• ensure
• flags
• user
• exec_env

image

Data type: String

The name of the container image to pull, which should be present in a configured container registry.

ensure

Data type: String

State of the resource must be either present or absent.

Default value: 'present'

flags

Data type: Hash

All flags for the 'podman image pull' command are supported, using only the long form of the flag name.

Default value: {}

user

Data type: String

Optional user for running rootless containers. When using this parameter, the user must also be defined as a Puppet resource and must include the 'uid', 'gid', and 'home'

Default value: ''

exec_env

Data type: Array

Optional array of environment variables used when the container image is pulled. Useful for defining a proxy for downloads. For example: ["HTTP_PROXY=http://${proxy_fqdn}:3128", "HTTPS_PROXY=http://${proxy_fqdn}:3128"]

Default value: []

podman::network

Create a podman network with defined flags

Examples

podman::network { 'mnetwork':
  driver   => 'bridge',
  internal => true,
}

Parameters

The following parameters are available in the podman::network defined type:

• ensure
• disable_dns
• driver
• opts
• gateway
• internal
• ip_range
• labels
• subnet
• ipv6
• user

ensure

Data type: Enum['present', 'absent']

State of the resource must be either 'present' or 'absent'.

Default value: 'present'

disable_dns

Data type: Boolean

Disables the DNS plugin for this network which if enabled, can perform container to container name resolution.

Default value: false

driver

Data type: Enum['bridge', 'macvlan']

Driver to manage the network.

Default value: 'bridge'

opts

Data type: Array[String]

A list of driver specific options.

Default value: []

gateway

Data type: Optional[String]

Define the gateway for the network. Must also provide the subnet.

Default value: undef

internal

Data type: Boolean

Restrict external access of this network.

Default value: false

ip_range

Data type: Optional[String]

Allocate container IP from a range. The range must be a complete subnet and in CIDR notation.

Default value: undef

labels

Data type: Hash[String,String]

A hash of metadata labels to set on the network.

Default value: {}

subnet

Data type: Optional[String]

The subnet in CIDR notation

Default value: undef

ipv6

Data type: Boolean

Enable IPv6 (dual-stack) networking.

Default value: false

user

Data type: String

Optional user for creating rootless container networks. For rootless containers, the user must also be defined as a puppet resource that includes at least 'uid', 'gid', and 'home' attributes.

Default value: ''

podman::pod

Create a podman pod with defined flags

Examples

podman::pod { 'mypod':
  flags => {
           label => 'use=test, app=wordpress',
           }
}

Parameters

The following parameters are available in the podman::pod defined type:

• ensure
• flags
• user

ensure

Data type: String

State of the resource, which must be either 'present' or 'absent'.

Default value: 'present'

flags

Data type: Hash

All flags for the 'podman pod create' command are supported, using only the long form of the flag name. The resource name (namevar) will be used as the pod name unless the 'name' flag is included in the hash of flags.

Default value: {}

user

Data type: String

Optional user for running rootless containers. When using this parameter, the user must also be defined as a Puppet resource and must include the 'uid', 'gid', and 'home'

Default value: ''

podman::rootless

Enable a given user to run rootless podman containers as a systemd user service.

podman::subgid

Define an entry in the /etc/subgid file.

Examples

podman::subgid { 'myuser':
  subgid => 1000000
  count  => 65535
}

Parameters

The following parameters are available in the podman::subgid defined type:

• subgid
• count
• order

subgid

Data type: Integer

Numerical subordinate group ID

count

Data type: Integer

Numerical subordinate group ID count

order

Data type: Integer

Sequence number for concat fragments#

Default value: 10

podman::subuid

Manage entries in /etc/subuid

Examples

podman::subuid { 'namevar':
  subuid => 1000000
  count  => 65535
}

Parameters

The following parameters are available in the podman::subuid defined type:

• subuid
• count
• order

subuid

Data type: Integer

Numerical subordinate user ID

count

Data type: Integer

Numerical subordinate user ID count

order

Data type: Integer

Sequence number for concat fragments

Default value: 10

podman::volume

Create a podman volume with defined flags

Examples

podman::volume { 'myvolume':
  flags => {
    label => 'use=test, app=wordpress',
  }
}

Parameters

The following parameters are available in the podman::volume defined type:

• ensure
• flags
• user

ensure

Data type: String

State of the resource must be either 'present' or 'absent'.

Default value: 'present'

flags

Data type: Hash

All flags for the 'podman volume create' command are supported as part of the 'flags' hash, using only the long form of the flag name. The value for any defined flag in the 'flags' hash must be entered as a string. Volume names are created based on the resoure title (namevar)

Default value: {}

user

Data type: String

Optional user for running rootless containers. When using this parameter, the user must also be defined as a Puppet resource and must include the 'uid', 'gid', and 'home'

Default value: ''

Changelog

Release 0.6.7

• Bugfix. Avoid deprecated has_key function #64. Contributed by traylenator
• Support for Puppet 8.x & puppetlabs/stdlib 9.x #66

Release 0.6.6

• Bugfix. Update install.pp due to false positive on selinux check #60. Contributed by magarvo
• Support ArchLinux #61. Contributed by traylenator
• Update supported OS list to drop specific versioned releases.

Release 0.6.5

• Bugfix for issue #55, Typo in network manifest. Identified by CyberLine
• Bugfix for issue #56, creates invalid systemd service file. Identified by tuxmaster5000

Release 0.6.4

• Bugfix. Fixed spelling typo "machienectl", which changed module parameters: "machienectl_pkg_ensure" is now "machinectl_pkg_ensure" "machienectl_pkg" is now "machinectl_pkg"
• Bugfix for issue #54. Unable to set the "--new" option when the systemd unit will be created. identified by tuxmaster5000

Release 0.6.3

• Add user option for networks #53. Contributed by jaevans
• Bugfix for manage_subuid documentation/implementation mismatch #51. Identified by ja391045

Release 0.6.2

• Bugfix. Fix service name #49. contributed by jcpunk

Release 0.6.1

• Bugfix. Set "systemd-logind" service title to a unique value to avoid conflict with "puppet-systemd" PR #45, contributed by jcpunk

Release 0.6.0

• Start user.slice if not running before trying to use "systemctl --user" PR #42, contributed by jcpunk
• Bugfix. Check for the container to avoid refresh errors. PR #43, contributed by jcpunk

Release 0.5.7

• Bugfix. Revert "remove rootless_users parameter and users resource collector" Contributed by silug

Release 0.5.6

• No functional changes. Bumped module dependencies to include the latest versions. Suggested by yorickps

Release 0.5.5

• Remove rootless_users parameter from the main class and do not use a resource collector for users. Identified by imp-

Release 0.5.4

• Bugfix. Creating multiple instances of podman::rootless fails, because they all have the same title for the api socket exec. Contributed by dmaes

Release 0.5.3

• Minor refactoring and general cleanup across several manifests.
• All module parameters defined in the main class and referenced by other classes.
• Default values moved from module hiera to main manifest.
• Add ability to manage the podman-compose package. Contributed by coreone

Release 0.5.2

• Minor fixes to the 'podman::network' defined type. Contributed by optizor

Release 0.5.1

• In the container defined type, skip the upstream image check when the running container image matches the declared resource and $update is false. This reduces hits against the image registry. Contributed by jaevans
• Fix operator syntax used by 'loginctl show-user' command to work with strict POSIX shells. Identified by drebs
• Add a $ruby parameter to the container defined type. This enables open source puppet agents where the ruby binary is not in the under /opt/puppetlabs. Contributed by jaevans

Release 0.5.0

• Add 'extra_env' as a parameter for the 'podman::image' class. Enables proxy support for image pull. Contributed by Kotty666
• Add 'podman::network' defined type to manage podman networks. Contributed by optiz0r

Release 0.4.0

• Add management of the API socket. - Contributed by silug

Release 0.3.0

• Add the ability to manage host system configuration of container storage in '/etc/containers/storage.conf'. Contrubuted by coreone

Release 0.2.7

• Added basic unit tests
• Fixed regression to update container when image digest differs from repo and update is true. Identified by lukashartl

Release 0.2.6

• Fix for container image removal when $update is true. Can't reference a container image after the container has been deleted...

Release 0.2.5

• Fix container removal when set to 'absent'
• Fix to re-deploy container when the defined resource image is changed. Previously, a container would not be re-deployed when the $update parameter was set to false, even when the image declared in the resource definition had changed as reported by 'lukashartl'. This change enables leaving the $update parameter set to false and 'pinning' the container image to a specific version, updating only when specified from puppet.

Release 0.2.4

• Fix "Container fails to restart when resource notified" reported by toreanderson

Release 0.2.3

• Fix for flags that don't require values - Contributed by jtopper
• Add dependency for the podman::install class to defined types

Release 0.2.2

• Only configure selinux on systems where it is enabled - Contributed by optiz0r
• Clean-up in 'podman::rootless'

Release 0.2.1

• Updated default hiera lookup to use a deep merge for all hash parameters in the main podman class

Release 0.2.0

• Changes to fix rootless containers. Using the defined types with the user parameter now requires a corresponding puppet user resource that includes the 'uid', 'gid', and 'home' attributes.
• The 'homedir' parameter was removed from all defined types. Defined types now directly reference attributes of the associated user resource and requires the user and home directory to be managed by puppet.
• Changed default value of manage_subuid to false. Recommend managing subuid/subgid outside this module, although the functionality to manage subuid/subgid files is still present.
• Stopped using resource default statements in favor of defining attributes with a hash.
• Make the 'image' parameter required for the 'container' defined type only when 'ensure' set to 'present'
• Include support for puppet 7.x

Release 0.1.4

• Added parameter to optionally create '/etc/containers/nodocker' - Contributed by coreone

Release 0.1.3

• Added dependency for puppetlabs/selinux_core to enable SElinux boolean container_manage_cgroup

Release 0.1.2

New features

• Added the ability to manage subuid/subgid files.

Release 0.1.0

• Initial Release