containers / quadlet

Quadlet has been merged into podman

This repo is frozen.

What is Quadlet

Quadlet is an opinionated tool for easily running podman system containers under systemd in an optimal way.

Why would I want that

Containers are often used in a cloud context, and they are then used in combination with an orchestrator like Kubernetes. They are also commonly used during development and testing to manually manage containers on an ad-hoc basis.

However, there are also use cases where you want some kind of automatic container management, but on a smaller, single-node scale, and often more tightly integrated with the rest of the system. Typical examples of this can be embedded or automotive use, where there is no system administrator, or disconnected or EDGE servers.

The recommended way to do this is to use systemd to orchestrate the containers, since this is an already running process manager, and since podman containers are just child processes. There are many documents that describe how to use podman with systemd directly, but the end result are generally large, hard to maintain systemd config files. And often the container setup isn't optimal.

With quadlet, you describe how to run a container in a format that is very similar to regular systemd config files. From these actual systemd configurations are automatically generated (using systemd generators).

The container descriptions focus on the relevant container details, with no technical details about how the podman integration works. This means they are easy to write, easy to maintain and integration can automatically improve over time as new podman features become available.

A container example

Here is a minimal container config:

[Unit]
Description=A minimal container

[Container]
Image=centos
Exec=sleep 60

[Service]
Restart=always

This is very similar to a regular systemd service file, except for the [Container] section. It will run sleep 60 in a centos container, and then exit only for systemd to restart it again.

If you put this in /etc/containers/systemd/minimal.container and then run systemctl daemon-reload and podman pull centos you can immediately start the container using systemctl start minimal.service and watch the status:

# systemctl status minimal.service
● minimal.service - A minimal container
     Loaded: loaded (/etc/containers/systemd/minimal.container; generated)
     Active: active (running) since Thu 2021-09-23 13:05:33 CEST; 1s ago
    Process: 839846 ExecStartPre=rm -f /run/minimal.cid (code=exited, status=0/SUCCESS)
   Main PID: 839894 (conmon)
      Tasks: 4 (limit: 38375)
     Memory: 1.4M
        CPU: 193ms
     CGroup: /system.slice/minimal.service
             ├─container
             │ ├─839898 /dev/init -- sleep 60
             │ └─839943 /usr/bin/coreutils --coreutils-prog-shebang=sleep /usr/bin/sleep 60
             └─supervisor
               └─839894 /usr/bin/conmon ...

The generated service file is in /run/systemd/generator/minimal.service for people interested in all the technical details.

Building quadlet

Quadlet builds using meson. You can build and install it with these steps:

$ meson builddir  --prefix /usr
$ cd builddir
$ meson compile
$ meson install

This will install quadlet-generator in /usr/lib/systemd/system-generators, which will read configuration files from /etc/containers/systemd.

Where to go from here

Here are some further documentations:

• File formats
• Container setup

Quadlet also ships with some example containers.

quadlet's Issues

How to disable SELinux the correct way?

If I add the "--privileged=true" flag to my .container file, I'm able to get things running successfully

[Container]
PodmanArgs="--privileged=true"

However, the preferred method for disabling SELinux is to pass the "--security-opt label=disable" flag.
Using the following two lines produces an error:

[Container]
NoNewPrivileges=no
PodmanArgs="--security-opt label=disable"

$ journalctl -xeu portainer.service (relevant lines)

Jul 30 21:44:33 falcon portainer[1599]: Error: unknown flag: --security-opt label
Jul 30 21:44:33 falcon portainer[1599]: See 'podman run --help'
Jul 30 21:44:33 falcon systemd[1]: portainer.service: Main process exited, code=exited, status=125/n/a

Is there a third method, or should the example above work?

Environment: Fedora CoreOS 36.20220716.3.1

$ podman info

host:
  arch: amd64
  buildahVersion: 1.26.1
  cgroupControllers:
  - memory
  - pids
  cgroupManager: systemd
  cgroupVersion: v2
  conmon:
    package: conmon-2.1.0-2.fc36.x86_64
    path: /usr/bin/conmon
    version: 'conmon version 2.1.0, commit: '
  cpuUtilization:
    idlePercent: 99.29
    systemPercent: 0.38
    userPercent: 0.33
  cpus: 2
  distribution:
    distribution: fedora
    variant: coreos
    version: "36"
  eventLogger: journald
  hostname: falcon
  idMappings:
    gidmap:
    - container_id: 0
      host_id: 1000
      size: 1
    - container_id: 1
      host_id: 100000
      size: 65536
    uidmap:
    - container_id: 0
      host_id: 1000
      size: 1
    - container_id: 1
      host_id: 100000
      size: 65536
  kernel: 5.18.11-200.fc36.x86_64
  linkmode: dynamic
  logDriver: journald
  memFree: 1653714944
  memTotal: 2064642048
  networkBackend: netavark
  ociRuntime:
    name: crun
    package: crun-1.4.5-1.fc36.x86_64
    path: /usr/bin/crun
    version: |-
      crun version 1.4.5
      commit: c381048530aa750495cf502ddb7181f2ded5b400
      spec: 1.0.0
      +SYSTEMD +SELINUX +APPARMOR +CAP +SECCOMP +EBPF +CRIU +YAJL
  os: linux
  remoteSocket:
    path: /run/user/1000/podman/podman.sock
  security:
    apparmorEnabled: false
    capabilities: CAP_CHOWN,CAP_DAC_OVERRIDE,CAP_FOWNER,CAP_FSETID,CAP_KILL,CAP_NET_BIND_SERVICE,CAP_SETFCAP,CAP_SETGID,CAP_SETPCAP,CAP_SETUID,CAP_SYS_CHROOT
    rootless: true
    seccompEnabled: true
    seccompProfilePath: /usr/share/containers/seccomp.json
    selinuxEnabled: true
  serviceIsRemote: false
  slirp4netns:
    executable: /usr/bin/slirp4netns
    package: slirp4netns-1.2.0-0.2.beta.0.fc36.x86_64
    version: |-
      slirp4netns version 1.2.0-beta.0
      commit: 477db14a24ff1a3de3a705e51ca2c4c1fe3dda64
      libslirp: 4.6.1
      SLIRP_CONFIG_VERSION_MAX: 3
      libseccomp: 2.5.3
  swapFree: 0
  swapTotal: 0
  uptime: 17m 20.4s
plugins:
  log:
  - k8s-file
  - none
  - passthrough
  - journald
  network:
  - bridge
  - macvlan
  volume:
  - local
registries:
  search:
  - registry.fedoraproject.org
  - registry.access.redhat.com
  - docker.io
  - quay.io
store:
  configFile: /var/home/core/.config/containers/storage.conf
  containerStore:
    number: 0
    paused: 0
    running: 0
    stopped: 0
  graphDriverName: overlay
  graphOptions: {}
  graphRoot: /var/home/core/.local/share/containers/storage
  graphRootAllocated: 20926410752
  graphRootUsed: 2335076352
  graphStatus:
    Backing Filesystem: xfs
    Native Overlay Diff: "true"
    Supports d_type: "true"
    Using metacopy: "false"
  imageCopyTmpDir: /var/tmp
  imageStore:
    number: 0
  runRoot: /run/user/1000/containers
  volumePath: /var/home/core/.local/share/containers/storage/volumes
version:
  APIVersion: 4.1.1
  Built: 1655914664
  BuiltTime: Wed Jun 22 16:17:44 2022
  GitCommit: ""
  GoVersion: go1.18.3
  Os: linux
  OsArch: linux/amd64
  Version: 4.1.1

Start container on boot

It seems like I can't setup containers to start on boot. I tried the following:

$ systemctl enable mycontainer
Failed to enable unit: Unit /run/systemd/generator/mycontainer.service is transient or generated.

How would I achieve this with a container generated by quadlet?

My container file looks like this:

[Unit]
Description=My container
After=network.target

[Container]
Image=docker.io/mycontainer:latest

[Service]
Restart=always

[Install]
WantedBy=multi-user.target

AFAIK This has to be done by the generator, so in this case quadlet.

My service is defined in /etc/container/systemd/mycontainer.container. It generates the service file /run/systemd/generated/mycontainer.servicecorrectly. It looks like this:

# Automatically generated by quadlet-generator
[Unit]
Description=My container
After=network.target
RequiresMountsFor=%t/containers
SourcePath=/etc/containers/systemd/mycontainer.container

[X-Container]
Image=docker.io/mycontainer:latest

[Service]
Restart=always
Environment=PODMAN_SYSTEMD_UNIT=%n
KillMode=mixed
ExecStartPre=-rm -f %t/%N.cid
ExecStopPost=-/usr/bin/podman rm -f -i --cidfile=%t/%N.cid
ExecStopPost=-rm -f %t/%N.cid
Delegate=yes
Type=notify
NotifyAccess=all
SyslogIdentifier=%N
ExecStart=/usr/bin/podman run --name=systemd-%N --cidfile=%t/%N.cid --replace --rm -d --log-driver journald --pull=never --runtime /usr/bin/crun --cgroups=split --init --sdnotify=conmon --security-opt=no-new-privileges --cap-drop=all --mount type=tmpfs,tmpfs-size=512M,destination=/tmp --uidmap 0:0:1 --uidmap 1:1879048192:899 --uidmap 901:1879049091:64637 --gidmap 0:0:1 --gidmap 1:1879048192:899 --gidmap 901:1879049091:64637 docker.io/mycontainer:latest

[Install]
WantedBy=multi-user.target

What it should also do is generate a symlink from /run/systemd/generator/multi-user.target.wants/mycontainer.service to /run/systemd/generated/mycontainer.service. That should be enough to get the container started at boot.

tl;dr:

When generating the *.service files from the *.container files quadlet should read the Install section and create corresponding symlinks in /run/systemd/generator/...target.wants/ directories.

Please create the SECURITY and CODE-OF-CONDUCT md files

We ask that all projects under the containers project have a SECURITY.md and a CODE-OF-CONDUCT.md. If you don't have one of your own, please feel free to grab the ones from Buildah and then just change the name of the project within each.

Thanks!

https://github.com/containers/buildah/blob/main/SECURITY.md
https://github.com/containers/buildah/blob/main/CODE-OF-CONDUCT.md

Support for grouping containers into a pod

I normally will group services that depend on each other in a podman pod so they can share the same network namespace and handle ports for the services. It would be nice to have support for that kind of setup in quadlet.

See https://github.com/forem/selfhost/blob/main/playbooks/templates/forem.yml.j2#L810-L1143 for an example of how I have been doing systemd units for podman containers in a podman pod.

--pull=never is problematic if container storage is empty

When container storage is empty, on system start no containers managed by quadlet can actually run. That might happen on clean installs or when an admin replaces the container storage. What's the best way to address that problem?

Support for UDP Ports

Currently is does not seem possible to add the protocol for PublishPort.

What should be possible? -> 80:80/udp

I guess this code https://github.com/containers/quadlet/blob/main/src/generator.c#L519 would need one more switch case?

I have not written any C code before, but if you think this would be a good addition I can give it a try over the weekend :)

[Feature Request] Ability to change/disable "systemd-" container prefix

For simple hobby servers that only host a few services, the "systemd-" prefix feels unnecessary and just adds to the typing that needs to be done to administer the containers.

It would be nice if the user could change the "systemd-" container prefix to something else, or even removed completely

Upstream into podman

I am very interested in this effort. It looks like the right idea!

I could not find any github issue or discussion regarding integration into podman. It would be great (for me!) to update that issue with links to discussion or integration.

Thanks.

Containers don't listen on IPv6

PublishPort lines in the container file don't get properly translated for IPv6 sockets.

This container file:

[Unit]
Description=test container

[Container]
Image=httpd:latest
PublishPort=80:80
PublishPort=[::]:80:80

[Service]
Restart=always

[Install]
WantedBy=multi-user.target default.target

Should result in this service file:

# Automatically generated by quadlet-generator
[Unit]
Description=test container
RequiresMountsFor=%t/containers
SourcePath=/etc/containers/systemd/test.container

[X-Container]
Image=docker.io/httpd:latest
PublishPort=80:80
PublishPort=[::]:80:80

[Service]
Restart=always
Environment=PODMAN_SYSTEMD_UNIT=%n
KillMode=mixed
ExecStartPre=-rm -f %t/%N.cid
ExecStopPost=-/usr/bin/podman rm -f -i --cidfile=%t/%N.cid
ExecStopPost=-rm -f %t/%N.cid
Delegate=yes
Type=notify
NotifyAccess=all
SyslogIdentifier=%N
ExecStart=/usr/bin/podman run --name=systemd-%N --cidfile=%t/%N.cid --replace --rm -d --log-driver journald --pull=never --runtime /usr/bin/crun --cgroups=split --init --sdnotify=conmon --security-opt=no-new-privileges --cap-drop=all --mount type=tmpfs,tmpfs-size=512M,destination=/tmp --uidmap 0:0:1 --uidmap 1:1879048192:65536 --gidmap 0:0:1 --gidmap 1:1879048192:65536 -p=80:80 -p=[::]:80:80 docker.io/httpd:latest

[Install]
WantedBy=multi-user.target default.target

The -p80:80 ends up there but not the -p[::]:80:80. I guess it's a parsing error when the conversion from .container to .service file happens.

Multiple containers? (pods)

Would it make sense to add support for multiple containers in the same format as well? I would like to replace podman-compose with something like this

Please create f36 branch on copr

With fedora 36 finalizing it would be great to have quadlet packages for Fedora 36. With Fedora CoreOS next rebasing to 36 I will need a solution soon and would be glad if I did not have to do any work 🙃.