🔧 Référence & Troubleshooting

Référence & Troubleshooting

Guide de dépannage complet

Cette section couvre les problèmes les plus fréquemment rencontrés lors de la mise en œuvre d'un pipeline CI/CD GitOps et leurs solutions.

Gitea et CI/CD

Problèmes d'installation Gitea

Gitea ne démarre pas

Symptômes :

Le conteneur Gitea se ferme immédiatement
Erreur "database connection failed"
Port 3000 inaccessible

Solutions :

Code
 
# Vérifier les logs du conteneur
docker logs gitea-container

# Problème de permissions sur le volume
sudo chown -R 1000:1000 /path/to/gitea/data

# Problème de base de données
docker exec -it gitea-db mysql -u root -p
# Vérifier que la base 'gitea' existe

# Recréer avec les bonnes permissions
docker-compose down
sudo rm -rf ./gitea
mkdir -p gitea/{data,config}
sudo chown -R 1000:1000 gitea/
docker-compose up -d

Actions Gitea ne se déclenchent pas

Symptômes :

Les workflows ne s'exécutent pas après un push
Pas d'onglet "Actions" visible

Solutions :

Code
 
# Vérifier que les Actions sont activées
# Dans l'interface admin Gitea : Site Administration > Configuration > Actions

# Vérifier les runners
docker logs gitea-runner

# Redémarrer le runner
docker restart gitea-runner

# Vérifier les permissions du fichier workflow
ls -la .gitea/workflows/
# Le fichier doit être lisible par tous

# Forcer un nouveau déclenchement
git commit --allow-empty -m "trigger: force workflow run"
git push

Problèmes de workflows

Workflow échoue avec "permission denied"

Symptômes :

Erreur lors de l'accès aux secrets
Impossible de push vers le registry
Échec des tests avec erreur de permissions

Solutions :

Code
 
# Vérifier les secrets dans le repository
# Settings > Actions > Secrets

# Vérifier les permissions du runner
docker exec -it gitea-runner whoami
docker exec -it gitea-runner groups

# Donner les permissions Docker au runner
docker exec -it gitea-runner sudo usermod -aG docker runner
docker restart gitea-runner

# Vérifier les tokens d'accès
curl -H "Authorization: token YOUR_TOKEN" \
  http://localhost:3000/api/v1/user

Timeout des workflows

Symptômes :

Workflow se termine par timeout
Étapes qui traînent indéfiniment

Solutions :

Code
 
# Ajouter des timeouts explicites
jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 30  # Timeout global du job
    steps:
    - name: Long running task
      run: |
        timeout 300 your-command  # 5 minutes max
      timeout-minutes: 10  # Timeout de l'étape

Docker Registry

Problèmes de connexion au registry

"Connection refused" vers le registry

Symptômes :

docker push échoue avec connection refused
Registry inaccessible depuis les workflows

Solutions :

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

# Vérifier les réseaux Docker
docker network ls
docker network inspect bridge

# Registry dans docker-compose
# S'assurer que les services peuvent communiquer
docker-compose exec app ping registry

# Ajouter --insecure-registry si pas de TLS
sudo systemctl edit docker.service

Code
 
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd --insecure-registry=localhost:5000

Code
 
sudo systemctl daemon-reload
sudo systemctl restart docker

Problèmes d'authentification

Symptômes :

"authentication required" même avec login
Secrets invalides dans les workflows

Solutions :

Code
 
# Tester l'auth manuellement
echo "testpassword" | docker login localhost:5000 -u testuser --password-stdin

# Vérifier le fichier htpasswd
cat auth/htpasswd
# Doit contenir les hash bcrypt

# Régénérer le fichier htpasswd
docker run --rm --entrypoint htpasswd \
  httpd:2 -Bbn testuser newpassword > auth/htpasswd

# Vérifier les secrets dans Gitea
# Ils doivent correspondre exactement au htpasswd

Registry plein ou lent

Symptômes :

Push très lent
Erreurs "no space left on device"
Images corrompues

Solutions :

Code
 
# Nettoyer les images orphelines
docker exec -it registry sh -c "rm -rf /var/lib/registry/docker/registry/v2/repositories/_*"

# Garbage collection du registry
docker exec -it registry registry garbage-collect /etc/docker/registry/config.yml

# Vérifier l'espace disque
df -h
docker system df

# Nettoyer le système Docker
docker system prune -a --volumes

Kubernetes

Problèmes de cluster

Pods en état "Pending"

Symptômes :

Pods restent en "Pending"
Pas de ressources suffisantes

Diagnostic :

Code
 
# Vérifier les events
kubectl describe pod <pod-name>
kubectl get events --sort-by=.metadata.creationTimestamp

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

# Vérifier les quotas
kubectl describe quota -n <namespace>
kubectl describe limitrange -n <namespace>

Solutions :

Code
 
# Ajuster les resource requests
kubectl edit deployment <deployment-name>

# Augmenter les ressources du cluster (minikube)
minikube stop
minikube start --memory=4096 --cpus=4

# Nettoyer les pods terminés
kubectl delete pods --field-selector=status.phase=Failed
kubectl delete pods --field-selector=status.phase=Succeeded

Pods en état "CrashLoopBackOff"

Symptômes :

Pods redémarrent en boucle
Application ne démarre pas

Diagnostic :

Code
 
# Voir les logs du container
kubectl logs <pod-name> --previous
kubectl logs <pod-name> -c <container-name>

# Décrire le pod pour voir les events
kubectl describe pod <pod-name>

# Se connecter au pod (si possible)
kubectl exec -it <pod-name> -- /bin/bash

Solutions :

Code
 
# Vérifier la configuration
kubectl get configmap <config-name> -o yaml
kubectl get secret <secret-name> -o yaml

# Vérifier les health checks
# Peut être trop agressifs pour le démarrage
kubectl edit deployment <deployment-name>
# Augmenter initialDelaySeconds et timeoutSeconds

# Vérifier les variables d'environnement
kubectl describe deployment <deployment-name>

Problèmes de réseau

Services inaccessibles

Symptômes :

Connexion refusée entre services
DNS ne résout pas les noms de service

Diagnostic :

Code
 
# Tester la résolution DNS
kubectl run debug --image=busybox -it --rm -- nslookup kubernetes.default

# Tester la connectivité
kubectl run debug --image=busybox -it --rm -- telnet <service-name> <port>

# Vérifier les endpoints
kubectl get endpoints <service-name>

# Vérifier les labels et selectors
kubectl describe service <service-name>
kubectl get pods --show-labels

Solutions :

Code
 
# Vérifier que les labels correspondent
kubectl label pods <pod-name> app=<app-label>

# Recréer le service si nécessaire
kubectl delete service <service-name>
kubectl expose deployment <deployment-name> --port=80 --target-port=8080

# Vérifier les NetworkPolicies
kubectl get networkpolicy
kubectl describe networkpolicy <policy-name>

Ingress non fonctionnel

Symptômes :

404 ou 502 via l'ingress
Pas d'adresse IP assignée

Diagnostic :

Code
 
# Vérifier l'ingress controller
kubectl get pods -n ingress-nginx

# Vérifier l'ingress
kubectl describe ingress <ingress-name>
kubectl get ingress

# Vérifier les logs de l'ingress controller
kubectl logs -n ingress-nginx deployment/ingress-nginx-controller

Solutions :

Code
 
# Installer nginx ingress controller (minikube)
minikube addons enable ingress

# Vérifier les annotations
kubectl annotate ingress <ingress-name> kubernetes.io/ingress.class=nginx

# Tester le service directement
kubectl port-forward service/<service-name> 8080:80

# Recréer l'ingress avec la bonne configuration
kubectl delete ingress <ingress-name>
kubectl apply -f ingress.yaml

Argo CD

Problèmes d'installation et de configuration

Argo CD pods ne démarrent pas

Symptômes :

Pods en état "ImagePullBackOff" ou "Pending"
Interface web inaccessible

Diagnostic :

Code
 
# Vérifier tous les pods Argo CD
kubectl get pods -n argocd

# Vérifier les events
kubectl get events -n argocd --sort-by=.metadata.creationTimestamp

# Logs du server
kubectl logs -n argocd deployment/argocd-server

Solutions :

Code
 
# Réinstaller avec les bonnes versions
kubectl delete namespace argocd
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Vérifier les ressources
kubectl describe pod <argocd-pod> -n argocd

# Attendre que tous les pods soient ready
kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=argocd-server -n argocd --timeout=300s

Impossible de se connecter à Argo CD

Symptômes :

Mot de passe admin ne fonctionne pas
CLI n'arrive pas à se connecter

Solutions :

Code
 
# Récupérer le mot de passe initial
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d

# Réinitialiser le mot de passe admin
kubectl -n argocd patch secret argocd-secret \
  -p '{"stringData": {"admin.password": "$2a$10$rRyBsGSHK6.uc8fntPwVIuLVHgsAhAX7TcdrqW/RADU0uh7CaChLa","admin.passwordMtime": "'$(date +%FT%T%Z)'"}}'

# Le hash ci-dessus correspond à "password"
# Pour générer un nouveau hash :
argocd account bcrypt --password your-new-password

# Redémarrer le server
kubectl -n argocd rollout restart deployment argocd-server

Problèmes de synchronisation

Applications ne se synchronisent pas

Symptômes :

Status "OutOfSync" permanent
Erreurs dans les logs de sync

Diagnostic :

Code
 
# Vérifier le status de l'application
argocd app get <app-name>
kubectl describe application <app-name> -n argocd

# Voir les logs de sync
argocd app logs <app-name>

# Vérifier la connectivité au repo
argocd repo list
argocd repo get <repo-url>

Solutions :

Code
 
# Forcer une synchronisation
argocd app sync <app-name> --force

# Vérifier les credentials du repo
argocd repo add <repo-url> --username <user> --password <token>

# Résoudre les conflits de configuration
argocd app diff <app-name>
argocd app sync <app-name> --replace

# Activer la synchronisation automatique
argocd app set <app-name> --sync-policy automated --auto-prune --self-heal

Repository inaccessible

Symptômes :

"repository not accessible" dans les logs
Applications ne peuvent pas récupérer les manifests

Solutions :

Code
 
# Tester l'accès au repository
git clone <repo-url>

# Vérifier les credentials
argocd repo list
argocd repo add <repo-url> --username <username> --password <new-token>

# Pour les repos SSH
argocd repo add <ssh-repo-url> --ssh-private-key-path ~/.ssh/id_rsa

# Vérifier la connectivité réseau depuis Argo CD
kubectl exec -it -n argocd deployment/argocd-repo-server -- nslookup github.com
kubectl exec -it -n argocd deployment/argocd-repo-server -- curl -I <repo-host>

CDK8s

Problèmes de développement

Erreurs de compilation TypeScript

Symptômes :

npm run build échoue
Erreurs de types CDK8s

Solutions :

Code
 
# Mettre à jour les dépendances
npm update
npm audit fix

# Réinstaller les types K8s
rm -rf imports/
cdk8s import k8s@1.28.0

# Vérifier la compatibilité des versions
npm ls cdk8s cdk8s-plus-27

# Nettoyer et reconstruire
rm -rf node_modules dist
npm install
npm run build

Manifests générés incorrects

Symptômes :

YAML invalide généré
Ressources manquantes après synth

Diagnostic :

Code
 
# Vérifier les manifests générés
npm run synth
ls -la dist/

# Valider avec kubectl
kubectl apply --dry-run=client -f dist/

# Comparer avec les attentes
cat dist/*.yaml | grep -A5 -B5 <problematic-section>

Solutions :

Code
 
# Débugger avec les tests
npm test -- --verbose

# Vérifier la logique dans les constructs
# Ajouter des console.log temporaires dans le code

# Valider étape par étape
ENVIRONMENT=dev npm run synth
kubectl apply --dry-run=server -f dist/

Problèmes d'intégration

Pipeline CDK8s échoue

Symptômes :

GitHub Actions / Gitea Actions échoue sur les étapes CDK8s
Tests d'infrastructure qui échouent

Solutions :

Code
 
# Reproduire localement
npm ci
npm run build
npm test
npm run synth

# Vérifier les variables d'environnement
echo $ENVIRONMENT
echo $IMAGE_TAG

# Vérifier les permissions de fichiers
ls -la dist/
chmod 644 dist/*.yaml

# Debug du pipeline
# Ajouter des étapes de debug dans le workflow :

Code
 
- name: Debug environment
  run: |
    echo "Node version: $(node --version)"
    echo "NPM version: $(npm --version)"
    echo "Environment: $ENVIRONMENT"
    ls -la dist/

Problèmes de performance

Pipelines lents

Diagnostic et solutions :

Code
 
# Profiler les étapes lentes dans Gitea Actions
# Regarder les temps d'exécution de chaque step

# Optimiser les builds Docker
# Utiliser le cache multi-stage
# .dockerignore approprié
# Layers optimisées

# Optimiser les tests
npm test -- --maxWorkers=4  # Parallélisation
npm test -- --onlyChanged   # Tests seulement des fichiers modifiés

# Cache des dépendances dans CI
# Utiliser les actions de cache appropriées

Cluster Kubernetes lent

Code
 
# Vérifier les ressources
kubectl top nodes
kubectl top pods --all-namespaces

# Identifier les goulots d'étranglement
kubectl get events --sort-by='.metadata.creationTimestamp' | tail -20

# Optimiser les resource requests/limits
# Trop restrictifs = throttling
# Trop généreux = waste de ressources

# Monitoring avec metrics-server
kubectl get apiservice v1beta1.metrics.k8s.io -o yaml

Scripts de diagnostic automatique

Script de santé générale

Code
 
#!/bin/bash
# health-check.sh

echo "🔍 Diagnostic complet du pipeline CI/CD"
echo "========================================"

# Vérifier Gitea
echo "📚 Gitea Status:"
curl -s http://localhost:3000/api/healthz && echo "✅ Gitea OK" || echo "❌ Gitea KO"

# Vérifier Docker Registry
echo "🐳 Docker Registry Status:"
curl -s http://localhost:5000/v2/ && echo "✅ Registry OK" || echo "❌ Registry KO"

# Vérifier Kubernetes
echo "☸️ Kubernetes Status:"
kubectl cluster-info > /dev/null 2>&1 && echo "✅ Kubernetes OK" || echo "❌ Kubernetes KO"

# Vérifier Argo CD
echo "🚀 Argo CD Status:"
kubectl get pods -n argocd --no-headers | grep -v Running | wc -l | xargs -I {} bash -c 'if [ {} -eq 0 ]; then echo "✅ Argo CD OK"; else echo "❌ Argo CD KO ({}pods not running)"; fi'

# Vérifier les applications
echo "📱 Applications Status:"
argocd app list 2>/dev/null | tail -n +2 | while read line; do
  app=$(echo $line | awk '{print $1}')
  status=$(echo $line | awk '{print $2}')
  health=$(echo $line | awk '{print $3}')
  
  if [[ "$status" == "Synced" && "$health" == "Healthy" ]]; then
    echo "✅ $app"
  else
    echo "❌ $app ($status, $health)"
  fi
done

# Vérifier l'espace disque
echo "💾 Disk Space:"
df -h / | tail -1 | awk '{if ($5 > 80) print "⚠️ Disk usage: " $5; else print "✅ Disk usage: " $5}'

echo ""
echo "🔧 Pour plus de détails, utilisez les commandes de diagnostic spécifiques."

Script de nettoyage

Code
 
#!/bin/bash
# cleanup.sh

echo "🧹 Nettoyage du système"
echo "====================="

# Nettoyer Docker
echo "🐳 Nettoyage Docker..."
docker system prune -f
docker volume prune -f
docker image prune -a -f

# Nettoyer Kubernetes
echo "☸️ Nettoyage Kubernetes..."
kubectl delete pods --field-selector=status.phase=Succeeded --all-namespaces
kubectl delete pods --field-selector=status.phase=Failed --all-namespaces

# Nettoyer les logs Gitea Actions
echo "📚 Nettoyage logs Gitea..."
# Selon votre configuration de stockage des logs

# Nettoyer les artefacts de build
echo "🗑️ Nettoyage build artefacts..."
find . -name "node_modules" -type d -exec rm -rf {} + 2>/dev/null
find . -name "dist" -type d -exec rm -rf {} + 2>/dev/null
find . -name ".npm" -type d -exec rm -rf {} + 2>/dev/null

echo "✅ Nettoyage terminé"

Ces guides de troubleshooting couvrent la plupart des problèmes que vous pourrez rencontrer. N'hésitez pas à les adapter à votre environnement spécifique et à enrichir avec vos propres découvertes.

Last modified on August 25, 2025

Ateliers pratiques - Jour 3 Référence des commandes