containers.podman.podman_generate_systemd module – Generate systemd unit from a pod or a container

Note

This module is part of the containers.podman collection (version 1.18.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install containers.podman. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: containers.podman.podman_generate_systemd.

Synopsis

  • Generate systemd .service unit file(s) from a pod or a container

  • Support Ansible check mode

Requirements

The below requirements are needed on the host that executes this module.

  • Podman installed on target host

Parameters

Parameter

Comments

after

list / elements=string

Add the systemd unit after (After=) option, that ordering dependencies between the list of dependencies and this service.

This option may be specified more than once.

User-defined dependencies will be appended to the generated unit file

But any existing options such as needed or defined by default (e.g. online.target) will not be removed or overridden.

Only with Podman 4.0.0 and above

container_prefix

string

Set the systemd unit name prefix for containers.

If not set, use the default defined by podman, container.

Refer to podman-generate-systemd(1) man page for more information.

dest

path

Destination of the generated systemd unit file(s).

Use /etc/systemd/system for the system-wide systemd instance.

Use /etc/systemd/user or ~/.config/systemd/user for use with per-user instances of systemd.

env

dictionary

Set environment variables to the systemd unit files.

Keys are the environment variable names, and values are the environment variable values

Only with Podman 4.3.0 and above

executable

string

Podman executable name or full path

Default: "podman"

force

boolean

Replace the systemd unit file(s) even if it already exists.

This works with dest option.

Choices:

  • false ← (default)

  • true

name

string / required

Name of the pod or container to export

new

boolean

Generate unit files that create containers and pods, not only start them.

Refer to podman-generate-systemd(1) man page for more information.

Choices:

  • false ← (default)

  • true

no_header

boolean

Do not generate the header including meta data such as the Podman version and the timestamp.

Choices:

  • false ← (default)

  • true

pod_prefix

string

Set the systemd unit name prefix for pods.

If not set, use the default defined by podman, pod.

Refer to podman-generate-systemd(1) man page for more information.

requires

list / elements=string

Set the systemd unit requires (Requires=) option.

Similar to wants, but declares a stronger requirement dependency.

Only with Podman 4.0.0 and above

restart_policy

string

Restart policy of the service

Choices:

  • "no-restart"

  • "on-success"

  • "on-failure"

  • "on-abnormal"

  • "on-watchdog"

  • "on-abort"

  • "always"

restart_sec

integer

Configures the time to sleep before restarting a service (as configured with restart-policy).

Takes a value in seconds.

Only with Podman 4.0.0 and above

separator

string

Systemd unit name separator between the name/id of a container/pod and the prefix.

If not set, use the default defined by podman, -.

Refer to podman-generate-systemd(1) man page for more information.

start_timeout

integer

Override the default start timeout for the container with the given value in seconds.

Only with Podman 4.0.0 and above

stop_timeout

integer

Override the default stop timeout for the container with the given value in seconds.

use_names

boolean

Use name of the containers for the start, stop, and description in the unit file.

Choices:

  • false

  • true ← (default)

wants

list / elements=string

Add the systemd unit wants (Wants=) option, that this service is (weak) dependent on.

This option may be specified more than once.

This option does not influence the order in which services are started or stopped.

User-defined dependencies will be appended to the generated unit file

But any existing options such as needed or defined by default (e.g. online.target) will not be removed or overridden.

Only with Podman 4.0.0 and above

Notes

Note

  • If you indicate a pod, the systemd units for it and all its containers will be generated

  • Create all your pods, containers and their dependencies before generating the systemd files

  • If a container or pod is already started before you do a systemctl daemon-reload, systemd will not see the container or pod as started

  • Stop your container or pod before you do a systemctl daemon-reload, then you can start them with systemctl start my_container.service

Examples

# Example of creating a container and systemd unit file.
# When using podman_generate_systemd with new:true then
# the container needs rm:true for idempotence.
- name: Create postgres container
  containers.podman.podman_container:
    name: postgres
    image: docker.io/library/postgres:latest
    rm: true
    state: created

- name: Generate systemd unit file for postgres container
  containers.podman.podman_generate_systemd:
    name: postgres
    new: true
    no_header: true
    dest: /etc/systemd/system

- name: Ensure postgres container is started and enabled
  ansible.builtin.systemd:
    name: container-postgres
    daemon_reload: true
    state: started
    enabled: true


# Example of creating a container and integrate it into systemd
- name: A postgres container must exist, stopped
  containers.podman.podman_container:
    name: postgres_local
    image: docker.io/library/postgres:latest
    state: stopped

- name: Systemd unit files for postgres container must exist
  containers.podman.podman_generate_systemd:
    name: postgres_local
    dest: ~/.config/systemd/user/

- name: Postgres container must be started and enabled on systemd
  ansible.builtin.systemd:
    name: container-postgres_local
    scope: user
    daemon_reload: true
    state: started
    enabled: true


# Generate the unit files, but store them on an Ansible variable
# instead of writing them on target host
- name: Systemd unit files for postgres container must be generated
  containers.podman.podman_generate_systemd:
    name: postgres_local
  register: postgres_local_systemd_unit

# Generate the unit files with environment variables sets
- name: Systemd unit files for postgres container must be generated
  containers.podman.podman_generate_systemd:
    name: postgres_local
    env:
      POSTGRES_USER: my_app
      POSTGRES_PASSWORD: example
  register: postgres_local_systemd_unit

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

podman_command

string

A copy of the podman command used to generate the systemd unit(s)

Returned: always

Sample: "podman generate systemd my_webapp"

systemd_units

dictionary

A copy of the generated systemd .service unit(s)

Returned: always

Sample: {"container-postgres_local": " #Content of the systemd .servec unit for postgres_local container", "pod-my_webapp": " #Content of the systemd .servec unit for my_webapp pod"}

Authors

  • Sébastien Gendre (@CyberFox001)