Construire une image Podman : multi-stage, cache, secrets, push

Ce guide vous apprend à construire une image reproductible, petite, rapide à builder, et à la publier proprement. Vous comprendrez le raisonnement derrière chaque décision de build, pas juste les options.

À la fin, vous saurez :

• Optimiser le cache pour des builds en quelques secondes
• Utiliser multi-stage pour diviser la taille par 10
• Passer des secrets sans les exposer dans l’image
• Publier vers un registry avec un digest vérifiable

Scénario fil rouge

Tout au long de ce guide, nous construisons une API Python FastAPI. Chaque section améliore le build : d’abord naïf (300 MB, 2 min), puis optimisé (50 MB, 10 sec).

Droit au but

Optimiser le cache Accélérez vos builds de 2 min à 10 sec.

Multi-stage builds Réduisez la taille de vos images de 90%.

Secrets de build Passez des tokens sans les brûler dans l'image.

Publier proprement Tag, push, et récupérez le digest.

Modèle mental : comment podman build fonctionne

Podman utilise Buildah en interne

Quand vous exécutez podman build, Podman appelle Buildah pour construire l’image. Cela a des implications importantes :

Aspect	Ce que ça signifie
Stockage partagé	podman et buildah voient les mêmes images
Compatibilité	Dockerfile et Containerfile sont équivalents
Options avancées	Certaines options viennent de Buildah (--secret, --ssh)
Sans démon	Pas de daemon à maintenir, builds rootless possibles

Glissez pour voir

Le contexte de build

Le contexte est le dossier envoyé au builder. Tout ce qui est dedans peut être copié dans l’image avec COPY.

# Le "." à la fin = contexte = dossier courant
podman build -t mon-image:1.0 .

Problème fréquent : un dossier node_modules/ de 500 MB dans le contexte ralentit tous les builds.

Solution : le fichier .containerignore (voir section cache).

Premier build reproductible

Un build reproductible signifie : même Containerfile → même image, demain comme dans 6 mois.

Règle 1 : pinner la version de base

# ❌ Mauvais : "latest" peut changer demain
FROM python:latest

# ❌ Mauvais encore : "3.12" peut passer de 3.12.1 à 3.12.2
FROM python:3.12-alpine

# ✅ Bon : version exacte + digest pour la reproductibilité
FROM python:3.12.8-alpine3.21

Obtenir le digest

# Récupérer le digest d'une image
podman pull python:3.12.8-alpine3.21
podman inspect python:3.12.8-alpine3.21 --format '{{.Digest}}'
# sha256:abc123...

Pour un build 100% reproductible, utilisez le digest :

FROM python@sha256:abc123...

Notre premier Containerfile

• Répertoiremon-api/

  • Containerfile
  • requirements.txt
  • Répertoireapp/

    • init .py
    • main.py

Containerfile

FROM python:3.12.8-alpine3.21

LABEL org.opencontainers.image.title="Mon API"
LABEL org.opencontainers.image.version="1.0.0"

WORKDIR /app

# Copier tout et installer
COPY . .
RUN pip install --no-cache-dir -r requirements.txt

# Utilisateur non-root
RUN adduser -D appuser
USER appuser

EXPOSE 8000
CMD ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0"]

Construire et mesurer

1. Construire l’image

   time podman build -t mon-api:v1-naive .

   Notez le temps de build et la taille.

2. Mesurer la taille

   podman images | grep mon-api

   Résultat

   localhost/mon-api   v1-naive   abc123   30 seconds ago   287 MB

3. Voir les layers

   podman image history mon-api:v1-naive

4. Tester

   podman run --rm -p 8000:8000 mon-api:v1-naive
   # Dans un autre terminal: curl http://localhost:8000

Constat : 287 MB et 45 secondes de build. On peut faire beaucoup mieux.

Le vrai levier : le cache

Le cache est l’optimisation la plus importante. Un build bien caché passe de 2 min à 10 sec.

Comment le cache fonctionne

Podman met en cache chaque instruction (chaque RUN, COPY, etc. crée un “layer”). Si une instruction n’a pas changé, le layer en cache est réutilisé.

Mais : dès qu’un layer change, tous les layers suivants sont invalidés.

L’erreur classique : tout copier trop tôt

# ❌ Cache invalidé à chaque modification de code
FROM python:3.12.8-alpine3.21
WORKDIR /app
COPY . .                           # ← Change à chaque commit
RUN pip install -r requirements.txt  # ← Rebuild 100% du temps !

La solution : séparer dépendances et code

# ✅ Dépendances installées une seule fois
FROM python:3.12.8-alpine3.21
WORKDIR /app

# 1. Copier UNIQUEMENT les fichiers de dépendances
COPY requirements.txt .

# 2. Installer (en cache tant que requirements.txt ne change pas)
RUN pip install --no-cache-dir -r requirements.txt

# 3. Copier le code (change souvent, mais pip est déjà fait)
COPY . .

CMD ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0"]

Mesurer l’impact

# Premier build (cold cache)
time podman build --no-cache -t mon-api:v2-cache .
# → 45 secondes

# Modifier un fichier Python
echo "# comment" >> app/main.py

# Deuxième build (warm cache)
time podman build -t mon-api:v2-cache .
# → 3 secondes ! (pip install est en cache)

Le fichier .containerignore

Excluez du contexte tout ce qui n’est pas nécessaire au build :

.containerignore

# Contrôle de version
.git/
.gitignore

# Fichiers de développement
*.md
README*
docs/
tests/

# Environnements virtuels (installés dans l'image)
.venv/
venv/
__pycache__/
*.pyc

# Secrets et config locale
.env
.env.*
secrets/
*.key
*.pem

# Fichiers de build
Containerfile*
.containerignore
.dockerignore

Mesurer l’impact :

# Avant .containerignore
du -sh mon-api/
# 500 MB (avec .venv et .git)

# Après .containerignore (effectif dans le build)
tar -cvf - --exclude-from=.containerignore . | wc -c
# 50 KB

Quand utiliser —no-cache

--no-cache est un outil de diagnostic, pas un mode normal.

Situation	Utilisez
Build de développement	Cache normal
CI/CD répétitif	Cache normal
”Mon build semble buggé”	--no-cache pour debug
Image finale avant release	--no-cache (optionnel)

Glissez pour voir

Multi-stage : le standard

Le multi-stage build sépare l’environnement de compilation de l’environnement d’exécution. C’est le pattern standard pour les applications compilées.

Le problème : images obèses

# Image de développement = tout installé
FROM python:3.12-slim

RUN apt-get update && apt-get install -y \
    gcc libpq-dev  # Nécessaires au build seulement

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
CMD ["python", "app.py"]

Taille : 400 MB (gcc et libpq-dev inclus, inutiles au runtime).

La solution : multi-stage

Containerfile

# Stage 1: Builder (avec outils de compilation)
FROM python:3.12.8-alpine3.21 AS builder

RUN apk add --no-cache gcc musl-dev libffi-dev

WORKDIR /install
COPY requirements.txt .

# Installer dans un prefix isolé
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt


# Stage 2: Runtime (minimal)
FROM python:3.12.8-alpine3.21 AS runtime

# Copier UNIQUEMENT les packages installés
COPY --from=builder /install /usr/local

WORKDIR /app
COPY app/ ./app/

# Utilisateur non-root
RUN adduser -D appuser
USER appuser

EXPOSE 8000
CMD ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0"]

Construire et comparer

# Build multi-stage
podman build -t mon-api:v3-multistage .

# Comparer les tailles
podman images | grep mon-api

Résultat

localhost/mon-api   v3-multistage   def456   10 seconds ago   52 MB
localhost/mon-api   v1-naive        abc123   30 seconds ago   287 MB

Gain : 82% de réduction (287 MB → 52 MB).

Cibler un stage spécifique

Parfois vous voulez construire uniquement le stage builder (pour debug ou tests) :

# Construire uniquement le builder
podman build --target builder -t mon-api:builder .

# Le stage builder contient gcc, parfait pour les tests
podman run --rm mon-api:builder python -m pytest

Exemple multi-stage Go (binaire statique)

Containerfile

# Builder
FROM golang:1.22-alpine AS builder

WORKDIR /build
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 go build -o /app

# Runtime (FROM scratch = 0 MB)
FROM scratch

COPY --from=builder /app /app
ENTRYPOINT ["/app"]

Taille finale : 8 MB (juste le binaire statique).

Sécurité : secrets au build

Certains builds nécessitent des secrets : token npm, clé SSH pour un repo privé, credentials pip. Ne les mettez jamais en ARG ou ENV — ils seraient visibles dans l’historique de l’image.

Le problème : secrets brûlés dans l’image

# ❌ DANGEREUX : le token est dans l'image finale
ARG NPM_TOKEN
RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" >> ~/.npmrc
RUN npm install

# N'importe qui peut extraire le token
podman history mon-image --no-trunc | grep NPM_TOKEN

La solution : —secret

L’option --secret monte un fichier secret temporairement pendant le build, sans le persister dans l’image.

Containerfile

FROM node:20-alpine

WORKDIR /app
COPY package*.json ./

# Le secret est disponible UNIQUEMENT pendant ce RUN
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm install

COPY . .
CMD ["node", "index.js"]

# Créer le fichier secret
echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > /tmp/npmrc

# Build avec le secret
podman build --secret id=npmrc,src=/tmp/npmrc -t mon-app:secure .

Vérification : le secret n’est pas dans l’image.

podman history mon-app:secure --no-trunc | grep -i token
# (aucun résultat)

Exemples de secrets au build

npm

RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm install

podman build --secret id=npmrc,src=$HOME/.npmrc .

pip

RUN --mount=type=secret,id=pip,target=/root/.pip/pip.conf \
    pip install -r requirements.txt

podman build --secret id=pip,src=$HOME/.pip/pip.conf .

SSH (git clone)

RUN --mount=type=ssh \
    git clone git@github.com:private/repo.git

eval $(ssh-agent)
ssh-add ~/.ssh/id_ed25519
podman build --ssh default .

Formats d’image : OCI vs Docker

Podman produit des images au format OCI par défaut. C’est le format standard, supporté par tous les registries modernes.

Format	Default Podman	Compatible
OCI	✅	Tous registries modernes
Docker	Non	Legacy, Docker Hub

Glissez pour voir

Quand forcer un format

# Format OCI (défaut)
podman build --format oci -t mon-image:oci .

# Format Docker (compatibilité legacy)
podman build --format docker -t mon-image:docker .

Règle : gardez OCI sauf si vous avez un problème de compatibilité spécifique.

Publier proprement

L’objectif : l’image est poussée vers un registry et vous avez conservé son digest (identifiant immuable).

Workflow complet

1. Tag sémantique

   # Tag de développement
   podman tag mon-api:v3-multistage mon-api:1.0.0
   podman tag mon-api:v3-multistage mon-api:1.0
   podman tag mon-api:v3-multistage mon-api:1
   podman tag mon-api:v3-multistage mon-api:latest

2. Tag pour le registry

   podman tag mon-api:1.0.0 registry.example.com/team/mon-api:1.0.0

3. Authentification

   podman login registry.example.com

4. Push

   podman push registry.example.com/team/mon-api:1.0.0

5. Récupérer le digest

   podman inspect registry.example.com/team/mon-api:1.0.0 \
     --format '{{.Digest}}'

   Résultat

   sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

6. Documenter

   Conservez le digest dans votre documentation de release :

   Release 1.0.0
   Image: registry.example.com/team/mon-api:1.0.0
   Digest: sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Tags vs Digests

	Tags	Digests
Mutable	Oui (:latest peut changer)	Non (identifiant crypto)
Lisible	Oui (:1.0.0)	Non (sha256:abc...)
Traçable	Non	Oui (SBOM, signatures)

Glissez pour voir

Règle : utilisez les tags pour la lisibilité, conservez les digests pour la traçabilité.

Push vers différents registries

Docker Hub

podman login docker.io
podman tag mon-api:1.0.0 docker.io/monuser/mon-api:1.0.0
podman push docker.io/monuser/mon-api:1.0.0

GitHub Container Registry

echo $GITHUB_TOKEN | podman login ghcr.io -u USERNAME --password-stdin
podman tag mon-api:1.0.0 ghcr.io/monuser/mon-api:1.0.0
podman push ghcr.io/monuser/mon-api:1.0.0

Registry privé

podman login registry.example.com
podman tag mon-api:1.0.0 registry.example.com/team/mon-api:1.0.0
podman push registry.example.com/team/mon-api:1.0.0

Options avancées (cas particuliers)

Ces options sont utiles dans des cas spécifiques. Ne les utilisez pas par défaut.

—squash : fusionner les layers

--squash fusionne tous les layers en un seul.

Avantage	Inconvénient
Image plus petite (un seul layer)	Perd l’historique des layers
Pas d’artefacts de build visibles	Cache inutilisable pour builds incrémentaux
	Incompatible avec SBOM par layer

Glissez pour voir

# Squash tout
podman build --squash -t mon-image:squashed .

# Squash uniquement les layers ajoutés (garde le base layer)
podman build --squash-all -t mon-image:all-squashed .

Quand utiliser : si la traçabilité des layers n’est pas importante et que vous voulez une image minimale.

—layers : contrôler la création de layers

# Créer un layer par instruction (défaut)
podman build --layers -t mon-image:layered .

# Tout dans un seul layer (comme --squash mais différent internement)
podman build --layers=false -t mon-image:single .

—pull : contrôler le téléchargement de l’image de base

# Pull uniquement si l'image n'existe pas localement (défaut)
podman build --pull=missing -t mon-image .

# Toujours pull (pour avoir la dernière version)
podman build --pull=always -t mon-image .

# Jamais pull (utiliser le cache local)
podman build --pull=never -t mon-image .

Dépannage

Problèmes courants

Symptôme	Cause	Solution
COPY failed: file not found	Fichier hors contexte ou dans .containerignore	Vérifier le chemin et .containerignore
Build très lent	Contexte trop gros	Ajouter .containerignore
Cache jamais utilisé	Ordre des instructions	Mettre les deps avant le code
Image trop grosse	Pas de multi-stage	Utiliser multi-stage
Secret visible dans history	ARG/ENV pour secrets	Utiliser --secret
Push échoue	Pas authentifié	podman login

Glissez pour voir

Commandes de diagnostic

# Voir les logs détaillés
podman build --log-level debug -t mon-image .

# Voir la taille de chaque layer
podman image history mon-image:1.0 --no-trunc

# Vérifier le contexte envoyé
tar -cvf - . 2>&1 | head -20

# Analyser le contenu de l'image
podman run --rm -it mon-image:1.0 sh

# Vérifier qu'un secret n'est pas dans l'image
podman history mon-image:1.0 --no-trunc | grep -i secret

Le cache ne fonctionne pas

Symptôme : chaque build refait tout.

Diagnostic :

# Voir quel layer invalide le cache
podman build -t test . 2>&1 | grep -E "(STEP|Using cache|COMMIT)"

Causes fréquentes :

1. COPY . . trop tôt
2. Fichiers qui changent toujours dans le contexte (.git/, logs)
3. --no-cache utilisé par erreur

Lab : construire une image de A à Z

Objectif : construire une API FastAPI optimisée et la publier.

1. Créer le projet

   mkdir -p ~/lab-build/app && cd ~/lab-build

   app/main.py

   from fastapi import FastAPI
   
   app = FastAPI()
   
   @app.get("/")
   def read_root():
       return {"message": "Hello from optimized image!"}

   requirements.txt

   fastapi==0.115.0
   uvicorn[standard]==0.32.0

2. Build naïf (baseline)

   Containerfile.naive

   FROM python:3.12-slim
   WORKDIR /app
   COPY . .
   RUN pip install -r requirements.txt
   CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0"]

   time podman build -f Containerfile.naive -t api:naive .
   podman images | grep api

   Notez : taille et temps de build.

3. Build optimisé (multi-stage + cache)

   Containerfile

   # Builder
   FROM python:3.12.8-alpine3.21 AS builder
   WORKDIR /install
   COPY requirements.txt .
   RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
   
   # Runtime
   FROM python:3.12.8-alpine3.21
   COPY --from=builder /install /usr/local
   WORKDIR /app
   COPY app/ ./app/
   RUN adduser -D appuser && chown -R appuser /app
   USER appuser
   EXPOSE 8000
   CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0"]

   time podman build -t api:optimized .
   podman images | grep api

4. Mesurer le gain cache

   # Modifier le code
   echo "# comment" >> app/main.py
   
   # Rebuild (devrait être rapide)
   time podman build -t api:optimized .

   Le rebuild devrait prendre < 5 secondes (pip en cache).

5. Publier (optionnel)

   # Tag
   podman tag api:optimized registry.example.com/demo/api:1.0.0
   
   # Push
   podman login registry.example.com
   podman push registry.example.com/demo/api:1.0.0
   
   # Digest
   podman inspect registry.example.com/demo/api:1.0.0 --format '{{.Digest}}'

Résultats attendus :

Métrique	Naïf	Optimisé	Gain
Taille	~300 MB	~50 MB	-83%
Build initial	45 sec	30 sec	-33%
Rebuild (code change)	45 sec	3 sec	-93%

Glissez pour voir

À retenir

1. podman build utilise Buildah en interne — stockage partagé, sans démon
2. Pinner les versions : python:3.12.8-alpine3.21 pas python:latest
3. Cache = ordre des instructions : dépendances avant code
4. .containerignore : exclure .git/, .venv/, node_modules/
5. Multi-stage : séparer builder (avec gcc) et runtime (sans)
6. Secrets : utiliser --secret, jamais ARG/ENV
7. Publier : tag + push + conserver le digest
8. Squash : cas particulier, pas une best practice universelle

Prochaines étapes

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

Skopeo Copiez et inspectez vos images entre registries.

Buildah — Builds avancés Workflow from/run/commit, builds sans Containerfile.

Pods Podman Regroupez plusieurs conteneurs dans un pod.

×

📖 Voir la documentation →