Comment migrer de Docker Compose à Kubernetes pour vos projets open source en 7 étapes

Docker Compose a révolutionné la façon dont les développeurs lancent des stacks multi-conteneurs en local. Un docker compose up et votre base de données, votre API, votre frontend et votre worker Redis démarrent en quelques secondes. Mais quand votre projet open source passe du laptop à la production — quand vous devez gérer du scaling, des rolling updates, des health checks avancés, et des dizaines de réplicas — Docker Compose atteint ses limites. C'est à ce moment que la migration vers Kubernetes s'impose.

Ce guide est né de notre expérience avec des équipes de développeurs freelances à Paris, Lyon, Nantes et Toulouse qui ont migré des projets open source de Docker Compose vers Kubernetes en production. Nous avons identifié 7 étapes qui couvrent l'intégralité du processus — de l'audit initial à la mise en place du monitoring — avec des exemples de code, des pièges à éviter, et des outils open source à chaque étape.

Que vous soyez un freelance DevOps migrant le projet d'un client, un mainteneur open source qui veut offrir un déploiement Kubernetes à sa communauté, ou une PME française qui passe à l'échelle, ce guide vous donne la marche à suivre complète.

Etape 1 : Auditer votre stack Docker Compose

Avant d'écrire la moindre ligne de YAML Kubernetes, commencez par un audit complet de votre docker-compose.yml. Cette étape est souvent négligée, et c'est la première source d'échec dans les migrations. L'objectif est d'identifier précisément ce que fait votre stack Docker Compose et ce qui nécessite un traitement spécial lors de la migration.

Commencez par lister tous vos services et leurs dépendances. Chaque service dans votre docker-compose.yml deviendra un Deployment Kubernetes (pour les services sans état) ou un StatefulSet (pour les bases de données et les services avec stockage persistant). Les depends_on de Docker Compose n'ont pas d'équivalent direct dans Kubernetes — Kubernetes ne garantit pas l'ordre de démarrage des Pods. Vous devrez gérer les dépendances via des init containers ou des readiness probes qui attendent que les services dépendants soient disponibles.

Identifiez ensuite les trois catégories de données sensibles. Les variables d'environnement définies dans environment ou .env deviendront des ConfigMaps (pour les valeurs non sensibles) ou des Secrets Kubernetes (pour les mots de passe, tokens, et clés API). Les volumes montés deviendront des PersistentVolumeClaims. Et les ports exposés deviendront des Services Kubernetes de type ClusterIP (interne) ou LoadBalancer / Ingress (externe).

Voici une checklist pratique pour l'audit. Lisez votre docker-compose.yml ligne par ligne et notez pour chaque service : le type (stateless ou stateful), les volumes (locaux ou nommés), les ports (internes ou exposés), les variables d'environnement (sensibles ou non), les health checks (s'ils existent), et les contraintes de ressources (limites CPU/mémoire). Ce document deviendra votre feuille de route pour la migration.

Etape 2 : Convertir avec Kompose — le point de départ

Kompose est l'outil officiel recommandé par la communauté Kubernetes pour convertir des fichiers docker-compose.yml en manifestes Kubernetes. L'installation est simple — un binaire unique disponible sur Linux, macOS et Windows. La conversion de base se fait en une commande.

# Installer Kompose
curl -L https://github.com/kubernetes/kompose/releases/latest/download/kompose-linux-amd64 -o kompose
chmod +x kompose && sudo mv kompose /usr/local/bin/

# Convertir votre docker-compose.yml
cd /chemin/vers/votre/projet
kompose convert

# Resultat : un fichier YAML par service
# api-deployment.yaml, api-service.yaml
# frontend-deployment.yaml, frontend-service.yaml
# postgres-deployment.yaml, postgres-service.yaml
# redis-deployment.yaml, redis-service.yaml

Kompose génère un Deployment et un Service pour chaque service de votre docker-compose.yml. C'est un excellent point de départ, mais il ne faut pas prendre la sortie de Kompose comme un résultat final. Plusieurs éléments nécessitent un ajustement manuel. Les depends_on sont ignorés. Les volumes locaux ne sont pas correctement mappés vers des PersistentVolumeClaims. Les fichiers .env ne sont pas automatiquement convertis en Secrets. Et les health checks de Docker Compose (healthcheck) ne sont pas toujours traduits en livenessProbe et readinessProbe Kubernetes.

Notre recommandation : utilisez Kompose pour générer la structure de base, puis passez en revue chaque fichier généré manuellement. C'est un travail d'une à deux heures pour un projet de 5 services, mais il évite des heures de débogage en production. Les équipes freelances que nous accompagnons à Paris et Lyon ont toutes confirmé que cette étape de revue manuelle est la clé d'une migration réussie.

Etape 3 : Gérer les secrets et les ConfigMaps

Dans Docker Compose, les secrets sont généralement stockés dans des fichiers .env ou directement dans les variables environment du docker-compose.yml. En Kubernetes, vous disposez de deux mécanismes dédiés : les ConfigMaps pour les configurations non sensibles, et les Secrets pour les données sensibles (mots de passe, tokens, clés).

Créez un ConfigMap pour les variables d'environnement publiques — URL de l'API, nom de l'application, niveau de logs, feature flags. Créez un Secret pour tout ce qui est confidentiel — mot de passe PostgreSQL, clé API, token d'authentification. Les Secrets Kubernetes sont encodés en base64 (pas chiffrés par défaut), donc activez le chiffrement au repos dans etcd si votre cluster le supporte, ou utilisez un outil comme Sealed Secrets (Bitnami) ou SOPS (Mozilla) pour chiffrer les Secrets avant de les stocker dans Git.

# ConfigMap pour les variables non sensibles
apiVersion: v1
kind: ConfigMap
metadata:
  name: api-config
data:
  NODE_ENV: "production"
  LOG_LEVEL: "info"
  API_PORT: "3000"

---
# Secret pour les credentials (valeurs en base64)
apiVersion: v1
kind: Secret
metadata:
  name: api-secrets
type: Opaque
data:
  DATABASE_URL: cG9zdGdyZXM6Ly91c2VyOnBhc3NAcG9zdGdyZXM6NTQzMi9teWRi
  REDIS_URL: cmVkaXM6Ly9yZWRpczo2Mzc5

Un piège courant : ne committez jamais vos fichiers Secret en clair dans votre dépôt Git. Utilisez Sealed Secrets, SOPS, ou un gestionnaire de secrets externe (HashiCorp Vault, AWS Secrets Manager, Google Secret Manager) pour gérer le cycle de vie de vos secrets de manière sécurisée. Comme nous l'avons détaillé dans notre article sur la sécurisation de la supply chain, les secrets exposés dans les dépôts Git sont la première cause de compromission d'infrastructure.

Etape 4 : Configurer le stockage persistant

Le stockage est l'aspect le plus délicat de la migration Docker Compose vers Kubernetes. Dans Docker Compose, un volume se déclare en une ligne : ./data:/var/lib/postgresql/data. En Kubernetes, vous devez comprendre trois concepts : les PersistentVolumes (PV), les PersistentVolumeClaims (PVC), et les StorageClasses.

Un PersistentVolume représente un espace de stockage physique dans le cluster — un disque SSD sur GCP, un volume EBS sur AWS, un NFS share on-premises. Un PersistentVolumeClaim est une demande de stockage faite par un Pod — « j'ai besoin de 10 Go de stockage SSD ». La StorageClass définit le type de stockage disponible et permet le provisionnement dynamique : quand un PVC est créé, Kubernetes provisionne automatiquement un PV correspondant.

Pour les bases de données (PostgreSQL, MySQL, MongoDB), utilisez des StatefulSets plutôt que des Deployments. Les StatefulSets garantissent un nom stable pour chaque Pod, un ordre de démarrage prévisible, et un lien persistant entre chaque Pod et son PVC. Chaque réplica de la base de données conserve son volume même en cas de redémarrage, ce qui est essentiel pour l'intégrité des données.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
spec:
  serviceName: postgres
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
      - name: postgres
        image: postgres:16-alpine
        ports:
        - containerPort: 5432
        envFrom:
        - secretRef:
            name: postgres-secrets
        volumeMounts:
        - name: postgres-data
          mountPath: /var/lib/postgresql/data
  volumeClaimTemplates:
  - metadata:
      name: postgres-data
    spec:
      accessModes: ["ReadWriteOnce"]
      storageClassName: standard
      resources:
        requests:
          storage: 20Gi

Etape 5 : Configurer le networking et les Services

Le networking est l'un des changements les plus significatifs entre Docker Compose et Kubernetes. Dans Docker Compose, tous les services partageant un même network peuvent se joindre par leur nom de service. Kubernetes fonctionne différemment : chaque groupe de Pods est exposé via un Service, qui fournit une adresse DNS stable et un load balancing automatique entre les réplicas.

Il existe quatre types de Services Kubernetes. Le ClusterIP (par défaut) crée une IP interne accessible uniquement depuis le cluster — c'est l'équivalent du networking interne de Docker Compose. Le NodePort expose le service sur un port de chaque noeud du cluster — utile pour le développement mais déconseillé en production. Le LoadBalancer provisionne un load balancer externe (sur les clouds publics GKE, EKS, AKS) — pratique mais coûteux si vous avez beaucoup de services. Et l'Ingress est la solution recommandée pour la production : un point d'entrée unique qui route le trafic vers les bons services basé sur les noms de domaine et les chemins URL.

Pour un projet open source typique avec un frontend, une API, et un service de base de données, la configuration idéale est : un Ingress pour le trafic externe (avec TLS via cert-manager), des Services ClusterIP pour la communication interne entre les Pods, et des NetworkPolicies pour restreindre le trafic entre les namespaces. La base de données ne devrait jamais être accessible depuis l'extérieur du cluster — contrairement à Docker Compose où le ports: "5432:5432" expose parfois la base de données au réseau local par inadvertance.

Etape 6 : Adapter votre pipeline CI/CD

La migration vers Kubernetes implique de repenser votre pipeline CI/CD. Avec Docker Compose, le déploiement se résumait souvent à un ssh + docker compose pull + docker compose up -d. En Kubernetes, vous déployez des manifestes YAML — et l'approche recommandée est le GitOps : vos manifestes Kubernetes vivent dans un dépôt Git, et un outil comme ArgoCD ou Flux synchronise automatiquement le cluster avec l'état déclaré dans le dépôt.

Pour un projet open source, nous recommandons l'architecture suivante : un dépôt applicatif contenant le code source et les Dockerfiles, et un dépôt infra (ou un répertoire k8s/ dans le même dépôt) contenant les manifestes Kubernetes ou les Helm charts. Le pipeline CI (GitHub Actions, GitLab CI) build l'image Docker, la push vers un registre (GitHub Container Registry, Docker Hub), puis met à jour le tag d'image dans le dépôt infra. ArgoCD détecte le changement et déploie la nouvelle version.

Si vous utilisez Helm, chaque environnement (dev, staging, production) est défini par un fichier values-{env}.yaml distinct. Le même chart Helm est utilisé partout, seules les valeurs changent — nombre de réplicas, ressources allouées, URLs de bases de données, feature flags. L'alternative est Kustomize, intégré nativement dans kubectl, qui fonctionne par overlays : une base commune et des patches spécifiques à chaque environnement. Le choix entre Helm et Kustomize dépend de la complexité de votre projet — Helm est plus puissant pour les projets distribués en tant que package, Kustomize est plus simple pour les projets internes.

# Structure Helm recommandee
my-app/
  Chart.yaml
  values.yaml          # valeurs par defaut
  values-dev.yaml      # overrides dev
  values-staging.yaml  # overrides staging
  values-prod.yaml     # overrides production
  templates/
    deployment.yaml
    service.yaml
    ingress.yaml
    configmap.yaml
    secret.yaml
    hpa.yaml

# Deploiement
helm upgrade --install my-app ./my-app \
  -f values-prod.yaml \
  --namespace production \
  --set image.tag=v1.2.3

Etape 7 : Mettre en place le monitoring et l'observabilité

La dernière étape — et la plus souvent négligée — est la mise en place d'une stack de monitoring adaptée à Kubernetes. Docker Compose offre une visibilité limitée : docker compose logs et docker stats suffisent pour le développement local. En production sur Kubernetes, vous gérez des dizaines de Pods distribués sur plusieurs noeuds, avec des redémarrages automatiques, du scaling horizontal, et des rolling updates. Sans monitoring, vous naviguez à l'aveugle.

La stack open source de référence pour le monitoring Kubernetes est Prometheus + Grafana + Loki. Prometheus collecte les métriques (CPU, mémoire, requêtes HTTP, latence) via un modèle pull — il interroge régulièrement les endpoints /metrics de vos applications. Grafana fournit les dashboards de visualisation. Loki agrège les logs de tous les Pods dans un système centralisé. L'installation se fait via le Helm chart kube-prometheus-stack qui déploie Prometheus, Grafana, Alertmanager, et les exporters de métriques Kubernetes en une seule commande.

# Installer la stack monitoring complete
helm repo add prometheus-community \
  https://prometheus-community.github.io/helm-charts
helm repo update

helm install monitoring prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --create-namespace \
  --set grafana.adminPassword=votre-mot-de-passe \
  --set prometheus.prometheusSpec.retention=30d

# Installer Loki pour les logs
helm install loki grafana/loki-stack \
  --namespace monitoring \
  --set promtail.enabled=true

Configurez ensuite des alertes pour les scénarios critiques : Pod en CrashLoopBackOff depuis plus de 5 minutes, PersistentVolume à plus de 85% de capacité, temps de réponse de l'API supérieur à 2 secondes (p95), nombre de réplicas inférieur au minimum défini dans le HPA. Ces alertes s'envoient via Alertmanager vers Slack, PagerDuty, ou email. Pour les équipes freelances qui gèrent plusieurs projets clients, un canal Slack par cluster avec des alertes bien calibrées est la configuration qui fonctionne le mieux selon notre expérience avec des équipes à Nantes et Toulouse.

Enfin, intégrez des probes dans vos Deployments Kubernetes. La livenessProbe vérifie que le conteneur est vivant et le redémarre s'il ne répond plus. La readinessProbe vérifie que le conteneur est prêt à recevoir du trafic — Kubernetes retire le Pod du Service si la probe échoue, assurant des rolling updates sans downtime. La startupProbe gère les applications lentes au démarrage pour éviter les faux positifs de la livenessProbe.

Conclusion : quand Docker Compose reste le bon choix

Cette migration en 7 étapes couvre l'essentiel du processus, mais il faut être honnête : Kubernetes n'est pas toujours la bonne réponse. Si votre projet open source tourne sur 2-3 conteneurs, que vous n'avez pas besoin de scaling automatique, et que votre déploiement se résume à un serveur unique, Docker Compose reste l'outil le plus simple et le plus adapté. La complexité opérationnelle de Kubernetes — gestion du cluster, mises à jour, monitoring, sécurité — est un coût réel qui ne se justifie que quand les bénéfices (scaling, résilience, déploiements zero-downtime) le compensent.

Pour les projets qui franchissent le seuil — plus de 5 services, besoin de haute disponibilité, déploiement multi-environnement — la migration vers Kubernetes est un investissement qui se rentabilise en quelques mois. Les 7 étapes décrites dans ce guide vous donnent une feuille de route concrète, avec les outils open source à utiliser à chaque étape et les pièges à éviter. Et si vous avez besoin d'accompagnement, nos experts DevOps freelances ont déjà réalisé cette migration pour des dizaines de projets open source en production.

FAQ — Questions fréquentes