Reference

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::quadlet: manage podman quadlets
podman::rootless: Enable a given user to run rootless podman containers as a systemd user service.
podman::secret: Manage a podman secret. Create and remove secrets, it cannot replace.
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
podman_pkg_ensure
buildah_pkg_ensure
podman_docker_pkg_ensure
compose_pkg_ensure
machinectl_pkg_ensure
nodocker
storage_options
containers_options
rootless_users
enable_api_socket
manage_subuid
file_header
match_subuid_subgid
subid
pods
volumes
images
containers
networks
quadlets

`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'

`podman_pkg_ensure`

Data type: Pattern[/^(\d+\.){2}\d+$/, /absent/, /installed/]

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

Default value: 'installed'

`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: Pattern[/^(\d+\.){2}\d+$/, /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: {}

`containers_options`

Data type: Hash

A hash containing any containers options you wish to set in /etc/containers/containers.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: {}

`quadlets`

Data type: Hash

A hash of quadlets to manage using podman::quadlet

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: Optional[String]

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

Default value: undef

`user`

Data type: Optional[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: undef

`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: Optional[String]

Optional command to be used as the container entry point.

Default value: undef

`ensure`

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

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: Optional[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: undef

`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: Enum['present', 'absent']

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: Optional[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: undef

`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: Optional[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: undef

`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: Enum['present', 'absent']

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: Optional[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: undef

`podman::quadlet`

manage podman quadlets

Examples

podman::quadlet { 'jenkins':
  user     => 'jenkins',
  settings => {
    Unit => {
      Description => "Jenkins container",
    },
    Container => {
      Image       => 'docker.io/jenkins/jenkins:latest',
      PublishPort => [
        '5000:5000',
        '8080:8080',
      ],
      Volume      => 'jenkins:/var/jenkins_home',
    },
    Service => {
      TimeoutStartSec => '300',
    },
  },
}

Parameters

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

ensure
user
quadlet_type
settings
defaults

`ensure`

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

Valid values are 'present' or 'absent'

Default value: 'present'

`user`

Data type: String

A username for running rootless containers. The user must also be defined as a puppet resource that includes at least 'uid', 'gid', and 'home' attributes. The default value is "root" and results in root containers and resources.

Default value: 'root'

`quadlet_type`

Data type:

Enum['container',
    'volume',
    'network',
    'build',
    'pod',
    'kube'
  ]

Must be one of the supported quadlet types: "container", "volume", "network", "build", "pod", or "kube". Default is "container"

Default value: 'container'

`settings`

Data type: Hash

A hash that represents the systemd unit file that will be managed for the podman quadlet. No sanity checking is done on this hash, so invalid values can result in a service that fails to start, but this also allows full configuration of any service or container setting now and in the future without needed to go back and update the module.

Default value: {}

`defaults`

Data type: Hash

A hash of values that's merged with settings to simplify module usage. This allows running a container with nothing but an image defined. See the "data/common.yaml" file for default values.

Default value: {}

`podman::rootless`

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

`podman::secret`

Manage a podman secret. Create and remove secrets, it cannot replace.

Examples

Set a secret with a version from puppet directly

podman::secret{'db_password':
  secret => Sensitive('NeverGuess'),
  flags  => {
    label => [
      'version=20230615',
    ]
  }
}

Set a secret from a file

podman::secret{'db_password':
  path => '/etc/passwd',
}

Set a secret from a deferred function call.

podman::secret{'ora_password':
  secret => Sensitive(Deferred('secret_lookup',['ora_password'])),
  flags => {
    labels => ['version=20230615'],
  }
  user => 'rootless user',
}

Parameters

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

ensure
path
secret
flags
user

`ensure`

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

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

Default value: 'present'

`path`

Data type: Optional[Stdlib::Unixpath]

Load secret from an existing file path The secret and path parameters are mutually exclusive.

Default value: undef

`secret`

Data type: Optional[Sensitive[String]]

A secret to be stored - can be set as a Deferred function. If the secret is changed the secret will NOT be modified. Best to set a secret version as a label. The secret and path parameters are mutually exclusive.

Default value: undef

`flags`

Data type: Hash

All flags for the 'podman secret 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. If the flags for a secret are modified the secret will be recreated.

Default value: {}

`user`

Data type: Optional[String[1]]

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

`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: Enum['present', 'absent']

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: Optional[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: undef

Files

REFERENCE.md

Latest commit

History

REFERENCE.md

File metadata and controls

Reference

Table of Contents

Classes

Public Classes

Private Classes

Defined types

Classes

podman

Examples

Basic usage

A rootless Jenkins deployment using hiera

Parameters

podman_pkg

skopeo_pkg

buildah_pkg

podman_docker_pkg

compose_pkg

machinectl_pkg

podman_pkg_ensure

buildah_pkg_ensure

podman_docker_pkg_ensure

compose_pkg_ensure

machinectl_pkg_ensure

nodocker

storage_options

containers_options

rootless_users

enable_api_socket

manage_subuid

file_header

match_subuid_subgid

subid

pods

volumes

images

containers

networks

quadlets

Defined types

podman::container

Examples

Parameters

image

user

flags

service_flags

command

ensure

enable

update

ruby

podman::image

Examples

Parameters

image

ensure

flags

user

exec_env

podman::network

Examples

Parameters

ensure

disable_dns

driver

opts

gateway

internal

ip_range

labels

subnet

ipv6

user

podman::pod

`podman`

`podman_pkg`

`skopeo_pkg`

`buildah_pkg`

`podman_docker_pkg`

`compose_pkg`

`machinectl_pkg`

`podman_pkg_ensure`

`buildah_pkg_ensure`

`podman_docker_pkg_ensure`

`compose_pkg_ensure`

`machinectl_pkg_ensure`

`nodocker`

`storage_options`

`containers_options`

`rootless_users`

`enable_api_socket`

`manage_subuid`

`file_header`

`match_subuid_subgid`

`subid`

`pods`

`volumes`

`images`

`containers`

`networks`

`quadlets`

`podman::container`

`image`

`user`

`flags`

`service_flags`

`command`

`ensure`

`enable`

`update`

`ruby`

`podman::image`

`image`

`ensure`

`flags`

`user`

`exec_env`

`podman::network`

`ensure`

`disable_dns`

`driver`

`opts`

`gateway`

`internal`

`ip_range`

`labels`

`subnet`

`ipv6`

`user`

`podman::pod`

`ensure`

`flags`

`user`

`podman::quadlet`

`ensure`

`user`

`quadlet_type`

`settings`

`defaults`

`podman::rootless`

`podman::secret`

`ensure`

`path`

`secret`

`flags`

`user`

`podman::subgid`

`subgid`

`count`

`order`

`podman::subuid`

`subuid`

`count`

`order`