Configuration Initiale de l’Infrastructure Azure (Compte Personnel)

Ce guide décrit les étapes pour mettre en place l’environnement Microsoft Azure en utilisant un compte personnel (Pay-As-You-Go) afin d’accueillir l’application EXAI. Cette approche est recommandée pour éviter les limitations potentielles des comptes étudiants sur Azure AD / Entra ID.

Objectif

Mettre en place les fondations nécessaires sur Azure (Groupe de Ressources, Registre de Conteneurs, Cluster Kubernetes) et configurer l’authentification pour les déploiements automatisés via GitHub Actions.

Prérequis

  • Un compte Microsoft personnel (non-étudiant) avec un abonnement Azure actif de type "Paiement à l’utilisation" (Pay-As-You-Go).

  • L’outil en ligne de commande Azure CLI installé sur votre machine.

Étapes de Configuration

1. Connexion et Sélection de l’Abonnement

Assurez-vous d’être connecté à Azure CLI avec votre compte personnel et que votre abonnement Pay-As-You-Go est sélectionné.

az login
az account show # Vérifiez l'abonnement actif
# Si nécessaire, sélectionnez le bon abonnement :
# az account set --subscription "<NOM_OU_ID_ABONNEMENT_PAYG>"

2. Création du Groupe de Ressources (Resource Group)

  • Rôle : Conteneur logique pour toutes les ressources Azure du projet.

  • Commande :

az group create --name exai-perso-rg --location francecentral

3. Création du Registre de Conteneurs Azure (ACR)

  • Rôle : Stockage privé et sécurisé pour les images Docker des microservices.

  • Commande : (Choisissez un nom globalement unique pour <VOTRE_ACR_NAME>. Ex: exaipersoacr)

az acr create --resource-group exai-perso-rg --name <VOTRE_ACR_NAME> --sku Standard --location francecentral

  • Notez le nom du serveur de connexion : <VOTRE_ACR_NAME>.azurecr.io.

4. Création du Cluster Kubernetes Azure (AKS)

  • Rôle : Orchestrateur pour l’exécution des microservices conteneurisés.

  • Commande : (Assurez-vous de remplacer <VOTRE_ACR_NAME> par le nom choisi à l’étape précédente)

az aks create --resource-group exai-perso-rg --name exai-perso-aks --node-count 1 --node-vm-size Standard_B2s --location francecentral --attach-acr <VOTRE_ACR_NAME> --enable-managed-identity --enable-addons monitoring --generate-ssh-keys

5. Création du Service Principal pour GitHub Actions

  • Rôle : Permettre à GitHub Actions de s’authentifier sur Azure pour déployer.

  • Commande : (Remplacez <ID_DE_VOTRE_ABONNEMENT_PAYG> par l’ID de votre abonnement personnel)

az ad sp create-for-rbac --name "exai-perso-github-sp" --role "Contributor" --scopes "/subscriptions/<ID_DE_VOTRE_ABONNEMENT_PAYG>"

  • Action Cruciale : Copiez intégralement le bloc JSON affiché en sortie. Vous en aurez besoin à l’étape suivante.

6. Configuration du Secret GitHub AZURE_CREDENTIALS

  • Allez dans les paramètres de votre dépôt GitHub > Secrets and variables > Actions.

  • Créez ou mettez à jour un secret nommé AZURE_CREDENTIALS.

  • Collez le JSON complet obtenu à l’étape 5 comme valeur pour ce secret.

7. Configuration de kubectl Localement

  • Rôle : Permettre à votre outil kubectl local de communiquer avec le nouveau cluster AKS.

  • Commande :

az aks get-credentials --resource-group exai-perso-rg --name exai-perso-aks --overwrite-existing

Déploiement Automatisé avec GitHub Actions

Avec l’infrastructure et l’authentification en place, le déploiement est géré par le workflow défini dans .github/workflows/deploy-production.yml.

Ce workflow utilise une combinaison d’outils :

  1. GitHub Actions (.github/workflows/deploy-production.yml): Orchestre le processus global (build, push, déploiement K8s, migration BDD).

  2. Docker/Buildx: Construit les images Docker pour les différents services.

  3. Azure CLI & Docker Login: Authentifie le workflow auprès d’Azure et de l’ACR.

  4. Skaffold (skaffold.yaml): Gère le déploiement sur Kubernetes en utilisant Kustomize. Le profil azure est spécifiquement utilisé.

  5. Kustomize (k8s/overlays/azure/): Applique les configurations spécifiques à l’environnement Azure par-dessus les manifestes de base (k8s/base/).

  6. Kubectl: Applique le Job de migration et gère les redémarrages post-migration.

  7. Alembic: Exécuté via un Job Kubernetes pour appliquer les migrations de base de données après le déploiement des applications.

Flux Détaillé du Workflow (deploy-production.yml)

  1. Checkout: Récupération du code source de la branche production.

  2. Login Azure/ACR: Connexion sécurisée à Azure et à l’ACR spécifié (ex: exaiprodacr).

  3. Build & Push Images:

    • Construction des images Docker pour api-gateway, service-selection, et frontend.

    • Les images sont taguées avec le SHA court du commit (ex: :612ccb3) ET avec :latest.

    • Important: Le tag :latest est crucial pour l’image exai-api-gateway car il est utilisé par le Job de migration Alembic.

    • Les images taguées sont poussées vers l’ACR.

  4. Set AKS Context: Configuration de kubectl pour cibler le cluster AKS défini dans les variables d’env du workflow (ex: exai-prod-aks).

  5. Create Namespace: Création du namespace exai s’il n’existe pas.

  6. Skaffold Deploy:

    • Exécution de skaffold deploy --profile=azure --tag=<commit_sha> -n exai.

    • Skaffold utilise Kustomize pour builder les manifestes depuis l’overlay k8s/overlays/azure/.

    • L’overlay Azure (kustomization.yaml) référence les ressources de base (k8s/base/…​) et applique les modifications nécessaires (ex: remplacement des noms d’images pour pointer vers l’ACR).

    • Configuration Kustomize Clé: L’argument --load-restrictor=LoadRestrictionsNone est passé à kustomize build via skaffold.yaml pour permettre à Kustomize de lire les fichiers de base situés en dehors du répertoire de l’overlay.

  7. Wait for PostgreSQL: Attente que le pod du StatefulSet PostgreSQL soit prêt.

  8. Database Migration:

    • Suppression de l’ancien Job de migration s’il existe (kubectl delete job…​).

    • Application du fichier k8s/base/jobs/api-gateway-migration-job.yaml. Ce Job utilise l’image exai-api-gateway:latest et exécute alembic upgrade head.

    • Attente de la complétion du Job (kubectl wait --for=condition=complete…​).

  9. Rollout Restart (Optionnel): Redémarrage des déploiements (ex: api-gateway) pour s’assurer qu’ils utilisent le schéma de base de données migré (kubectl rollout restart deployment…​).

  10. Cleanup (Optionnel): Suppression du Job de migration une fois terminé avec succès (kubectl delete job…​).

Configurations Kubernetes Clés (Base & Overlay)

Le succès du déploiement dépend de la bonne configuration des manifestes Kubernetes de base et de leur surcharge via Kustomize pour l’environnement Azure.

  • Structure Kustomize: Les manifestes génériques sont dans k8s/base/ (organisés par service ou fonction, ex: api-gateway/, postgres/, common/). L’overlay k8s/overlays/azure/kustomization.yaml référence ces bases et applique des patches ou des remplacements (ex: noms d’images ACR).

  • StatefulSet pour PostgreSQL: La base de données est gérée par un StatefulSet (k8s/base/postgres/postgresql-statefulset.yaml) pour assurer une identité réseau stable et une gestion correcte des volumes persistants.

  • Ressources Communes: Les ressources partagées comme l’Ingress et le ClusterIssuer Cert-Manager sont placées dans k8s/base/common/ (ingress.yaml, letsencrypt-prod-issuer.yaml). L’overlay Azure référence ces fichiers depuis common/.

  • Secrets (gateway-secrets.yaml, db-secrets.yaml, etc.):

  • Les secrets contiennent des informations sensibles comme les URL de base de données et les clés secrètes JWT, encodées en Base64.

  • Cohérence Cruciale: Les noms des clés DANS le secret YAML (ex: database-url, secret-key - souvent avec tiret par convention YAML) doivent correspondre EXACTEMENT aux clés (key: …​) référencées dans les définitions des variables d’environnement (env.valueFrom.secretKeyRef.key) des déploiements (deployment.yaml) ET des jobs (api-gateway-migration-job.yaml) qui les utilisent. Une incohérence (ex: tiret vs underscore) cause une erreur CreateContainerConfigError lors du démarrage du pod.

  • Ingress (ingress.yaml):

  • Définit les règles de routage HTTP(S) basées sur les noms d’hôtes (ex: api.exai-pipeline.fr) vers les services Kubernetes correspondants (api-gateway-service, frontend).

  • Utilise les annotations kubernetes.io/ingress.class: nginx et cert-manager.io/cluster-issuer: letsencrypt-prod pour indiquer au contrôleur Nginx Ingress et à Cert-Manager comment gérer les requêtes et les certificats TLS.

  • Dépendance Forte: L’Ingress ne fonctionne que si un contrôleur d’Ingress (comme Nginx Ingress) est correctement installé et en cours d’exécution dans le cluster, et expose un service de type LoadBalancer avec une adresse IP externe publique.

Prochaines Étapes

L’infrastructure de base et le pipeline de déploiement étant fonctionnels, les prochaines étapes peuvent inclure :

  • Configuration avancée du réseau (Ingress Controller, règles de pare-feu).

  • Mise en place de stratégies de monitoring et d’alerting plus détaillées.

  • Optimisation des coûts et des ressources.