Podman

This role is used to configure podman, manage containers, and set up systemd services that run podman containers.

Requirements

• You need Podman version 4.2 or newer.
• For quadlet and secret functionalities, you need Podman version 4.4 or newer.
• For health check support, use Podman version 4.5 or newer (this feature works only with quadlet container types).

Collection Requirements

The role requires these collections:

• containers.podman
• fedora.linux_system_roles

To install the collections, use:

ansible-galaxy collection install -vv -r meta/collection-requirements.yml

Users, Groups, SubUID, SubGID

Users and groups defined in podman_run_as_user, podman_run_as_group, and in a kube spec as run_as_user and run_as_group must meet these requirements:

• They must already exist on the system; the role will not create them, and an error will occur if a non-existent user or group is referenced.
• Users must exist in /etc/subuid and groups in /etc/subgid. An error will occur if a specified user is missing from /etc/subuid or a specified group is missing from /etc/subgid. The role uses getsubids to verify this.

Role Variables

podman_kube_specs

This is a list. Each item describes a podman pod and its corresponding systemd unit. The items have a structure similar to the podman_play module but with these specifics:

• state: Default is created. Possible values are:

  • started: Create pods and systemd services, and start them.
  • created: Create pods and systemd services but do not start them.
  • absent: Remove the pods and systemd services.

• run_as_user: Specify a user for the pod. Defaults to the value of podman_run_as_user, or root. The user must exist and be in /etc/subuid.

• run_as_group: Specify a group for the pod. Defaults to the value of podman_run_as_group, or root. The group must exist and be in /etc/subgid.

• systemd_unit_scope: Scope for the systemd unit. Defaults to podman_systemd_unit_scope.

• activate_systemd_unit: Whether to activate the systemd unit upon creation. Default is true.

• pull_image: Ensure the image is pulled before use. Default is true.

• continue_if_pull_fails: If pulling the image fails, continue without treating it as a fatal error. Default is false.

• kube_file_src: File name on the control node to copy to the managed node. It should be in Kubernetes YAML format.

• kube_file_content: String or dict in Kubernetes YAML format to be used as the content for the kube file on the managed node.

• kube_file: Name of the file on the managed node that contains the Kubernetes specification.

Example:

podman_kube_specs:
  - state: started
    kube_file_content:
      apiVersion: v1
      kind: Pod
      metadata:
        name: myappname

This will create /etc/containers/ansible-kubernetes.d/myappname.yml on the managed node.

podman_quadlet_specs

List of Quadlet specifications. Each quadlet spec is identified by a name and type. You can explicitly pass these or derive them from a specified file.

Default file locations are:

• /etc/containers/systemd/$name.$type for root containers.
• $HOME/.config/containers/systemd/$name.$type for rootless containers.

To specify dependencies, ensure that files required by a quadlet spec are defined before the dependent file.

podman_secrets

List of secret specs similar to those used in podman_secret. An additional field is run_as_user, specifying a user for the particular secret.

podman_create_host_directories

Boolean (default false). If true, the role ensures that host directories in volume mounts specified in podman_kube_specs are created.

podman_host_directories

Dict specifying ownership and permissions for host directories created if podman_create_host_directories is true.

podman_firewall

List of ports to manage in the firewall.

podman_selinux_ports

List to manage SELinux policy for ports.

podman_run_as_user

Specify the user for all rootless containers.

podman_run_as_group

Specify the group for all rootless containers.

podman_systemd_unit_scope

Default scope for systemd units.

podman_activate_systemd_units

Default is true for activating systemd units when created.

podman_pull_image

Ensure all images are present by pulling. Default is true.

podman_continue_if_pull_fails

Continue without failing if pulling an image fails. Default is false.

podman_containers_conf

Settings for containers.conf, provided as a dict.

podman_registries_conf

Settings for containers-registries.conf, provided as a dict.

podman_storage_conf

Settings for containers-storage.conf, provided as a dict.

podman_policy_json

Settings for containers-policy.json, provided as a dict.

podman_use_copr (EXPERIMENTAL)

Boolean to enable using a copr repository for the latest podman version.

podman_fail_if_too_old (EXPERIMENTAL)

If true, the role will fail if an unsupported podman version is detected.

Authentication Variables

• podman_registry_username: Username for registry authentication.
• podman_registry_password: Password for registry authentication.
• podman_credential_files: List of credential files for registries.
• podman_registry_certificates: List of TLS certificates and keys for registry connections.
• podman_validate_certs: Control TLS cert validation when pulling images.
• podman_prune_images: If true, remove unused images when cleaning up.
• podman_transactional_update_reboot_ok: Handle reboots for transactional update systems.

Example Playbooks

Create a Rootless Container

- name: Manage podman containers and services
  hosts: all
  vars:
    podman_create_host_directories: true
    podman_firewall:
      - port: 8080-8081/tcp
        state: enabled 
    podman_kube_specs:
      - state: started
        run_as_user: dbuser
        kube_file_content:
          apiVersion: v1
          kind: Pod
          metadata:
            name: db
          spec:
            containers:
              - name: db
                image: quay.io/db/db:stable
                ports:
                  - containerPort: 1234
                    hostPort: 12340
    roles:
      - linux-system-roles.podman

Create a Container with Podman Volume

- name: Manage podman root containers and services
  hosts: all
  vars:
    podman_kube_specs:
      - state: started
        kube_file_content:
          apiVersion: v1
          kind: Pod
          metadata:
            name: ubi8-httpd
          spec:
            containers:
              - name: ubi8-httpd
                image: registry.access.redhat.com/ubi8/httpd-24
                ports:
                  - containerPort: 8080
                    hostPort: 8080
    roles:
      - linux-system-roles.podman

Create Quadlet Application with Secrets

podman_quadlet_specs:
  - name: quadlet-demo
    type: network
    file_content: |
      [Network]
      Subnet=192.168.30.0/24
  - file_src: quadlet-demo-app.container
podman_secrets:
  - name: mysql-root-password
    data: "{{ root_password }}"

License

MIT License

Author Information

Originally based on podman-container-systemd by Ilkka Tengvall. Other contributors include: Thom Carlin, Rich Megginson, Adam Miller, Valentin Rothberg.