🔧 Référence & Troubleshooting

Problèmes courants

Guide des problèmes les plus fréquents

Cette section répertorie les problèmes les plus couramment rencontrés par les participants à la formation, avec leurs solutions détaillées et des conseils de prévention.

Jour 1 - Problèmes de base

1. Gitea ne démarre pas après l'installation

Problème :

Code
 
docker-compose up -d
# Gitea container exits immediately

Causes possibles :

Permissions incorrectes sur les volumes
Port 3000 déjà utilisé
Base de données non accessible

Solution étape par étape :

Code
 
# 1. Vérifier les ports occupés
sudo netstat -tlnp | grep :3000
# Si occupé, changer le port dans docker-compose.yml

# 2. Corriger les permissions
sudo chown -R 1000:1000 ./gitea
chmod -R 755 ./gitea

# 3. Vérifier les logs
docker-compose logs gitea

# 4. Recréer les conteneurs
docker-compose down -v
docker-compose up -d

# 5. Attendre l'initialisation complète
docker-compose logs -f gitea
# Attendre "Listen: http://0.0.0.0:3000"

Prévention :

Toujours vérifier les ports avant l'installation
Utiliser des répertoires avec les bonnes permissions dès le début

2. Actions Gitea non visibles ou non fonctionnelles

Problème :

Code
 
Pas d'onglet "Actions" dans l'interface
Les workflows ne se déclenchent pas

Causes possibles :

Actions non activées dans la configuration
Runner non configuré
Fichiers workflow mal placés

Solution :

Code
 
# 1. Vérifier la configuration Gitea
# Dans l'interface admin : Site Administration > Configuration
# Chercher [actions] ENABLED = true

# 2. Activer les actions si nécessaire
docker exec -it gitea-container sh
vi /data/gitea/conf/app.ini

Code
 
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://gitea.com

Code
 
# 3. Redémarrer Gitea
docker-compose restart gitea

# 4. Vérifier le runner
docker-compose logs gitea-runner

# 5. Vérifier la structure des workflows
ls -la .gitea/workflows/
# Les fichiers doivent avoir l'extension .yml ou .yaml

Prévention :

Utiliser les docker-compose fournis dans la formation
Vérifier la configuration avant de commencer les ateliers

3. Premier workflow échoue avec des erreurs de permissions

Problème :

Code
 
Error: buildx failed with: permission denied while trying to connect to the Docker daemon socket

Solution :

Code
 
# 1. Donner les permissions Docker au runner
docker exec -it gitea-runner sudo usermod -aG docker runner

# 2. Redémarrer le runner
docker-compose restart gitea-runner

# 3. Vérifier les permissions
docker exec -it gitea-runner groups runner
# Doit inclure "docker"

# 4. Tester Docker dans le runner
docker exec -it gitea-runner docker ps

Prévention :

Configurer les permissions dès l'installation du runner

Jour 2 - Problèmes intermédiaires

4. Docker Registry refuse les connexions

Problème :

Code
 
docker push localhost:5000/myapp:latest
# Error: Get "https://localhost:5000/": dial tcp: connection refused

Solution :

Code
 
# 1. Vérifier que le registry tourne
docker ps | grep registry
curl http://localhost:5000/v2/

# 2. Configurer Docker pour le registry insecure
sudo nano /etc/docker/daemon.json

Code
 
{
  "insecure-registries": ["localhost:5000"]
}

Code
 
# 3. Redémarrer Docker
sudo systemctl restart docker

# 4. Tester à nouveau
docker push localhost:5000/myapp:latest

Prévention :

Configurer les registries insecure dès le début
Vérifier la connectivité réseau entre conteneurs

5. Images Docker très lentes à build

Problème :

Code
 
Building takes 10+ minutes
npm install step is extremely slow

Solutions d'optimisation :

Code
 
# Dockerfile optimisé avec cache des layers
FROM node:18-alpine AS base
WORKDIR /app

# Copier seulement package*.json d'abord (cache layer)
COPY package*.json ./
RUN npm ci --only=production && npm cache clean --force

# Copier le reste du code
COPY . .

# Multi-stage pour réduire la taille finale
FROM node:18-alpine AS production
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

WORKDIR /app
COPY --from=base --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=base --chown=nodejs:nodejs /app .

USER nodejs
CMD ["npm", "start"]

Code
 
# Utiliser BuildKit pour de meilleures performances
export DOCKER_BUILDKIT=1
docker build --progress=plain .

# Nettoyer les caches régulièrement
docker builder prune -a

Prévention :

Utiliser .dockerignore approprié
Ordonner les layers par fréquence de changement
Utiliser des images base optimisées (alpine)

6. Kubernetes pods en "Pending" indéfiniment

Problème :

Code
 
kubectl get pods
# NAME     READY   STATUS    RESTARTS   AGE
# myapp    0/1     Pending   0          5m

Diagnostic :

Code
 
# 1. Vérifier les events
kubectl describe pod myapp

# 2. Vérifier les ressources des nodes
kubectl top nodes
kubectl describe nodes

# 3. Vérifier les quotas
kubectl describe quota

Solutions selon la cause :

Code
 
# Si manque de ressources sur les nodes
kubectl edit deployment myapp
# Réduire requests.cpu et requests.memory

# Si problème de scheduling (minikube)
minikube stop
minikube start --memory=4096 --cpus=4

# Si problème de permissions
kubectl get pv
kubectl get pvc
# Vérifier les permissions des volumes persistants

Prévention :

Toujours définir des resource requests réalistes
Monitorer les ressources du cluster régulièrement

7. Services Kubernetes inaccessibles

Problème :

Code
 
curl http://myapp-service/health
# curl: (7) Failed to connect to myapp-service port 80

Diagnostic et solution :

Code
 
# 1. Vérifier que le service existe
kubectl get svc myapp-service

# 2. Vérifier les endpoints
kubectl get endpoints myapp-service
# Si pas d'endpoints, problème de selector/labels

# 3. Vérifier les labels des pods
kubectl get pods --show-labels
kubectl describe svc myapp-service

# 4. Tester depuis un pod de debug
kubectl run debug --image=busybox -it --rm -- sh
# Puis dans le pod:
nslookup myapp-service
telnet myapp-service 80

# 5. Si les labels ne correspondent pas
kubectl label pods myapp-pod app=myapp

Prévention :

Toujours vérifier que les labels des pods correspondent aux selectors des services
Tester la connectivité après chaque déploiement

Jour 3 - Problèmes avancés

8. Argo CD applications restent "OutOfSync"

Problème :

Code
 
argocd app get myapp
# Status: OutOfSync
# Health: Unknown

Solutions selon le type de problème :

Code
 
# 1. Problème de credentials Git
argocd repo list
argocd repo add https://github.com/user/repo.git --username user --password token

# 2. Problème de path ou de branch
argocd app set myapp --path correct/path --revision main

# 3. Synchronisation forcée
argocd app sync myapp --force --replace

# 4. Problème de permissions sur le cluster
kubectl auth can-i create pods --as=system:serviceaccount:argocd:argocd-application-controller

# 5. Vérifier les logs du controller
kubectl logs -n argocd deployment/argocd-application-controller

Prévention :

Tester l'accès aux repositories avant de créer les applications
Utiliser des chemins absolus dans les configurations
Vérifier les permissions RBAC d'Argo CD

9. CDK8s génère des manifests invalides

Problème :

Code
 
npm run synth
kubectl apply -f dist/
# error validating data: ValidationError(Deployment.spec.template)

Diagnostic :

Code
 
# 1. Vérifier les imports CDK8s
cdk8s import --help
ls imports/

# 2. Valider individuellement
kubectl apply --dry-run=client -f dist/myapp.k8s.yaml

# 3. Vérifier les types TypeScript
npm run build

Solutions :

Code
 
// Problème fréquent: mauvaise conversion des ports
// ❌ Incorrect
ports: [{ port: "3000" }]

// ✅ Correct
ports: [{ port: 3000 }]

// Problème fréquent: resources mal typées
// ❌ Incorrect
resources: {
  requests: { cpu: 100, memory: 128 }
}

// ✅ Correct  
resources: {
  requests: { cpu: "100m", memory: "128Mi" }
}

Prévention :

Utiliser des tests unitaires pour les constructs CDK8s
Valider les manifests générés avec kubectl --dry-run

10. Pipeline GitOps ne se déclenche pas

Problème :

Code
 
Code pushed → CI/CD works → CDK8s works → GitOps repo updated
But Argo CD doesn't sync

Diagnostic :

Code
 
# 1. Vérifier les webhooks Git
curl -H "Authorization: token $TOKEN" \
  http://gitea:3000/api/v1/repos/user/gitops-config/hooks

# 2. Vérifier la connectivité Argo CD → Git
kubectl exec -it -n argocd deployment/argocd-repo-server -- \
  git ls-remote https://gitea:3000/user/gitops-config.git

# 3. Vérifier les logs Argo CD
kubectl logs -n argocd deployment/argocd-application-controller -f

# 4. Forcer une synchronisation manuelle
argocd app sync myapp

Solutions :

Code
 
# 1. Configurer le webhook correctement
# Dans Gitea: Repository Settings → Webhooks → Add Webhook
# URL: http://argocd-server.argocd.svc.cluster.local/api/webhook
# Content-Type: application/json
# Events: Push, Pull Request

# 2. Vérifier la configuration du repository dans Argo CD
argocd repo add http://gitea:3000/user/gitops-config.git \
  --username user --password token

# 3. Activer la synchronisation automatique
argocd app set myapp --sync-policy automated --auto-prune --self-heal

Prévention :

Tester les webhooks manuellement après configuration
Utiliser des URLs internes du cluster pour la communication inter-services

Problèmes de performance

11. Pipeline CI/CD très lent

Symptômes :

Build prend plus de 10 minutes
Tests traînent indéfiniment
Push vers le registry très lent

Solutions d'optimisation :

Code
 
# Optimisation du workflow Gitea Actions
name: Optimized CI/CD

on: [push, pull_request]

# Utiliser des caches
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    
    - name: Setup Node.js with cache
      uses: actions/setup-node@v4
      with:
        node-version: '20'
        cache: 'npm'  # Cache automatique des node_modules
    
    - name: Cache dependencies
      uses: actions/cache@v3
      with:
        path: ~/.npm
        key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    
    - name: Install dependencies
      run: npm ci --prefer-offline --no-audit
    
    # Paralléliser les étapes longues
    - name: Run tests in parallel
      run: npm test -- --maxWorkers=4 --passWithNoTests

  # Séparer build et test pour la parallélisation
  build:
    runs-on: ubuntu-latest
    steps:
    # ... steps de build

Code
 
# Optimisation Docker
# Utiliser des images plus petites et un registry local
docker pull node:18-alpine  # Plus petit que node:18
docker build --cache-from myregistry/app:latest .

Prévention :

Utiliser les caches appropriés dès le début
Profiler régulièrement les pipelines pour identifier les goulots

12. Cluster Kubernetes à court de ressources

Symptômes :

Pods évictés fréquemment
Nodes en état "Ready,SchedulingDisabled"
Applications qui traînent

Solutions :

Code
 
# 1. Diagnostic des ressources
kubectl top nodes
kubectl top pods --all-namespaces --sort-by=memory
kubectl describe nodes | grep -A 5 "Allocated resources"

# 2. Identifier les gourmands en ressources
kubectl get pods --all-namespaces -o custom-columns=NAME:.metadata.name,MEMORY:.status.containerStatuses[0].resources.requests.memory,CPU:.status.containerStatuses[0].resources.requests.cpu

# 3. Ajuster les limits et requests
kubectl edit deployment resource-hungry-app

Code
 
# Exemple d'optimisation des ressources
resources:
  requests:
    memory: "128Mi"  # Ce dont l'app a vraiment besoin
    cpu: "100m"
  limits:
    memory: "256Mi"  # Maximum absolu
    cpu: "500m"

Code
 
# 4. Nettoyer les ressources inutilisées
kubectl delete pods --field-selector=status.phase=Failed --all-namespaces
kubectl delete pods --field-selector=status.phase=Succeeded --all-namespaces

# 5. Configurer l'autoscaling
kubectl apply -f - <<EOF
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: myapp-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: myapp
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
EOF

Prévention :

Définir des resource requests/limits réalistes dès le début
Monitorer l'utilisation des ressources régulièrement
Utiliser l'autoscaling horizontal et vertical

Erreurs de sécurité courantes

13. Secrets exposés dans les logs

Problème :

Code
 
# Dans les logs Gitea Actions ou Kubernetes
echo "DATABASE_URL=postgresql://user:password@db/app"

Solutions immédiates :

Code
 
# 1. Révoquer immédiatement les credentials exposés
# Changer les mots de passe, régénérer les tokens

# 2. Nettoyer les logs
kubectl delete pods -l app=myapp  # Force restart et nouveaux logs

# 3. Utiliser les secrets appropriés
kubectl create secret generic db-secret \
  --from-literal=database-url="postgresql://user:newpassword@db/app"

Code
 
# Dans les workflows, utiliser les secrets
env:
  DATABASE_URL: ${{ secrets.DATABASE_URL }}  # ✅ Correct
  # DATABASE_URL: postgresql://user:pass@db  # ❌ Jamais ça !

Code
 
# Dans Kubernetes, utiliser secretRef
env:
- name: DATABASE_URL
  valueFrom:
    secretKeyRef:
      name: db-secret
      key: database-url

Prévention :

Ne jamais committer de secrets dans Git
Utiliser .gitignore pour les fichiers de configuration locaux
Scanner automatiquement les repos pour les secrets

14. Pods qui tournent en root

Problème :

Code
 
kubectl exec -it myapp-pod -- whoami
# root

Solution :

Code
 
# Dans les manifests Kubernetes
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        runAsGroup: 1000
        fsGroup: 1000
      containers:
      - name: myapp
        image: myapp:latest
        securityContext:
          runAsNonRoot: true
          readOnlyRootFilesystem: true
          allowPrivilegeEscalation: false
          capabilities:
            drop:
            - ALL

Code
 
# Dans le Dockerfile
FROM node:18-alpine

# Créer un utilisateur non-root
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

# Utiliser cet utilisateur
USER nodejs

# Le reste de votre Dockerfile

Prévention :

Utiliser des images de base non-root par défaut
Configurer les security contexts dès le début
Utiliser des policies de sécurité (Pod Security Standards)

Checklist de prévention

Avant de commencer un atelier

Tous les ports requis sont libres
Docker fonctionne et les permissions sont correctes
Assez d'espace disque disponible (minimum 10GB)
Connexion internet stable pour télécharger les images

Avant de passer au jour suivant

Tous les services du jour précédent fonctionnent
Les logs ne montrent pas d'erreurs critiques
Un backup des configurations importantes est fait
Les ressources système sont disponibles pour la suite

Après chaque modification importante

Tester dans un environnement isolé d'abord
Vérifier les logs après le déploiement
Valider que les services répondent correctement
Documenter les changements importants

Cette liste de problèmes courants vous aidera à éviter les pièges les plus fréquents et à résoudre rapidement les issues quand elles surviennent.

Last modified on August 25, 2025

Référence des commandes Ressources