Ansible Role podman_containers¶

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

Available since LFOps 3.0.0.

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