REFERENCE.md

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::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
• 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::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: 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: ''