Ansible Role podman_containers¶

This role installs Podman and deploys Quadlets to configure containers, networks and volumes. The role supports running rootless containers.

Mandatory Requirements¶

When running rootless containers, make sure to create a user with lingering enabled. This can be done using the linuxfabrik.lfops.login role:

login__users__host_var:
  - name: 'example'
    home: '/opt/example'
    state: 'present'
    linger: true

Tags¶

podman_containers

Installs Podman, deploys Quadlets and manages their state.
Triggers: none.

podman_containers:auto_update

Manages podman-auto-update.timer for system and users.
Triggers: none.

podman_containers:containers

Deploys and removes container Quadlets.
Triggers: none.

podman_containers:networks

Deploys and removes network Quadlets.
Triggers: none.

podman_containers:state

Manages the state of the containers, networks and volumes.
Triggers: none.

podman_containers:volumes

Deploys and removes volume Quadlets.
Triggers: none.

Optional Role Variables¶

podman_containers__auto_update__host_var / podman_containers__auto_update__group_var

List of dictionaries controlling podman-auto-update.timer.
Type: List of dictionaries.
Default: []
Subkeys:
- on_calendar:
  - Optional. Custom schedule for the timer in systemd calendar format (e.g., daily, weekly, *-*-* 04:00:00). When specified, creates an override file to customize the schedule. Uses systemd default daily when unset.
  - Type: String.
  - Default: unset
- state:
  - Optional. State of the timer. Possible options: present (enable and start), absent (disable and stop).
  - Type: String.
  - Default: 'present'
- user:
  - Mandatory. Username for which to manage the timer. Use root for the system-wide timer.
  - Type: String.

podman_containers__containers__host_var / podman_containers__containers__group_var

List of dictionaries describing the Podman containers.
Type: List of dictionaries.
Default: []
Subkeys:
- enabled:
  - Optional. Set true to start the container at boot.
  - Type: Bool.
  - Default: true
- name:
  - Mandatory. Name of the quadlet file. Will be suffixed with -container.service.
  - Type: String.
- raw_container:
  - Optional. Raw block in the [Container] section.
  - Type: String.
  - Default: unset
- raw_install:
  - Optional. Raw block in the [Install] section.
  - Type: String.
  - Default: unset
- raw_service:
  - Optional. Raw block in the [Service] section.
  - Type: String.
  - Default: unset
- raw_unit:
  - Optional. Raw block in the [Unit] section.
  - Type: String.
  - Default: unset
- state:
  - Optional. State of the container. Possible options: present, absent, started (implies present), stopped (implies present).
  - Type: String.
  - Default: 'started'
- user:
  - Optional. Set this to run the container as rootless.
  - Type: String.
  - Default: unset (rootful)
- wanted_by:
  - Optional. Unit for the WantedBy directive. Only effective if enabled: true is set.
  - Type: String.
  - Default: 'default.target'

podman_networks__networks__host_var / podman_networks__networks__group_var

List of dictionaries describing the Podman networks.
Type: List of dictionaries.
Default: []
Subkeys:
- enabled:
  - Optional. Set true to start the network at boot.
  - Type: Bool.
  - Default: true
- name:
  - Mandatory. Name of the quadlet file. Will be suffixed with -network.service.
  - Type: String.
- raw_network:
  - Optional. Raw block in the [Network] section.
  - Type: String.
  - Default: unset
- raw_install:
  - Optional. Raw block in the [Install] section.
  - Type: String.
  - Default: unset
- raw_service:
  - Optional. Raw block in the [Service] section.
  - Type: String.
  - Default: unset
- raw_unit:
  - Optional. Raw block in the [Unit] section.
  - Type: String.
  - Default: unset
- state:
  - Optional. State of the network. Possible options: present, absent, started (implies present), stopped (implies present).
  - Type: String.
  - Default: 'started'
- user:
  - Optional. Set this to run the corresponding container as rootless.
  - Type: String.
  - Default: unset (rootful)
- wanted_by:
  - Optional. Unit for the WantedBy directive. Only effective if enabled: true is set.
  - Type: String.
  - Default: 'default.target'

podman_volumes__volumes__host_var / podman_volumes__volumes__group_var

List of dictionaries describing the Podman volumes.
Type: List of dictionaries.
Default: []
Subkeys:
- enabled:
  - Optional. Set true to start the volume at boot.
  - Type: Bool.
  - Default: true
- name:
  - Mandatory. Name of the quadlet file. Will be suffixed with -volume.service.
  - Type: String.
- raw_volume:
  - Optional. Raw block in the [Volume] section.
  - Type: String.
  - Default: unset
- raw_install:
  - Optional. Raw block in the [Install] section.
  - Type: String.
  - Default: unset
- raw_service:
  - Optional. Raw block in the [Service] section.
  - Type: String.
  - Default: unset
- raw_unit:
  - Optional. Raw block in the [Unit] section.
  - Type: String.
  - Default: unset
- state:
  - Optional. State of the volume. Possible options: present, absent, started (implies present), stopped (implies present).
  - Type: String.
  - Default: 'started'
- user:
  - Optional. Set this to run the corresponding container as rootless.
  - Type: String.
  - Default: unset (rootful)
- wanted_by:
  - Optional. Unit for the WantedBy directive. Only effective if enabled: true is set.
  - Type: String.
  - Default: 'default.target'

Example:

# optional
podman_containers__auto_update__host_var:
  - user: 'root'
    state: 'present'
    on_calendar: '*-*-* 04:00:00' # run at 4 AM every day
  - user: 'rocketuser'
    state: 'present'
    on_calendar: 'weekly'
podman_containers__containers__host_var:
  - name: 'rocketchat'
    raw_container: |
      AutoUpdate=registry
      ContainerName=rocketchat
      EnvironmentFile=/opt/rocketchat/rocketchat.env
      HealthCmd=curl --fail --show-error --silent --max-time 2 http://localhost:3000
      HealthInterval=30s
      HealthOnFailure=kill
      HealthRetries=5
      HealthStartPeriod=5s
      HealthTimeout=10s
      Image=registry.rocket.chat/rocketchat/rocket.chat:latest
      LogDriver=journald
      Network=rocketchat.network
      PublishPort=3000:3000/tcp
      User=rocketchat
      UserNS=keep-id:uid=1000,gid=1000
    raw_service: |
      Restart=always
    user: 'rocketuser'
podman_containers__networks__host_var:
  - name: 'rocketchat'
    user: 'rocketuser'
podman_containers__volumes__host_var:
  - name: 'rocketchat'
    user: 'rocketuser'

Troubleshooting¶

Failed to enable unit: Unit ... is transient or generated.: Since the units are generated, systemctl enable/disable has no effect. Autostarting is handled by the podman-system-generator based on the WantedBy setting in the quadlet. Have a look at man podman-systemd.unit for details.

License¶

The Unlicense

Author Information¶

Linuxfabrik GmbH, Zurich