Quadlet : exécuter des conteneurs Podman comme services systemd

Quadlet transforme des fichiers déclaratifs en unités systemd pour vos conteneurs Podman. Vous décrivez l’intention (image, ports, volumes), systemd gère le cycle de vie (démarrage, restart, logs).

À la fin de ce cours, vous saurez :

• Démarrer un conteneur comme un service systemd
• Gérer logs, restart et dépendances
• Structurer un mini-stack (volume + réseau + conteneur)
• Choisir entre rootless et rootful

Linux uniquement

Quadlet dépend de systemd. Il fonctionne uniquement sur Linux. Pour macOS/Windows, utilisez Podman Machine avec systemd dans la VM.

Ce que Quadlet résout

Avant Quadlet, vous aviez deux options pour exécuter des conteneurs au démarrage :

1. podman generate systemd : génère une unité .service avec la commande podman run complète. Problème : toute modification nécessite de régénérer le fichier.

2. Écrire un .service à la main : fragile, difficile à maintenir, pas de gestion native des volumes/réseaux.

Quadlet apporte une approche déclarative :

Approche	Maintenabilité	Fonctionnalités
Script shell + cron	Fragile	Aucune
.service manuel	Moyenne	Basiques
podman generate systemd	Moyenne	Complètes mais figées
Quadlet	Excellente	Complètes et évolutives

Glissez pour voir

Quadlet est maintenant l’approche recommandée par Red Hat pour la production.

Prérequis

• Linux avec systemd
• Podman 4.4+ (Quadlet intégré depuis cette version)
• Connaissances de base de systemd (systemctl, journalctl)

Droit au but

Premier service en 5 minutes Créez votre premier conteneur-service avec Quadlet.

Anatomie d'un fichier Quadlet Comprenez la structure et les options disponibles.

Stack multi-services Volumes, réseaux et dépendances entre conteneurs.

Dépannage Résolvez les problèmes courants.

Modèle mental : comment Quadlet fonctionne

Le générateur systemd

Quadlet est un générateur systemd. Il s’exécute automatiquement :

• Au boot du système
• Après chaque systemctl daemon-reload

Il lit vos fichiers .container, .volume, .network et génère les unités .service correspondantes.

Où placer les fichiers

Rootless (utilisateur)

~/.config/containers/systemd/
├── nginx.container
├── data.volume
└── app-network.network

Commandes avec --user :

systemctl --user daemon-reload
systemctl --user start nginx
journalctl --user -u nginx

Rootful (système)

/etc/containers/systemd/
├── nginx.container
├── data.volume
└── app-network.network

Commandes sans --user :

sudo systemctl daemon-reload
sudo systemctl start nginx
sudo journalctl -u nginx

Types de fichiers Quadlet

Quadlet reconnait plusieurs types de fichiers, chacun correspondant à un type de ressource Podman. L’extension du fichier détermine ce que Quadlet va créer :

Extension	Ce qu’il définit	Équivalent Podman
.container	Un conteneur	podman run
.volume	Un volume nommé	podman volume create
.network	Un réseau	podman network create
.pod	Un pod	podman pod create
.image	Une image à pull	podman pull
.kube	Un play kube	podman kube play
.build	Un build d’image	podman build

Glissez pour voir

Dans la pratique, vous utiliserez principalement .container, .volume et .network. Les autres types couvrent des cas d’usage plus spécifiques comme l’intégration avec des manifests Kubernetes (.kube) ou le build d’images en CI/CD (.build).

Voir ce qui est généré

Pour inspecter l’unité systemd générée à partir de votre fichier Quadlet :

# Rootless
systemctl --user cat nginx.service

# Rootful
systemctl cat nginx.service

Démarrage en 5 minutes

Créons un serveur nginx comme service systemd.

1. Créer le répertoire Quadlet (rootless)

   mkdir -p ~/.config/containers/systemd

2. Créer le fichier nginx.container

   cat > ~/.config/containers/systemd/nginx.container << 'EOF'
   [Unit]
   Description=Serveur web Nginx
   
   [Container]
   Image=docker.io/library/nginx:alpine
   PublishPort=8080:80
   
   [Service]
   Restart=always
   
   [Install]
   WantedBy=default.target
   EOF

3. Recharger systemd

   systemctl --user daemon-reload

4. Démarrer le service

   systemctl --user start nginx

5. Vérifier

   systemctl --user status nginx

   Résultat

   ● nginx.service - Serveur web Nginx
        Loaded: loaded (/home/bob/.config/containers/systemd/nginx.container; generated)
        Active: active (running) since Thu 2026-02-13 10:30:00 CET; 5s ago
      Main PID: 12345 (conmon)

Testez avec curl http://localhost:8080 — vous devriez voir la page d’accueil nginx.

Port déjà utilisé ?

Si le service échoue avec address already in use, le port 8080 est occupé par un autre processus (kubectl, serveur de dev, etc.). Vérifiez avec ss -tlnp | grep 8080 et changez le port dans le fichier .container (ex: PublishPort=8180:80).

Activer au démarrage

systemctl --user enable nginx

Persistance rootless

Pour que les services rootless démarrent automatiquement au boot (sans session ouverte), activez le linger :

loginctl enable-linger $USER

Anatomie d’un fichier Quadlet

Un fichier .container se compose de 4 sections :

exemple.container

[Unit]
Description=Description du service
After=network-online.target

[Container]
Image=docker.io/library/nginx:alpine
PublishPort=8080:80
Volume=data:/var/www:Z
Environment=MA_VAR=valeur
ReadOnly=true

[Service]
Restart=always
TimeoutStartSec=300

[Install]
WantedBy=default.target

Section [Unit]

Cette section utilise la syntaxe standard systemd pour définir les métadonnées et les dépendances du service. Les directives les plus utiles :

Directive	Usage
Description=	Description affichée dans systemctl status
After=	Démarre après ces unités
Requires=	Dépendance forte (si l’autre échoue, celui-ci aussi)
Wants=	Dépendance faible

Glissez pour voir

Astuce dépendances : utilisez Requires= pour les dépendances critiques (base de données pour une application) et Wants= pour les dépendances optionnelles (monitoring, logs). After= ne garantit que l’ordre de démarrage, pas que le service dépendant est fonctionnel.

Section [Container]

C’est le cœur de votre fichier Quadlet. Chaque directive correspond à une option de podman run, mais avec une syntaxe déclarative plus lisible :

Directive Quadlet	Option podman run	Exemple
Image=	(image)	nginx:alpine
PublishPort=	-p	8180:80
Volume=	-v	data:/app:Z
Environment=	-e	DEBUG=true
EnvironmentFile=	--env-file	/etc/myapp/env
User=	--user	1000:1000
ReadOnly=	--read-only	true
AddCapability=	--cap-add	NET_BIND_SERVICE
DropCapability=	--cap-drop	ALL
SecurityLabelDisable=	--security-opt label=disable	true
Network=	--network	app-network.network
PodmanArgs=	(options supplémentaires)	--init --userns=keep-id
Exec=	(commande)	/bin/sh -c "sleep infinity"
AutoUpdate=	label auto-update	registry

Glissez pour voir

Deux directives essentielles :

• PodmanArgs= : permet de passer des options podman run non supportées directement par Quadlet. Utilisez-le pour --userns=keep-id (rootless) ou --security-opt.
• Network= : référence un fichier .network du même répertoire. Quadlet gère automatiquement l’ordre de création.

Section [Service]

Cette section contrôle le comportement systemd du service. Les paramètres les plus importants concernent la gestion des redémarrages et les timeouts :

Directive	Usage	Valeur typique
Restart=	Politique de restart	always, on-failure
RestartSec=	Délai entre restarts	5s
TimeoutStartSec=	Timeout au démarrage	300 (pour pull d’image)
TimeoutStopSec=	Timeout à l’arrêt	30

Glissez pour voir

Pourquoi ces valeurs ?

• Restart=always : en production, vous voulez que le service redémarre automatiquement après un crash ou un reboot.
• RestartSec=5s : évite les boucles de redémarrage rapide en cas de problème persistant.
• TimeoutStartSec=300 : 5 minutes pour permettre le pull d’images lourdes (plusieurs Go).

Section [Install]

Définit quand le service doit démarrer :

[Install]
WantedBy=default.target  # rootless
# ou
WantedBy=multi-user.target  # rootful

Recette 1 — Service durci (production)

Voici un service nginx prêt pour la production, avec les bonnes pratiques de sécurité :

~/.config/containers/systemd/nginx-prod.container

[Unit]
Description=Nginx production
After=network-online.target

[Container]
Image=docker.io/library/nginx:alpine
PublishPort=8080:80

# Sécurité : filesystem read-only + tmpfs pour les dossiers d'écriture
ReadOnly=true
Tmpfs=/tmp
Tmpfs=/var/cache/nginx
Tmpfs=/var/run

# Sécurité : capabilities minimales
DropCapability=ALL
AddCapability=NET_BIND_SERVICE
AddCapability=CHOWN
AddCapability=SETGID
AddCapability=SETUID

# Options supplémentaires via PodmanArgs
PodmanArgs=--security-opt no-new-privileges --init

# Volume pour les données (lecture seule)
Volume=web-content:/usr/share/nginx/html:ro,Z

[Service]
Restart=always
RestartSec=5s
TimeoutStartSec=300
TimeoutStopSec=30

[Install]
WantedBy=default.target

Vérifications :

# Recharger et démarrer
systemctl --user daemon-reload
systemctl --user start nginx-prod

# Vérifier le statut
systemctl --user status nginx-prod

# Voir l'unité générée
systemctl --user cat nginx-prod.service

# Tester le restart automatique
podman kill $(podman ps -q --filter name=systemd-nginx-prod)
sleep 10
systemctl --user status nginx-prod  # Doit être "active (running)"

Comprendre les options de sécurité

Pour comprendre pourquoi ces options de sécurité sont importantes, consultez le guide Podman run avancé.

Recette 2 — Rootless propre

En mode rootless, quelques points d’attention :

Répertoire des fichiers

# Créer le répertoire
mkdir -p ~/.config/containers/systemd

# Vos fichiers doivent être ici
ls ~/.config/containers/systemd/

Ports exposés

En rootless, vous ne pouvez pas exposer de ports < 1024 sans configuration spéciale :

# ❌ Ne fonctionne pas en rootless
PublishPort=80:80

# ✅ Port > 1024
PublishPort=8080:80

Volumes et permissions

Problème classique : le conteneur n’a pas accès aux fichiers de l’hôte.

Solution 1 : utiliser PodmanArgs=--userns=keep-id

[Container]
Image=nginx:alpine
Volume=./html:/usr/share/nginx/html:Z
PodmanArgs=--userns=keep-id

Solution 2 : utiliser le suffixe :U (chown automatique)

[Container]
Volume=myvolume:/data:U

Détails sur les volumes

Pour une explication complète des permissions en rootless, consultez le guide Volumes Podman.

Quand basculer en rootful

Le mode rootless est le choix par défaut pour la sécurité (pas de privilèges root). Cependant, certaines situations nécessitent le mode rootful :

Situation	Rootless	Rootful
Dev local	✅
Service utilisateur	✅
Port < 1024 nécessaire		✅
Accès hardware (GPU, USB)		✅
Performance réseau critique		✅
Service système partagé		✅

Glissez pour voir

Règle de décision : commencez toujours en rootless. Basculez en rootful uniquement si vous avez une contrainte technique (port 80/443, GPU) ou organisationnelle (service partagé entre utilisateurs). Le passage en rootful se fait en plaçant vos fichiers dans /etc/containers/systemd/ au lieu de ~/.config/containers/systemd/.

Recette 3 — Stack multi-services

Créons une stack complète : PostgreSQL + application web, avec volume et réseau dédiés.

Structure des fichiers

• Répertoire~/.config/containers/systemd/

  • app-network.network
  • pgdata.volume
  • postgres.container
  • webapp.container

1. Créer le réseau

app-network.network

[Unit]
Description=Réseau applicatif

[Network]
Subnet=10.89.0.0/24
Gateway=10.89.0.1

2. Créer le volume

pgdata.volume

[Unit]
Description=Données PostgreSQL

[Volume]
# Options par défaut suffisent

3. Créer le service PostgreSQL

postgres.container

[Unit]
Description=Base de données PostgreSQL
After=app-network.network pgdata.volume

[Container]
Image=docker.io/library/postgres:16-alpine
Network=app-network.network
Volume=pgdata.volume:/var/lib/postgresql/data:Z

# Variables d'environnement
Environment=POSTGRES_USER=app
Environment=POSTGRES_PASSWORD=secret
Environment=POSTGRES_DB=myapp

# Healthcheck
HealthCmd=pg_isready -U app -d myapp
HealthInterval=10s
HealthTimeout=5s
HealthRetries=3

[Service]
Restart=always
TimeoutStartSec=300

[Install]
WantedBy=default.target

4. Créer le service application

webapp.container

[Unit]
Description=Application web
After=postgres.container
Requires=postgres.container

[Container]
Image=docker.io/myapp:latest
Network=app-network.network
PublishPort=8080:3000

Environment=DATABASE_URL=postgres://app:secret@systemd-postgres:5432/myapp

PodmanArgs=--init --userns=keep-id

[Service]
Restart=always
RestartSec=5s

[Install]
WantedBy=default.target

Déployer la stack

# Recharger
systemctl --user daemon-reload

# Démarrer (l'ordre est géré par les dépendances)
systemctl --user start webapp

# Vérifier
systemctl --user status app-network pgdata postgres webapp

Points clés

Cette stack illustre plusieurs mécanismes Quadlet importants :

Directive	Ce qu’elle fait
After=postgres.container	Démarre après PostgreSQL
Requires=postgres.container	Si PostgreSQL échoue, webapp s’arrête
Network=app-network.network	Utilise le réseau Quadlet
Volume=pgdata.volume:/path	Utilise le volume Quadlet

Glissez pour voir

Comment Quadlet gère les ressources : quand vous référencez app-network.network dans Network=, Quadlet sait que c’est un fichier du même répertoire. Il crée le réseau systemd-app-network avant de démarrer le conteneur. Même logique pour les volumes.

Attention : les fichiers .network et .volume ne créent pas de services systemd visibles avec systemctl status. Ils créent les ressources Podman sous-jacentes (vérifiez avec podman network ls et podman volume ls).

Nommage des conteneurs

Quadlet préfixe automatiquement les noms de conteneurs avec systemd-. Votre postgres.container devient systemd-postgres. Utilisez ce nom pour les connexions réseau.

Bonnes pratiques

Nommage

Un bon nommage facilite le debug et la maintenance à long terme :

• Fichiers : noms explicites (postgres.container, pas db.container). Quand vous aurez 10 services, vous regretterez les noms génériques.
• Descriptions : rédigez-les pour systemctl status. “Base de données PostgreSQL 16 - production” est plus utile que “db”.
• Un service = un fichier : Quadlet gère les dépendances entre fichiers. Évitez de tout mettre dans un seul fichier complexe.

Restart et timeouts

[Service]
# Toujours redémarrer en production
Restart=always

# Délai entre les redémarrages (évite les boucles)
RestartSec=5s

# Timeout pour le pull d'image (images lourdes)
TimeoutStartSec=300

# Timeout pour l'arrêt propre
TimeoutStopSec=30

Ordre de démarrage

[Unit]
# Dépendance forte : si postgres échoue, webapp ne démarre pas
Requires=postgres.container

# Ordre : webapp démarre APRÈS postgres
After=postgres.container

# Dépendance faible : si le réseau n'existe pas, on essaie quand même
Wants=app-network.network

Sécurité

[Container]
# Filesystem en lecture seule
ReadOnly=true
Tmpfs=/tmp

# Capabilities minimales
DropCapability=ALL
AddCapability=NET_BIND_SERVICE

# Bloquer l'escalade de privilèges
PodmanArgs=--security-opt no-new-privileges --init

Observabilité

L’un des grands avantages de Quadlet : vos conteneurs bénéficient automatiquement de l’infrastructure de logs systemd. Plus besoin de podman logs — utilisez journalctl :

# Statut rapide (conteneur actif ? PID ? mémoire ?)
systemctl --user status webapp

# Logs en temps réel (équivalent de podman logs -f)
journalctl --user -u webapp -f

# Logs depuis le dernier boot (utile après un redémarrage)
journalctl --user -u webapp -b

# Logs des 10 dernières minutes (debug incident récent)
journalctl --user -u webapp --since "10 minutes ago"

Avantage journalctl : les logs persistent après l’arrêt du conteneur et sont automatiquement rotatés par systemd.

Dépannage

”Je pose le fichier mais rien n’apparaît”

1. Vérifiez le répertoire

   # Rootless
   ls ~/.config/containers/systemd/
   
   # Rootful
   ls /etc/containers/systemd/

2. Vérifiez l’extension

   Le fichier doit se terminer par .container, .volume, .network, etc.

3. Rechargez systemd

   systemctl --user daemon-reload

4. Vérifiez que l’unité existe

   systemctl --user list-unit-files | grep monservice

”Le service démarre puis s’arrête”

Cause 1 : image inexistante

# Vérifier les logs
journalctl --user -u monservice -n 50

# Si l'image n'existe pas, la pull manuellement
podman pull docker.io/library/nginx:alpine

Cause 2 : port déjà utilisé

# Vérifier quel processus utilise le port
ss -tlnp | grep 8080

Cause 3 : problème de permissions

# Logs détaillés
journalctl --user -u monservice --no-pager

# Chercher "permission denied"

”Rootless + volumes = permission denied”

Solution 1 : ajouter --userns=keep-id

[Container]
PodmanArgs=--userns=keep-id
Volume=./data:/app/data:Z

Solution 2 : utiliser le suffixe :U

[Container]
Volume=myvolume:/app/data:U

Solution 3 : sur SELinux, ajouter :Z

[Container]
Volume=./data:/app/data:Z

”Le conteneur ne se connecte pas à la base de données”

Vérifiez le nommage : Quadlet préfixe les conteneurs avec systemd-

# ❌ Incorrect
Environment=DATABASE_HOST=postgres

# ✅ Correct
Environment=DATABASE_HOST=systemd-postgres

Commandes de debug

# Voir l'unité générée
systemctl --user cat monservice.service

# Tester la génération Quadlet manuellement
/usr/libexec/podman/quadlet --dryrun --user

# Voir les logs systemd pour Quadlet
journalctl --user -u systemd-generator -b

Templates prêts à copier

Ces templates couvrent les cas d’usage courants. Copiez-les, adaptez Image= et PublishPort=, et vous avez un service fonctionnel.

Template conteneur simple

Le minimum viable pour démarrer rapidement. Adapté au développement local :

simple.container

[Unit]
Description=Mon service

[Container]
Image=docker.io/library/nginx:alpine
PublishPort=8080:80

[Service]
Restart=always

[Install]
WantedBy=default.target

Template conteneur durci

Pour la production : filesystem read-only, capabilities minimales, pas d’escalade de privilèges. Utilisez ce template comme base pour tout service exposé au réseau :

hardened.container

[Unit]
Description=Service durci

[Container]
Image=docker.io/library/nginx:alpine
PublishPort=8080:80

ReadOnly=true
Tmpfs=/tmp
Tmpfs=/var/run

DropCapability=ALL
AddCapability=NET_BIND_SERVICE

PodmanArgs=--security-opt no-new-privileges --init --userns=keep-id

[Service]
Restart=always
RestartSec=5s
TimeoutStartSec=300

[Install]
WantedBy=default.target

Template avec volume et réseau

Pour les services stateful (bases de données, caches). Ce template nécessite des fichiers .network et .volume complémentaires dans le même répertoire :

stateful.container

[Unit]
Description=Service avec données persistantes
After=mynetwork.network mydata.volume

[Container]
Image=docker.io/library/postgres:16-alpine
Network=mynetwork.network
Volume=mydata.volume:/var/lib/postgresql/data:Z

Environment=POSTGRES_PASSWORD=secret

HealthCmd=pg_isready
HealthInterval=30s

[Service]
Restart=always
TimeoutStartSec=300

[Install]
WantedBy=default.target

À retenir

• Quadlet = fichiers déclaratifs (.container, .volume, .network) → systemd gère le cycle de vie
• Répertoires : ~/.config/containers/systemd/ (rootless) ou /etc/containers/systemd/ (rootful)
• Workflow : créer fichier → daemon-reload → start → status
• Dépendances : After= pour l’ordre, Requires= pour la criticité
• Nommage : Quadlet préfixe avec systemd- (important pour les connexions réseau)
• Debug : systemctl cat pour voir l’unité générée, journalctl pour les logs

Prochaines étapes

Run avancé Comprenez les options de sécurité utilisées dans Quadlet (capabilities, read-only, no-new-privileges).

Volumes Gérez la persistance des données et les permissions rootless.

Réseaux Configurez les réseaux Podman pour vos stacks multi-services.

×

📖 Voir la documentation →