Automatically start pods using systemd

Manage entire pods as systemd services to help ensure all containers within the pod start and stop together. This simplifies the management of multi-container applications.

Before you begin

  • The container-tools meta-package is installed.

About this task

Note that the systemctl command should only be used on a pod and you should not start or stop containers individually through systemctl, as they are managed by the pod service along with the internal infra-container.

Note
Starting with Podman v4.6, you can use the Quadlets that describe how to run a container in a format similar to regular systemd unit files and hides the complexity of running containers under systemd.

Procedure

  1. Create an empty pod, for example named systemd-pod: 
    $ podman pod create --name systemd-pod
     
    11d4646ba41b1fffa51c108cbdf97cfab3213f7bd9b3e1ca52fe81b90fed5577
  2. Optional: List all pods: 
    $ podman pod ps
     
    POD ID        NAME         STATUS   CREATED         # OF CONTAINERS  INFRA ID
11d4646ba41b  systemd-pod  Created  40 seconds ago  1                8a428b257111
11d4646ba41b1fffa51c108cbdf97cfab3213f7bd9b3e1ca52fe81b90fed5577
  3. Create two containers in the empty pod. For example, to create container0 and container1 in systemd-pod: 
    $ podman create --pod systemd-pod --name container0 registry.access.redhat.com/ubi10 top
     
    $ podman create --pod systemd-pod --name container1 registry.access.redhat.com/ubi10 top
  4. Optional: List all pods and containers associated with them: 
    $ podman ps -a --pod
     
    CONTAINER ID  IMAGE                                   COMMAND  CREATED        STATUS         PORTS   NAMES               POD ID        PODNAME
24666f47d9b2  registry.access.redhat.com/ubi10:latest  top      3 minutes ago  Created                container0          3130f724e229  systemd-pod
56eb1bf0cdfe  k8s.gcr.io/pause:3.2                             4 minutes ago  Created                3130f724e229-infra  3130f724e229  systemd-pod
62118d170e43  registry.access.redhat.com/ubi10:latest  top      3 seconds ago  Created                container1          3130f724e229  systemd-pod
  5. Generate the systemd unit file for the new pod: 
    $ podman generate systemd --files --name systemd-pod
     
    /home/user1/pod-systemd-pod.service
/home/user1/container-container0.service
/home/user1/container-container1.service

    Note that three systemd unit files are generated, one for the systemd-pod pod and two for the containers container0 and container1.

  6. Display pod-systemd-pod.service unit file: 
    $ cat pod-systemd-pod.service
     
    # pod-systemd-pod.service
# autogenerated by Podman 3.3.1
# Wed Sep  8 20:49:17 CEST 2021

[Unit]
Description=Podman pod-systemd-pod.service
Documentation=man:podman-generate-systemd(1)
Wants=network-online.target
After=network-online.target
RequiresMountsFor=
Requires=container-container0.service container-container1.service
Before=container-container0.service container-container1.service

[Service]
Environment=PODMAN_SYSTEMD_UNIT=%n
Restart=on-failure
TimeoutStopSec=70
ExecStart=/usr/bin/podman start bcb128965b8e-infra
ExecStop=/usr/bin/podman stop -t 10 bcb128965b8e-infra
ExecStopPost=/usr/bin/podman stop -t 10 bcb128965b8e-infra
PIDFile=/run/user/1000/containers/overlay-containers/1dfdcf20e35043939ea3f80f002c65c00d560e47223685dbc3230e26fe001b29/userdata/conmon.pid
Type=forking

[Install]
WantedBy=multi-user.target default.target
    • The Requires line in the [Unit] section defines dependencies on container-container0.service and container-container1.service unit files. Both unit files will be activated.
    • The ExecStart and ExecStop lines in the [Service] section start and stop the infra-container, respectively.
  7. Display container-container0.service unit file: 
    $ cat container-container0.service
     
    # container-container0.service
# autogenerated by Podman 3.3.1
# Wed Sep  8 20:49:17 CEST 2021

[Unit]
Description=Podman container-container0.service
Documentation=man:podman-generate-systemd(1)
Wants=network-online.target
After=network-online.target
RequiresMountsFor=/run/user/1000/containers
BindsTo=pod-systemd-pod.service
After=pod-systemd-pod.service

[Service]
Environment=PODMAN_SYSTEMD_UNIT=%n
Restart=on-failure
TimeoutStopSec=70
ExecStart=/usr/bin/podman start container0
ExecStop=/usr/bin/podman stop -t 10 container0
ExecStopPost=/usr/bin/podman stop -t 10 container0
PIDFile=/run/user/1000/containers/overlay-containers/4bccd7c8616ae5909b05317df4066fa90a64a067375af5996fdef9152f6d51f5/userdata/conmon.pid
Type=forking

[Install]
WantedBy=multi-user.target default.target
    • The BindsTo line in the [Unit] section defines the dependency on the pod-systemd-pod.service unit file
    • The ExecStart and ExecStop lines in the [Service] section start and stop the container0 respectively.
  8. Display container-container1.service unit file: 
    $ cat container-container1.service
  9. Copy all the generated files to $HOME/.config/systemd/user for installing as a non-root user: 
    $ cp pod-systemd-pod.service container-container0.service container-container1.service $HOME/.config/systemd/user
  10. Enable the service and start at user login: 
    $ systemctl enable --user pod-systemd-pod.service
     
    Created symlink /home/user1/.config/systemd/user/multi-user.target.wants/pod-systemd-pod.service  /home/user1/.config/systemd/user/pod-systemd-pod.service.
Created symlink /home/user1/.config/systemd/user/default.target.wants/pod-systemd-pod.service  /home/user1/.config/systemd/user/pod-systemd-pod.service.

    Note that the service stops at user logout.

Results

  • Check if the service is enabled: 
    $ systemctl is-enabled pod-systemd-pod.service
     
    enabled

For more information, see the podman-create(1), podman-generate-systemd(1), and systemctl(1) man pages on your system.