Podman

This guide helps you install and set up Podman in rootless mode.

GitLab project: yoanncolin/ansible/roles/podman

Requirements

You need a Linux system set up with:

• SSH
• Python (for Ansible)
• Sudo access
• A working package manager

You can use the gwerlas.system role to assist you:

ansible-galaxy install gwerlas.system

Example Playbook

Here’s how to use the role in your playbook:

- name: My playbook
  hosts: all
  roles:
    - role: gwerlas.system
    - role: gwerlas.podman

Facts

This role defines these facts:

• podman_version
• podman_packages

To get these facts without changing anything on your nodes:

- name: My playbook
  hosts: all
  tasks:
    - name: Get facts
      ansible.builtin.import_role:
        name: gwerlas.podman
        tasks_from: facts

    - name: Display
      ansible.builtin.debug:
        var: podman_packages

Tags

You can filter tasks with these tags:

• provision: Only provision resources

Role Variables

Here are the available variables with their default values (see defaults/main.yml):

podman_compose_install: false
podman_toolbox_install: false

podman_mimic_docker: false

podman_create_missing_users: true
podman_users:
  - name: "{{ ansible_user_id }}"

podman_wrappers: []
podman_wrappers_path: /usr/local/bin

Podman in Rootless Mode

To allow users to use Podman in rootless mode, the podman_users list should look like this:

podman_users:
  - name: jdoe            # Required Unix login name
    home: /home/jdoe      # Automatically obtained if missing
    uid: 1000             # For users not yet created in the system
    subuid_starts: 100000 # Default starts from user ID
    subuid_length: 50000  # Default is 65536
    subgid_starts: 100000 # Same as subuid_starts by default
    subgid_length: 50000  # Same as subuid_length by default

Since Podman stores data in the user's home directory, we will create it if it isn't there.

To quickly add users, you can run the rootless task:

---
- name: Add a user for Podman rootless usage
  hosts: all
  vars:
    podman_users:
      - name: jdoe
        uid: 300
  tasks:
    - name: Add John Doe
      ansible.builtin.import_role:
        name: gwerlas.podman
        tasks_from: rootless

For Non-Existing Users

If the users don’t exist, we’ll create them using the gwerlas.system role.

To prevent creating missing users, set podman_create_missing_users to false. In this case, you need to specify the uid for each missing user.

Podman Configuration

By default, we leave the configuration files of the distribution unchanged, except for Debian 11 containers, which require additional configuration.

To customize the configuration, use podman_*_config settings.

Containers

Use podman_containers_config to modify /etc/containers/containers.conf following the structure explained in the [containers.conf][] man page.

Example:

podman_containers_config:
  containers:
    log_driver: journald
  engine:
    cgroup_manager: cgroupfs

This will create the following /etc/containers/containers.conf:

[containers]
log_drivers = "journald"

[engine]
cgroup_manager = "cgroupfs"

For Debian 11, we override distribution defaults with the above configuration.

Registries

NOTE Version 1 format is not supported.

Use podman_registries_config to define the /etc/containers/registries.conf file following the structure in the [registries.conf][] man page.

Example:

podman_registries_config:
  unqualified-search-registries:
    - docker.io
  registry:
    - location: my-insecure-registry:5000
      insecure: true

This produces the following /etc/containers/registries.conf:

unqualified-search-registries = ['docker.io']

[[registry]]
location = my-insecure-registry:5000
insecure = true

Storage

Use podman_storage_config to set up /etc/containers/storage.conf following the structure in the [storage.conf][] man page.

Example:

podman_storage_config:
  storage:
    driver: zfs
    options:
      zfs:
        mountopt: "nodev"

This generates:

[storage]
driver = "zfs"

[storage.options.zfs]
mountopt = "nodev"

Libpod

To configure /etc/containers/libpod.conf, use the podman_libpod_config similar to the structure in the [libpod.conf][] man page.

Example:

podman_libpod_config:
  cgroup_manager: cgroupfs

This will create:

cgroup_manager = "cgroupfs"

For Debian 11, we override distribution defaults again.

Podman Compose

Set podman_compose_install to true to install podman-compose if available for your system.

Podman Toolbox

Set podman_toolbox_install to true to install podman-toolbox if it's available.

Mimic Docker

To make Podman behave like Docker, set podman_mimic_docker to true. If podman-docker is available, it will be installed; otherwise, a symlink will be created.

This allows scripts that call docker to use podman instead.

Daemon Socket

If Podman is version 3.0 or higher, the service will be enabled for each podman_users, and the environment variables DOCKER_BUILDKIT and DOCKER_HOST will be set appropriately, allowing you to run Docker commands within Podman.

Wrappers

You can create wrappers to run commands without installing them on your system:

Example for running Molecule:

podman_wrappers:
  - command: molecule
    image: gwerlas/molecule
    env:
      CONTAINER_CONNECTION: docker
      MOLECULE_CONTAINERS_BACKEND: podman
    interactive: true
    network: host
    security_opt: label=disable
    volume:
      - $HOME/.cache/molecule:/root/.cache/molecule
      - $HOME/.vagrant.d:/root/.vagrant.d
      - /run/libvirt:/run/libvirt
      - /var/lib/libvirt:/var/lib/libvirt
      - /var/tmp:/var/tmp
    wrapper_extras:
      env_patterns:
        - ANSIBLE_*
        - MOLECULE_*
      openstack_cli: true
      podman_socket: true
      same_pwd: true
      ssh_auth_sock: true

Most arguments align with podman run parameters. You can customize supported parameters in the podman_wrappers_autofill variable.

Dependencies

You will need the gwerlas.system role for user management.

Ensure containers.podman is installed on your system or present in requirements.yml.

Example Playbook

Here is an example of how to set up Podman to be Docker-compatible:

---
- name: Docker compatible
  hosts: all
  roles:
    - name: gwerlas.system
    - name: gwerlas.podman
      vars:
        podman_mimic_docker: true

License

This project is licensed under the BSD 3-Clause License.