Développement local avec kind

Ce guide permet de faire tourner FastAPI + PostgreSQL localement sur un cluster kind, sans dépendre d'AWS.

Prérequis

• Docker Desktop (ou Docker dans WSL)
• kind v0.25+
• kubectl v1.31+

Vérification rapide :

docker version
kind version
kubectl version --client

Démarrage rapide

1. Créer le cluster

kind create cluster --name fastapi-local
kubectl cluster-info --context kind-fastapi-local

2. Builder et charger l'image

cd ~/Project-DEVOPS-FASTAPI-2026

# Build
docker build -t fastapi:local .

# Charger dans kind (contourne le registry)
kind load docker-image fastapi:local --name fastapi-local

3. Déployer

kubectl apply -k k8s/overlays/local-kind/ --context kind-fastapi-local

4. Vérifier que les pods sont Running

kubectl get pods -n fastapi --context kind-fastapi-local

Attendre que les deux pods fastapi-* et postgres-* soient 1/1 Running.

5. Tester

# Port-forward en arrière-plan
kubectl port-forward -n fastapi svc/fastapi 8080:80 --context kind-fastapi-local &

# Test basique
curl http://localhost:8080/

# Swagger UI (ouvrir dans un navigateur)
# http://localhost:8080/docs

# Test CORS
curl -H "Origin: http://localhost:3000" -v http://localhost:8080/ 2>&1 | grep -i access-control

Cycle de développement

Après chaque modification du code :

docker build -t fastapi:local .
kind load docker-image fastapi:local --name fastapi-local
kubectl rollout restart deployment/fastapi -n fastapi --context kind-fastapi-local
kubectl rollout status deployment/fastapi -n fastapi --context kind-fastapi-local

Ce que fait l'overlay local-kind

Paramètre	Base (EKS)	Local (kind)
DB_HOSTNAME	endpoint RDS AWS	postgres (service k8s)
DB_NAME	fastapi_db	fastapi
PostgreSQL	RDS managé	Pod avec emptyDir
Image	${ECR_IMAGE} (CI)	fastapi:local
imagePullPolicy	Always	Never
Replicas	2	1
Secrets	External Secrets Operator	Secret k8s local

Debugging

Symptôme	Cause probable	Fix
ImagePullBackOff sur fastapi:local	Image pas chargée dans kind	kind load docker-image fastapi:local --name fastapi-local
Init:Error sur migrations	PostgreSQL pas encore ready	Attendre, le pod va retry
Init:CrashLoopBackOff	Erreur Alembic ou config manquante	kubectl logs -n fastapi <pod> -c migrations
Pydantic ValidationError	Secret incomplet	Vérifier DB_PASSWORD + SECRET_KEY dans secret.yaml
Pod en Pending	Resource limits trop hauts	Réduire les limits dans le base
readOnlyRootFilesystem bloque	Lib qui écrit hors /tmp	Ajouter un emptyDir sur le chemin concerné
Données postgres perdues	emptyDir est éphémère	Normal — supprimer le pod postgres pour reset

# Logs migrations
kubectl logs -n fastapi <pod-fastapi> -c migrations --context kind-fastapi-local

# Logs app
kubectl logs -n fastapi <pod-fastapi> -c fastapi --context kind-fastapi-local

# Reset base de données (supprime toutes les données)
kubectl delete pod -n fastapi -l app=postgres --context kind-fastapi-local

Teardown

# Supprimer uniquement les ressources (garde le cluster)
kubectl delete -k k8s/overlays/local-kind/ --context kind-fastapi-local

# Supprimer le cluster entier
kind delete cluster --name fastapi-local