Pods Podman : regrouper des conteneurs comme une unité

Un pod Podman regroupe plusieurs conteneurs qui partagent le même espace réseau. Ils communiquent via localhost, démarrent et s’arrêtent ensemble. C’est idéal pour les patterns sidecar (app + reverse proxy, app + agent de logs).

À la fin de ce guide, vous saurez :

Créer un pod avec plusieurs conteneurs
Comprendre ce qui est partagé et ce qui ne l’est pas
Exposer correctement les ports
Éviter les pièges classiques

Droit au but

Premier pod en 5 min Créez votre premier pod multi-conteneurs.

Ce qui est partagé Réseau, namespaces, et conteneur infra.

Pods vs Compose Quand utiliser l'un ou l'autre.

Différences avec K8s Ce qui pique quand on passe à Kubernetes.

Pourquoi utiliser un pod ?

Le problème : conteneurs qui doivent communiquer étroitement

Certaines applications nécessitent plusieurs processus qui doivent :

Communiquer sur localhost (pas via le réseau)
Partager des volumes pour échanger des fichiers
Être démarrés/arrêtés ensemble

Exemples :

Pattern	Conteneur principal	Sidecar
Reverse proxy	Application	nginx/envoy
Logging	Application	Fluentd/Vector
Monitoring	Application	Prometheus exporter
PHP-FPM	nginx	php-fpm

La solution : le pod

Un pod est un groupe de conteneurs qui partagent :

Le namespace réseau (même interface, même localhost)
Le namespace IPC (communication inter-processus)
Optionnellement des volumes

Structure d'un pod Podman : nginx + php-fpm + infra partageant localhost

Premier pod en 5 minutes

Créer le pod
Fenêtre de terminal
```
podman pod create --name web-stack -p 8080:80
```
Important : le port est exposé au niveau du pod, pas des conteneurs.

Ajouter nginx

podman run -d --pod web-stack --name nginx nginx:alpine

Vérifier

podman pod ps

POD ID        NAME       STATUS   CREATED        INFRA ID      # OF CONTAINERS
abc123def456  web-stack  Running  1 minute ago   def456ghi789  2

Tester
Fenêtre de terminal
```
curl http://localhost:8080
```
Vous voyez la page d’accueil nginx.

Voir les conteneurs du pod

podman pod inspect web-stack --format '{{range .Containers}}{{.Name}} {{end}}'

abc123def456-infra nginx

Notez qu’il y a 2 conteneurs : nginx + le conteneur “infra” (on y revient).

Ce qui est partagé

Le namespace réseau

Tous les conteneurs d’un pod partagent la même interface réseau. Concrètement :

Ils ont la même IP
Ils peuvent communiquer via localhost
Un conteneur peut accéder aux ports des autres sans configuration

Démonstration :

# Créer un pod avec deux conteneurs
podman pod create --name demo-net

podman run -d --pod demo-net --name server \
  python:3.12-alpine python -m http.server 9000

podman run -d --pod demo-net --name client \
  alpine:3.21 sleep infinity

# Le client peut accéder au serveur via localhost
podman exec client wget -qO- http://localhost:9000

<!DOCTYPE HTML>
<html>...

Sans pod, il faudrait un réseau dédié et utiliser le nom du conteneur.

Le conteneur infra (pause)

Quand vous créez un pod, Podman démarre automatiquement un conteneur spécial appelé infra (ou “pause”). Ce conteneur ne fait rien d’utile en apparence — il dort. Mais c’est lui qui détient les namespaces réseau et IPC que tous les autres conteneurs du pod partagent.

Son rôle :

Fonction	Explication
Maintenir les namespaces	Même si tous les conteneurs s’arrêtent, le namespace réseau persiste
Anchorer l’IP	L’IP du pod ne change pas quand un conteneur redémarre
Léger	Utilise ~1 MB de mémoire

# Voir le conteneur infra
podman ps --pod | grep infra

def456ghi789  k8s.gcr.io/pause:3.5  3 minutes ago  Up  web-stack-infra  web-stack

Ce qui N’est PAS partagé

Le partage se limite au réseau et aux IPC. Chaque conteneur conserve son propre système de fichiers, sa propre vision des processus, et ses propres limites de ressources. C’est une différence importante avec les VM où tout est partagé par défaut.

Ressource	Partagée ?	Explication
Réseau	✅	Même interface, même localhost
IPC	✅	Communication inter-processus
Volumes	⚠️	Seulement si montés explicitement
PID namespace	❌	Chaque conteneur a ses propres PIDs
Filesystem	❌	Chaque conteneur a son propre rootfs
Mémoire/CPU	❌	Limites par conteneur

Partager des volumes

Pour partager des fichiers entre conteneurs, montez le même volume :

# Créer un pod avec volume partagé
podman pod create --name shared-data

# Conteneur qui écrit
podman run -d --pod shared-data \
  -v data:/shared:Z \
  --name writer \
  alpine:3.21 sh -c 'while true; do date >> /shared/log.txt; sleep 5; done'

# Conteneur qui lit
podman run -d --pod shared-data \
  -v data:/shared:Z,ro \
  --name reader \
  alpine:3.21 tail -f /shared/log.txt

Lifecycle : pod vs conteneurs

Commandes de pod

Les commandes podman pod agissent sur tous les conteneurs du pod en une seule opération. C’est l’intérêt principal : gérer un groupe comme une unité.

Commande	Effet
`podman pod start <pod>`	Démarre tous les conteneurs
`podman pod stop <pod>`	Arrête tous les conteneurs
`podman pod restart <pod>`	Redémarre tous les conteneurs
`podman pod rm <pod>`	Supprime le pod ET tous ses conteneurs
`podman pod pause <pod>`	Met en pause tous les conteneurs
`podman pod unpause <pod>`	Reprend tous les conteneurs

Démonstration du lifecycle

# Créer un pod avec 2 conteneurs
podman pod create --name lifecycle-demo
podman run -d --pod lifecycle-demo --name c1 alpine:3.21 sleep infinity
podman run -d --pod lifecycle-demo --name c2 alpine:3.21 sleep infinity

# Vérifier l'état
podman pod ps
podman ps --pod

# Arrêter le pod (arrête c1 et c2)
podman pod stop lifecycle-demo

# Vérifier
podman ps -a --pod | grep lifecycle

abc123  alpine:3.21  Exited  c1  lifecycle-demo
def456  alpine:3.21  Exited  c2  lifecycle-demo

Comportement au redémarrage

Quand un conteneur dans un pod s’arrête inopinément :

Situation	Comportement
Un conteneur crash	Les autres continuent
Tous les conteneurs crashent	Le pod reste “Running” (infra actif)
Le conteneur infra crash	Le pod est détruit

Important : contrairement à Kubernetes, Podman ne redémarre pas automatiquement les conteneurs crashés. Utilisez Quadlet ou systemd pour ça.

Exposition réseau : ports et limites

Règle fondamentale

Les ports sont exposés au niveau du pod, pas des conteneurs individuels.

# ✅ Correct : port sur le pod
podman pod create --name web -p 8080:80
podman run -d --pod web --name nginx nginx:alpine

# ❌ Incorrect : -p ignoré quand --pod est utilisé
podman run -d --pod web -p 9090:80 --name nginx nginx:alpine
# Warning: Le -p est ignoré !

Exposer plusieurs ports

podman pod create --name multi-port \
  -p 8080:80 \
  -p 9000:9000 \
  -p 3000:3000

Limites du réseau pod

Le modèle réseau d’un pod est volontairement simple : tout passe par localhost. C’est parfait pour des conteneurs couplés (nginx → php-fpm), mais insuffisant pour des architectures distribuées.

Fonctionnalité	Disponible ?	Alternative
localhost entre conteneurs	✅	—
Ports exposés à l’hôte	✅	—
Service discovery (DNS)	❌	Utiliser podman-compose ou des réseaux bridge
Load balancing	❌	Traefik, nginx reverse proxy

Recette : nginx + php-fpm

Le cas d’usage classique : nginx sert les fichiers statiques et fait proxy vers php-fpm pour le PHP.

Architecture

nginx + php-fpm dans un pod : proxy vers FastCGI avec volume partagé

Implémentation

Créer le contenu PHP

mkdir -p ~/lab-pod/html

<?php
echo "<h1>PHP dans un pod Podman</h1>";
echo "<p>Hostname: " . gethostname() . "</p>";
echo "<p>Date: " . date('Y-m-d H:i:s') . "</p>";
phpinfo();
?>

Configuration nginx

server {
    listen 80;
    server_name localhost;
    root /var/www/html;
    index index.php index.html;

    location ~ \.php$ {
        # php-fpm sur localhost:9000 (même pod)
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location / {
        try_files $uri $uri/ =404;
    }
}

Créer le pod avec le port

podman pod create --name web-php -p 8080:80

Lancer php-fpm

podman run -d --pod web-php \
  --name php-fpm \
  -v ~/lab-pod/html:/var/www/html:Z \
  php:8.3-fpm-alpine

Lancer nginx

podman run -d --pod web-php \
  --name nginx \
  -v ~/lab-pod/html:/var/www/html:Z,ro \
  -v ~/lab-pod/nginx.conf:/etc/nginx/conf.d/default.conf:Z,ro \
  nginx:alpine

Vérifier

# État du pod
podman pod ps

# Conteneurs
podman ps --pod

# Tester
curl http://localhost:8080/index.php

Vérifications

# Vérifier que les conteneurs sont dans le même pod
podman pod inspect web-php --format '{{range .Containers}}{{.Name}} {{end}}'
# php-fpm nginx abc123-infra

# Vérifier que localhost:9000 fonctionne depuis nginx
podman exec nginx sh -c 'echo "test" | nc -z 127.0.0.1 9000 && echo "OK"'
# OK

# Logs
podman logs nginx
podman logs php-fpm

Pods vs Compose : règle de décision

Podman supporte les deux : pods natifs et Compose. La question revient souvent : “Pourquoi utiliser un pod plutôt que Compose ?”

La réponse tient en une phrase : les pods sont pour les conteneurs qui doivent partager localhost, Compose pour les services qui communiquent via le réseau.

Tableau de décision

Critère	Pod	Compose
Conteneurs sur localhost	✅ Idéal	⚠️ Possible mais pas natif
Services indépendants	❌	✅ Idéal
Stack multi-services (db + api + front)	⚠️	✅
Pattern sidecar	✅ Idéal	⚠️
Compatibilité Kubernetes YAML	✅	❌
Service discovery (DNS)	❌	✅
Déjà un docker-compose.yml	❌	✅

Règle simple

Pod : conteneurs couplés qui doivent partager localhost
Compose : services découplés qui communiquent via le réseau

Exemples

Situation	Meilleur choix
nginx + php-fpm	Pod (localhost:9000)
App + redis + postgres	Compose (services séparés)
App + envoy sidecar	Pod (proxy localhost)
Microservices	Compose (service discovery)
Test d’un YAML Kubernetes	Pod (kube play)

Différences avec les pods Kubernetes

Les pods Podman s’inspirent de Kubernetes, mais ne sont pas identiques. Podman est un outil local sans orchestrateur — les fonctionnalités qui dépendent d’un cluster (scheduling, service discovery, restart automatique) sont absentes.

Si vous connaissez Kubernetes, attention aux différences :

Aspect	Podman pods	Kubernetes pods
Restart automatique	❌ Non	✅ Oui (restartPolicy)
Service discovery DNS	❌ Non	✅ Oui
Load balancing	❌ Non	✅ Oui (Services)
Scheduling	❌ Local uniquement	✅ Multi-nodes
Health checks	⚠️ Manuels	✅ livenessProbe, readinessProbe
Resource limits	⚠️ Par conteneur	✅ Pod-level + container-level

Ce qui pique quand on passe à Kubernetes

Pas de restart auto : en production, utilisez Quadlet/systemd
Pas de DNS : utilisez localhost, pas des noms de service
Ports au pod : pas de -p sur podman run --pod

Dépannage

Erreurs courantes

La plupart des problèmes avec les pods viennent de deux sources : les ports mal configurés, et les conteneurs qui ne sont pas dans le bon pod. Le tableau ci-dessous couvre 90% des cas.

Erreur	Cause	Solution
`port already in use`	Port exposé sur un pod existant	`podman pod rm <pod>`
`-p` ignoré avec `--pod`	Ports = responsabilité du pod	Créer le pod avec `-p`
Conteneur ne voit pas l’autre	Mauvais port ou conteneur pas dans le pod	Vérifier avec `podman pod inspect`
Connection refused localhost	Le service n’écoute pas sur toutes les interfaces	Vérifier que le service écoute sur `0.0.0.0`

Commandes de diagnostic

# Lister les pods
podman pod ps

# Voir les conteneurs d'un pod
podman ps --pod --filter pod=<pod-name>

# Inspecter un pod
podman pod inspect <pod-name>

# Voir les ports d'un pod
podman pod inspect <pod-name> --format '{{.InfraConfig.PortBindings}}'

# Logs de tous les conteneurs du pod
podman pod logs <pod-name>

# Tester localhost depuis un conteneur
podman exec <container> wget -qO- http://localhost:<port>

# Nettoyer
podman pod rm -f <pod-name>

Le conteneur ne démarre pas dans le pod

# Vérifier les logs
podman logs <container-name>

# Vérifier que le pod est Running
podman pod ps

# Recréer le pod
podman pod rm -f <pod-name>
podman pod create --name <pod-name> -p <ports>

Bonnes pratiques

Nommage

# ✅ Noms explicites
podman pod create --name api-stack
podman run --pod api-stack --name api-server ...
podman run --pod api-stack --name api-cache ...

# ❌ Noms génériques
podman pod create --name pod1
podman run --pod pod1 --name container1 ...

Organisation

Un pod = un groupe fonctionnel (app + sidecars)
Pas de pod monolithique avec 10 services indépendants
Volumes partagés seulement si nécessaire

Production

Pour la production, ne lancez pas les pods manuellement. Utilisez :

Quadlet : fichiers déclaratifs → systemd (voir le guide)
kube play : fichiers YAML Kubernetes (voir le guide)

À retenir

Pod = groupe de conteneurs partageant le réseau (même localhost)
Conteneur infra : maintient les namespaces, ne pas supprimer
Ports exposés au pod : -p sur podman pod create, pas sur run
Pas de restart auto : utilisez Quadlet/systemd en production
Pas de DNS : communication via localhost:<port>
Pod vs Compose : pod pour couplage fort, Compose pour services séparés

Prochaines étapes

Kube play et generate Testez des YAML Kubernetes localement avec podman kube.

Quadlet (systemd) Déployez vos pods comme services systemd en production.

Réseaux Podman Réseaux bridge, host, et CNI pour des topologies complexes.

Multi-arch et manifests Construisez des images pour plusieurs architectures.