Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท Compose and Quadlet

Quadlet for Pods, Volumes and Networks

Build a complete stack with Quadlet: .volume, .network, .pod, .kube and .image unit files, how containers reference them, generated names, dependency ordering and a full example.

A single .container file is a good start, but a real application has storage, a private network and several cooperating containers. Quadlet covers those with more unit types. Each one becomes a systemd service, and when one file refers to another, Quadlet adds the right systemd dependencies for you so things start in order.

This lesson walks through every unit type and then assembles a three-part stack. Quadlet requires systemd, so the unit files are read-only text; the runnable stand-ins resolve references and compute start order.

The unit types

File Creates Generated service
name.container a container name.service
name.volume a named volume name-volume.service
name.network a network name-network.service
name.pod a pod name-pod.service
name.kube workloads from Kubernetes YAML (podman kube play) name.service
name.image a pulled image name-image.service
name.build an image built from a Containerfile name-build.service

Objects created by Quadlet are named systemd-<name> by default (for example the volume systemd-appdata). You can override that with VolumeName=, NetworkName=, PodName= or ContainerName= in the matching section.

Volumes

appdata.volume:

INI
[Volume]
Label=app=shop

An empty [Volume] section is fine. To use it from a container, name the file as the volume source:

INI
[Container]
Image=docker.io/library/postgres:17
Volume=appdata.volume:/var/lib/postgresql/data

Because the source ends in .volume, Quadlet knows it is a Quadlet-managed volume, creates it first (the container's service gets Requires= and After= on appdata-volume.service) and substitutes the real volume name.

Networks

shopnet.network:

INI
[Network]
Subnet=10.89.10.0/24
Gateway=10.89.10.1
Label=app=shop

Other keys include Internal=true, IPv6=true, DisableDNS=true and Driver=. Use it with Network=shopnet.network in a container. Containers on a Quadlet network get DNS, so db can be reached by its container name or an alias set with NetworkAlias=.

Pods

shop.pod:

INI
[Pod]
PodName=shop
PublishPort=8080:80
Network=shopnet.network

A container joins the pod with Pod=shop.pod. Pod containers share a network namespace: they talk on localhost, and ports are published on the pod, not on individual containers. Do not repeat PublishPort= in the container files.

INI
# web.container
[Container]
Image=docker.io/library/nginx:stable
Pod=shop.pod

[Service]
Restart=always

[Install]
WantedBy=default.target

The pod gets its own service, shop-pod.service, and every container in it depends on that service.

Kubernetes YAML

If you already have a Kubernetes-style YAML file (see Podman and Kubernetes YAML), a .kube file runs it as a service:

INI
[Kube]
Yaml=shop.yaml
PublishPort=8080:80

[Install]
WantedBy=default.target

Images and builds

An .image unit pulls an image as its own service, which is useful for pre-pulling or for referencing from several containers. A .build unit builds from a Containerfile:

INI
# app.build
[Build]
ImageTag=localhost/myapp:latest
File=Containerfile
SetWorkingDirectory=unit

A container then says Image=app.build and Quadlet makes sure the build ran first.

Reference resolution, by hand

When you write Network=shopnet.network, Quadlet replaces it with the real network name and adds ordering. This stand-in models that translation so you can see what the generator will do.

Python Resolve .volume and .network references (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Start order across a stack

Because references create Requires= and After=, systemd starts volumes and networks first, then the pod, then containers. You can add manual ordering in [Unit] (After=db.service) when an application must wait for another container.

Python Systemd start order (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Each step lists units that systemd can start in parallel; the next step begins once that batch is up.

A complete mini stack

Files in ~/.config/containers/systemd/:

  • shopnet.network, appdata.volume, shop.pod as above
  • db.container with Pod=shop.pod, Volume=appdata.volume:/var/lib/postgresql/data, Environment=POSTGRES_PASSWORD=example (use Secret= or EnvironmentFile= for real passwords)
  • web.container with Pod=shop.pod and an nginx image
Terminal
systemctl --user daemon-reload
systemctl --user start shop-pod.service web.service db.service
systemctl --user status shop-pod.service
podman pod ps

Because the containers share a pod, web reaches the database at localhost:5432. The next chapters build on this layout in a full project.

Secrets: avoid putting passwords in unit files, which are readable by anyone who can read the directory. Use podman secret create and Secret=name,type=env,target=POSTGRES_PASSWORD in the [Container] section.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the default name of a volume created from appdata.volume?

    Quadlet prefixes objects with systemd- unless VolumeName= is set.
  2. 2. How does a .container file use a Quadlet-managed network?

    Naming the .network file as the Network= value makes Quadlet resolve the name and add dependencies.
  3. 3. Where do published ports go for containers that belong to a pod?

    Pod containers share one network namespace, so PublishPort= belongs on the .pod file.
  4. 4. Which key keeps a database password out of a world-readable unit file?

    Podman secrets are stored separately; Secret= injects them as an environment variable or file.

Summary

  • Quadlet has unit types for containers, volumes, networks, pods, Kubernetes YAML, images and builds.
  • Referencing x.volume, x.network or x.pod from a container creates the object and the systemd ordering for you.
  • Generated objects are named systemd-<name> unless you override the name.
  • Containers in a pod share localhost; publish ports on the pod.
  • Keep secrets out of unit files with Secret=.

Next: Building Images with a Containerfile