Podman kube : tester et générer des YAML Kubernetes localement

Podman kube permet de tester des manifests Kubernetes localement, sans cluster. Vous pouvez aussi générer des YAML depuis vos conteneurs existants. C’est idéal pour valider vos manifests avant de les déployer sur un vrai cluster.

À la fin de ce guide, vous saurez :

Lancer des pods depuis des YAML Kubernetes
Générer des manifests depuis des conteneurs existants
Itérer rapidement : generate → edit → play
Nettoyer proprement avec kube down

Droit au but

Play : YAML → Pod Lancez un pod depuis un manifest Kubernetes.

Generate : Pod → YAML Créez un YAML depuis vos conteneurs existants.

Boucle d'itération Workflow generate → edit → play → replace.

Nettoyage kube down et gestion des volumes.

Pourquoi utiliser kube play ?

Le problème : tester un YAML sans cluster

Vous avez un manifest Kubernetes et vous voulez le tester :

Sans installer Minikube ou Kind
Sans déployer sur un cluster de dev
Rapidement, pour valider la syntaxe et le comportement

La solution : podman kube play

podman kube play lit un fichier YAML Kubernetes et crée les ressources localement avec Podman.

Flux kube play : manifest YAML vers Pod Podman local

Ce qui est supporté

Podman ne simule pas un cluster Kubernetes complet — il se concentre sur les ressources que vous pouvez tester localement sans orchestrateur. Les ressources de type “réseau” (Services, Ingress) ne sont pas supportées car elles dépendent d’un control plane Kubernetes.

Ressource	Supporté	Notes
Pod	✅	Complet
Deployment	✅	Crée les pods
DaemonSet	✅	Crée un pod
ConfigMap	✅	Monté comme fichiers ou envvars
Secret	✅	Monté comme fichiers ou envvars
PersistentVolumeClaim	✅	Crée un volume Podman
Service	❌	Utilisez les ports du pod
Ingress	❌	Non supporté
NetworkPolicy	❌	Non supporté

kube play : lancer un YAML

Syntaxe de base

podman kube play <fichier.yaml>

Premier exemple

Créer un manifest simple

apiVersion: v1
kind: Pod
metadata:
  name: nginx-web
  labels:
    app: nginx
spec:
  containers:
    - name: nginx
      image: docker.io/library/nginx:alpine
      ports:
        - containerPort: 80
          hostPort: 8080

Lancer avec kube play

podman kube play nginx-pod.yaml

Pod:
nginx-web
Container:
nginx-web-nginx

Vérifier

podman pod ps

POD ID        NAME        STATUS   CREATED        # OF CONTAINERS
abc123def456  nginx-web   Running  10 seconds ago 2

Tester
Fenêtre de terminal
```
curl http://localhost:8080
```

Exemple avec Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app
spec:
  replicas: 2    # Crée 2 pods
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: docker.io/library/nginx:alpine
          ports:
            - containerPort: 80

podman kube play deployment.yaml

Options utiles de kube play

Les options les plus utiles permettent de contrôler le réseau, de charger des ConfigMaps externes, et surtout d’itérer rapidement avec --replace.

Option	Description	Exemple
`--network`	Réseau à utiliser	`--network my-net`
`--configmap`	Charger un ConfigMap externe	`--configmap cm.yaml`
`--start`	Démarrer les pods (défaut: true)	`--start=false`
`--replace`	Remplacer les pods existants	`--replace`
`--down`	Alias pour `kube down`	(voir section dédiée)

kube generate : créer un YAML

Le cas d’usage

Vous avez des conteneurs qui fonctionnent avec podman run. Vous voulez les “exporter” en YAML Kubernetes pour :

Les versionner dans Git
Les déployer ailleurs
Les transformer en vraies ressources Kubernetes

Syntaxe

# Depuis un conteneur
podman kube generate <container-name> > pod.yaml

# Depuis un pod
podman kube generate <pod-name> > pod.yaml

Exemple : conteneur simple

# Créer un conteneur
podman run -d --name my-nginx -p 8080:80 nginx:alpine

# Générer le YAML
podman kube generate my-nginx

apiVersion: v1
kind: Pod
metadata:
  name: my-nginx-pod
  labels:
    app: my-nginx-pod
spec:
  containers:
    - name: my-nginx
      image: docker.io/library/nginx:alpine
      ports:
        - containerPort: 80
          hostPort: 8080

Exemple : pod complet

# Créer un pod avec plusieurs conteneurs
podman pod create --name api-stack -p 8080:80
podman run -d --pod api-stack --name nginx nginx:alpine
podman run -d --pod api-stack --name redis redis:alpine

# Générer le YAML
podman kube generate api-stack > api-stack.yaml

Le YAML généré contient les deux conteneurs dans le même pod.

Options de kube generate

Deux options principales : écrire directement dans un fichier (-f) ou générer aussi un Service Kubernetes (-s) pour faciliter la transition vers un vrai cluster.

Option	Description	Exemple
`-f, --filename`	Écrire dans un fichier	`-f pod.yaml`
`-s, --service`	Générer aussi un Service	`-s`

# Générer Pod + Service
podman kube generate my-nginx -s

Workflow d’itération

Le workflow typique est :

Workflow d'itération kube play : prototyper, générer, éditer, tester, itérer

Démonstration

Prototyper avec le CLI

# Créer le pod manuellement
podman pod create --name demo -p 8080:80
podman run -d --pod demo --name app nginx:alpine

Générer le YAML
Fenêtre de terminal
```
podman kube generate demo > demo.yaml
```

Éditer le YAML

Ajoutez des ressources, des variables d’environnement, etc.

apiVersion: v1
kind: Pod
metadata:
  name: demo
spec:
  containers:
    - name: app
      image: docker.io/library/nginx:alpine
      ports:
        - containerPort: 80
          hostPort: 8080
      resources:
        limits:
          memory: "128Mi"
          cpu: "500m"
      env:
        - name: ENV
          value: "production"

Supprimer l’ancien pod
Fenêtre de terminal
```
podman pod rm -f demo
```
Relancer avec le YAML modifié
Fenêtre de terminal
```
podman kube play demo.yaml
```

Vérifier les changements

podman inspect demo-app --format '{{.Config.Env}}'
# [ENV=production ...]

L’option —replace

Pour éviter de supprimer manuellement le pod :

# Première fois
podman kube play demo.yaml

# Modifications...

# Remplacer directement
podman kube play --replace demo.yaml

kube down : nettoyer proprement

Syntaxe

podman kube down <fichier.yaml>

Ce que kube down supprime

kube down est conservateur par défaut : il supprime les pods et conteneurs, mais préserve les volumes pour éviter toute perte de données accidentelle. Utilisez --force uniquement si vous voulez un nettoyage complet.

Ressource	Supprimée ?	Notes
Pods	✅	Toujours
Conteneurs	✅	Tous les conteneurs du pod
Volumes créés par le YAML	⚠️	Seulement avec `--force`
Réseaux	❌	Non supprimés

Exemple

# Créer
podman kube play demo.yaml

# Vérifier
podman pod ps

# Supprimer
podman kube down demo.yaml

Pods stopped:
demo
Pods removed:
demo

Supprimer les volumes aussi

Par défaut, kube down préserve les volumes (pour ne pas perdre de données).

# Supprimer pods + volumes
podman kube down --force demo.yaml

Vérifier ce qui reste après kube down

# Vérifier les pods (devrait être vide)
podman pod ps

# Vérifier les volumes (peuvent rester)
podman volume ls

# Nettoyer manuellement les volumes orphelins
podman volume prune

ConfigMaps et Secrets

ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  app.conf: |
    server {
      listen 80;
    }
  LOG_LEVEL: debug
---
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
    - name: app
      image: nginx:alpine
      volumeMounts:
        - name: config-volume
          mountPath: /etc/nginx/conf.d
      env:
        - name: LOG_LEVEL
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: LOG_LEVEL
  volumes:
    - name: config-volume
      configMap:
        name: app-config
        items:
          - key: app.conf
            path: default.conf

podman kube play config.yaml

Secrets

apiVersion: v1
kind: Secret
metadata:
  name: db-secret
type: Opaque
data:
  password: cGFzc3dvcmQxMjM=  # base64 encoded
---
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
    - name: app
      image: nginx:alpine
      env:
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: password

Encoder un secret en base64 :

echo -n 'password123' | base64
# cGFzc3dvcmQxMjM=

Lab : workflow complet

Objectif : créer une stack API avec nginx + backend, la transformer en YAML, et itérer.

Créer la stack avec des commandes

# Créer le pod
podman pod create --name api-demo -p 8080:80

# Backend (simule une API)
podman run -d --pod api-demo --name backend \
  python:3.12-alpine python -m http.server 3000

# Frontend (nginx)
podman run -d --pod api-demo --name frontend \
  nginx:alpine

Vérifier que ça fonctionne

# État
podman pod ps
podman ps --pod

# Test
curl http://localhost:8080

Générer le YAML

podman kube generate api-demo > api-demo.yaml
cat api-demo.yaml

Éditer le YAML

Ajoutez des variables d’environnement, des labels, etc.

Supprimer et recréer

podman pod rm -f api-demo
podman kube play api-demo.yaml

Vérifier
Fenêtre de terminal
```
podman pod ps
curl http://localhost:8080
```
Nettoyer
Fenêtre de terminal
```
podman kube down api-demo.yaml
```

Checklist de validation :

podman pod ps montre le pod
podman ps --pod montre les conteneurs
curl localhost:8080 fonctionne
Après kube down, podman pod ps est vide
podman volume ls montre les volumes restants (si PVC)

Dépannage

Erreurs courantes

La plupart des erreurs viennent de trois sources : un pod qui existe déjà (nom en conflit), une image mal référencée (oubli du registry), ou un port déjà utilisé.

Erreur	Cause	Solution
`Error: pod already exists`	Pod avec ce nom existe	`--replace` ou supprimer le pod
`image not found`	Image avec tag local	Ajouter `docker.io/library/`
`hostPort already in use`	Port déjà utilisé	Changer le hostPort ou libérer le port
`ConfigMap not found`	ConfigMap pas dans le même fichier	Mettre ConfigMap avant Pod dans le YAML

Commandes de diagnostic

# Voir ce qui a été créé
podman pod ps
podman ps --pod

# Logs d'un conteneur
podman logs <container-name>

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

# Vérifier un YAML sans le lancer
podman kube play --start=false <fichier.yaml>

Le pod ne démarre pas

# Vérifier les logs
podman kube play my-pod.yaml
podman logs <container-name>

# Problème d'image ?
podman pull docker.io/library/nginx:alpine

# Problème de port ?
ss -tlnp | grep <port>

Bonnes pratiques

Organisation des fichiers

Répertoiredeploy/
- Répertoirebase/
  - pod.yaml
  - configmap.yaml
  - secret.yaml
- Répertoiredev/
  - pod-dev.yaml
- Répertoireprod/
  - pod-prod.yaml

Conventions

Un fichier par ressource ou tout dans un fichier avec --- séparateurs
ConfigMap avant Pod : les dépendances d’abord
Images complètes : docker.io/library/nginx:alpine pas nginx:alpine
Labels explicites : pour le filtrage et la documentation

Versionner les YAML

# Générer avec date
podman kube generate my-pod > pod-$(date +%Y%m%d).yaml

# Ou utiliser Git
git add pod.yaml
git commit -m "feat: add resource limits"

À retenir

kube play : lance un YAML Kubernetes localement
kube generate : crée un YAML depuis des conteneurs existants
--replace : recrée le pod sans suppression manuelle
kube down : supprime le pod, préserve les volumes (sauf --force)
Workflow : CLI → generate → edit → play → iterate
Scope limité : pas de Services, Ingress, NetworkPolicy

Prochaines étapes

Multi-arch et manifests Construisez des images pour amd64 et arm64.

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

Pods Podman Comprendre les pods natifs sans YAML.

Kubernetes avec K3s Passez à un vrai cluster Kubernetes léger.