Gestion des Secrets dans EXAI

Ce document explique comment gérer les secrets dans le projet EXAI, à la fois pour le développement local et la production.

1. Vue d’ensemble

Le projet EXAI utilise deux scripts Python pour gérer les secrets Kubernetes de manière sécurisée :

  • scripts/update-local-secrets.py - Met à jour les fichiers YAML de secrets avec des valeurs encodées en base64

  • scripts/reset-placeholders.py - Restaure les placeholders avant de pousser le code vers Git

Ces scripts permettent de :

  1. Éviter de commiter des valeurs de secrets dans Git

  2. Maintenir une configuration cohérente entre le développement local et la production

  3. Simplifier la gestion des secrets pour tous les développeurs

2. Détails des Fichiers Secrets

2.1. Fichiers Concernés

Fichier Description

k8s/base/api-gateway/gateway-secrets.yaml

Secrets pour l’API Gateway (JWT, BDD, Google OAuth)

k8s/overlays/azure/oauth-redirect-patch.yaml

Patch pour l’URL de redirection OAuth en production

2.2. Format des Secrets

Les fichiers de secrets utilisent le format Kubernetes standard :

apiVersion: v1
kind: Secret
metadata:
  name: gateway-secrets
  namespace: exai
type: Opaque
data:
  secret-key: REPLACE_WITH_SECRET_KEY
  database-url: REPLACE_WITH_DATABASE_URL
  google-client-id: REPLACE_WITH_GOOGLE_CLIENT_ID
  google-client-secret: REPLACE_WITH_GOOGLE_CLIENT_SECRET
  oauth-redirect-url: REPLACE_WITH_LOCAL_REDIRECT_URL

Dans ce format, chaque valeur après le ":" doit être encodée en base64.

3. Configuration pour le Développement Local

3.1. Créer le Fichier .env

Le fichier .env doit être créé à la racine du projet. Ce fichier contient les secrets en clair (non encodés) :

# Clé secrète pour JWT
JWT_SECRET_KEY=09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7

# URL Base de données pour l'API Gateway
DATABASE_URL=postgresql+asyncpg://exai_user:password@postgresql-service.exai.svc.cluster.local:5432/exai_db

# Client ID Google OAuth
GOOGLE_CLIENT_ID=votre-client-id-google

# Client Secret Google OAuth
GOOGLE_CLIENT_SECRET=votre-client-secret-google

# URLs de redirection OAuth
LOCAL_REDIRECT_URL=http://localhost:4200/authentication/callback
OAUTH_REDIRECT_URL_PROD=https://exai-pipeline.fr/authentication/callback

# URLs des services backend pour le reverse proxy de l'API Gateway
# Ces URLs permettent à l'API Gateway de rediriger les requêtes vers les bons services
# Valeurs par défaut pour Minikube (automatiques)
SERVICE_SELECTION_URL=http://service-selection-service.exai.svc.cluster.local
ML_PIPELINE_URL=http://ml-pipeline-service.exai.svc.cluster.local
XAI_ENGINE_URL=http://xai-engine-service.exai.svc.cluster.local

# Optionnel : URLs alternatives pour le développement local avec services en local
# SERVICE_SELECTION_URL=http://localhost:8001
# ML_PIPELINE_URL=http://localhost:8002
# XAI_ENGINE_URL=http://localhost:8003

Le fichier .env est exclu de Git via .gitignore. NE JAMAIS commiter ce fichier !

3.2. Script update-local-secrets.py

Ce script lit les valeurs du fichier .env, les encode en base64, et met à jour les fichiers de secrets Kubernetes :

python -m scripts.update-local-secrets

Fonctionnement : 1. Charge les variables depuis .env (utilise python-dotenv) 2. Vérifie que toutes les variables requises sont présentes 3. Encode chaque valeur en base64 4. Met à jour les fichiers YAML avec les valeurs encodées 5. Affiche un message de confirmation

Exécutez ce script après chaque modification du fichier .env ou après avoir récupéré des changements sur les fichiers de secrets.

4. Configuration des Services Backend

4.1. Architecture Microservices

Le projet EXAI utilise une architecture microservices avec un API Gateway qui fait du reverse proxy vers les services backend. Les variables d’environnement suivantes configurent les URLs des services :

Variable Description

SERVICE_SELECTION_URL

URL du service de sélection des datasets

ML_PIPELINE_URL

URL du service de pipeline ML

XAI_ENGINE_URL

URL du moteur XAI

4.2. Valeurs par Défaut

Les valeurs par défaut sont configurées pour fonctionner automatiquement avec Minikube et en production Kubernetes :

SERVICE_SELECTION_URL=http://service-selection-service.exai.svc.cluster.local
ML_PIPELINE_URL=http://ml-pipeline-service.exai.svc.cluster.local
XAI_ENGINE_URL=http://xai-engine-service.exai.svc.cluster.local

Ces URLs utilisent les DNS internes de Kubernetes et fonctionnent automatiquement sans configuration supplémentaire.

4.3. Configuration Alternative

Pour le développement local avec des services qui tournent directement sur la machine (sans Kubernetes), vous pouvez surcharger ces variables dans votre fichier .env :

SERVICE_SELECTION_URL=http://localhost:8001
ML_PIPELINE_URL=http://localhost:8002
XAI_ENGINE_URL=http://localhost:8003

4.4. Fonctionnement du Reverse Proxy

L’API Gateway (port 9000) intercepte les requêtes suivantes et les redirige vers les services appropriés :

  • /datasets/* → SERVICE_SELECTION_URL

  • /ml-pipeline/* → ML_PIPELINE_URL (à venir)

  • /xai/* → XAI_ENGINE_URL (à venir)

Cela permet au frontend d’avoir une seule URL d’API tout en gardant les avantages de l’architecture microservices.

4.5. Script reset-placeholders.py

Ce script restaure les placeholders dans les fichiers de secrets avant de commiter le code :

python -m scripts.reset-placeholders

Fonctionnement : 1. Remplace les valeurs encodées par des placeholders (REPLACE_WITH_*) 2. Met à jour les fichiers YAML avec ces placeholders 3. Affiche un message de confirmation

Exécutez TOUJOURS ce script avant de commiter des changements qui affectent les fichiers de secrets !

5. Workflow de Développement

5.1. Premier Configuration

  1. Cloner le dépôt

  2. Créer le fichier .env à la racine (utiliser le format ci-dessus)

  3. Installer python-dotenv : pip install python-dotenv

  4. Exécuter python -m scripts.update-local-secrets

  5. Démarrer l’application avec Skaffold

5.2. Changement de Configuration

  1. Modifier le fichier .env

  2. Exécuter python -m scripts.update-local-secrets

  3. Redémarrer l’application si nécessaire

5.3. Avant de Pousser le Code

  1. Exécuter python -m scripts.reset-placeholders

  2. Vérifier que les fichiers de secrets contiennent maintenant des placeholders

  3. Commiter et pousser le code

6. Configuration en Production (Azure)

En production, les secrets sont injectés par GitHub Actions à partir des secrets stockés dans le dépôt GitHub.

Le workflow .github/workflows/deploy-production.yml :

  1. Récupère les secrets depuis GitHub Secrets

  2. Encode ces valeurs en base64

  3. Met à jour les fichiers de secrets avec sed

  4. Déploie l’application avec ces secrets

Pour ajouter ou modifier des secrets en production : 1. Mettre à jour les secrets dans GitHub Repository Settings > Secrets and variables > Actions 2. Vérifier que les noms des secrets correspondent à ceux utilisés dans le workflow 3. Lancer un déploiement ou pousser un commit sur la branche production

7. Sécurité et Bonnes Pratiques

  • Ne jamais commiter de secrets en clair ou encodés dans Git

  • Exécuter scripts.reset-placeholders avant chaque commit

  • Utiliser des secrets forts et uniques pour chaque environnement

  • Renouveler régulièrement les secrets, en particulier pour la production

  • Limiter l’accès aux secrets de production (GitHub Secrets) aux administrateurs

  • Garder le fichier .env local sécurisé