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.16.2).

You might already have this collection installed if you are using the ansible package. 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)

Collection links

• Issue Tracker
• Repository (Sources)