diff --git a/.github/workflows/airflow.yml b/.github/workflows/airflow.yml index 23b6af0..0d652d9 100644 --- a/.github/workflows/airflow.yml +++ b/.github/workflows/airflow.yml @@ -93,11 +93,12 @@ jobs: # `--help` sort par argparse avant `get_settings()` : ni base ni secret requis, et # l'import des modules prouve que l'environnement /opt/backend est complet. - # Les deux commandes du DAG `alertes` et la commande du DAG historique sont couvertes. - - name: Vérifie que les trois commandes backend s'importent sans réseau + # Les commandes des DAGs `alertes`, historique et API Mock sont couvertes. + - name: Vérifie que les quatre commandes backend s'importent sans réseau run: > docker run --rm --network none enervision-airflow:ci bash -c "cd /opt/backend && env -u VIRTUAL_ENV uv run --no-sync python -m app.detection.internal_alerts --help && env -u VIRTUAL_ENV uv run --no-sync python -m app.cli generate-recommendations --help - && env -u VIRTUAL_ENV uv run --no-sync python -m app.etl.historical_import --help" \ No newline at end of file + && env -u VIRTUAL_ENV uv run --no-sync python -m app.etl.historical_import --help + && env -u VIRTUAL_ENV uv run --no-sync python -m app.etl.mock_api_import --help" \ No newline at end of file diff --git a/README.md b/README.md index 879a491..f068f67 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ L'etat detaille de chaque brique et les vues d'architecture sont dans │ ├── migrations/ Migrations SQL versionnees │ └── seeds/ Jeux de donnees de reference ├── etl/airflow/ -│ ├── dags/ DAGs d'orchestration (pipeline ML, alertes, import, dérive) +│ ├── dags/ DAGs d'orchestration (pipeline ML, alertes, imports, dérive) │ ├── plugins/ Operateurs et hooks maison │ ├── include/ Requetes SQL et ressources des DAGs │ └── tests/ Tests d'integrite des DAGs diff --git a/apps/backend/app/etl/mock_api_import.py b/apps/backend/app/etl/mock_api_import.py index 0d5d6be..65fcea5 100644 --- a/apps/backend/app/etl/mock_api_import.py +++ b/apps/backend/app/etl/mock_api_import.py @@ -45,15 +45,19 @@ CAPACITY_BOUNDS = (0.0, 100_000.0) def create_mock_api_client() -> httpx.AsyncClient: settings = get_settings() - if settings.mock_api_username is None or settings.mock_api_password is None: + username = settings.mock_api_username + password = ( + settings.mock_api_password.get_secret_value() + if settings.mock_api_password is not None + else None + ) + + if not username or not username.strip() or not password or not password.strip(): raise ValueError("Les identifiants de l'API Mock ne sont pas configurés.") return httpx.AsyncClient( base_url=settings.mock_api_base_url.rstrip("/"), - auth=( - settings.mock_api_username, - settings.mock_api_password.get_secret_value(), - ), + auth=(username, password), timeout=settings.mock_api_timeout_seconds, ) diff --git a/apps/backend/app/monitoring/drift.py b/apps/backend/app/monitoring/drift.py index ce663b5..76fc0d6 100644 --- a/apps/backend/app/monitoring/drift.py +++ b/apps/backend/app/monitoring/drift.py @@ -71,7 +71,7 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace: default=defauts.seuil_biais, help=( "Biais absolu en kWh au-delà duquel le verdict bascule en dérive. " - "Zéro, le défaut, laisse le biais informatif : voir l'ADR 0011." + "Zéro, le défaut, laisse le biais informatif : voir l'ADR 0013." ), ) parser.add_argument( diff --git a/apps/backend/app/services/drift.py b/apps/backend/app/services/drift.py index ef8ecac..71bc41a 100644 --- a/apps/backend/app/services/drift.py +++ b/apps/backend/app/services/drift.py @@ -42,7 +42,7 @@ class Seuils: ratio_derive: float = 1.25 mae_plancher: float = 0.0 # Un biais se compte en kWh, donc ne se transpose pas d'un site à l'autre : zéro le désactive, - # sans cesser de le mesurer. Réglé par `--bias-threshold`, arbitrage dans l'ADR 0011. + # sans cesser de le mesurer. Réglé par `--bias-threshold`, arbitrage dans l'ADR 0013. seuil_biais: float = 0.0 seuil_couverture: float = 0.8 diff --git a/apps/backend/tests/etl/test_mock_api_import.py b/apps/backend/tests/etl/test_mock_api_import.py index cdcff55..fa654bc 100644 --- a/apps/backend/tests/etl/test_mock_api_import.py +++ b/apps/backend/tests/etl/test_mock_api_import.py @@ -283,6 +283,41 @@ def test_create_mock_api_client_requires_credentials( mock_api_import.create_mock_api_client() +@pytest.mark.parametrize( + ("username", "password_value"), + [ + ("", "test-password"), + ("test-user", ""), + (" ", "test-password"), + ("test-user", " "), + ], +) +def test_create_mock_api_client_rejects_empty_credentials( + monkeypatch: pytest.MonkeyPatch, + username: str, + password_value: str, +) -> None: + password = MagicMock() + password.get_secret_value.return_value = password_value + + settings = SimpleNamespace( + mock_api_username=username, + mock_api_password=password, + ) + + monkeypatch.setattr( + mock_api_import, + "get_settings", + lambda: settings, + ) + + with pytest.raises( + ValueError, + match="Les identifiants de l'API Mock ne sont pas configurés", + ): + mock_api_import.create_mock_api_client() + + async def test_create_mock_api_client_uses_configuration( monkeypatch: pytest.MonkeyPatch, ) -> None: diff --git a/apps/backend/tests/services/test_drift.py b/apps/backend/tests/services/test_drift.py index 723f252..acc924a 100644 --- a/apps/backend/tests/services/test_drift.py +++ b/apps/backend/tests/services/test_drift.py @@ -222,7 +222,7 @@ async def test_drift_compares_the_recent_window_to_the_reference_one( async def test_drift_leaves_the_bias_out_of_the_verdict_by_default() -> None: # Le modèle surestime de 3 kWh à chaque heure, et le verdict reste `stable` : le biais est - # mesuré et servi, il ne juge pas tant que `--bias-threshold` n'a pas été réglé (ADR 0011). + # mesuré et servi, il ne juge pas tant que `--bias-threshold` n'a pas été réglé (ADR 0013). depot = FauxDepot( recentes=paires(nombre=30, prevu=13.0, reel=10.0), anciennes=paires(nombre=30, prevu=13.0, reel=10.0), diff --git a/docker-compose.yml b/docker-compose.yml index ffa7238..b6d9f5d 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -34,12 +34,14 @@ x-airflow-common: &airflow-common # memes identifiants que le backend en attendant. ML_DATABASE_URL: postgresql+psycopg://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB} MLFLOW_TRACKING_URI: sqlite:////opt/ml/state/mlflow.db - # Le DAG `alertes` lance le backend en sous-processus : il lit `DATABASE_URL`, en - # dialecte asyncpg, là où le pipeline ML lit `ML_DATABASE_URL`. + # Les DAGs backend lisent `DATABASE_URL` en dialecte asyncpg, là où le pipeline ML + # utilise `ML_DATABASE_URL`. DATABASE_URL: postgresql+asyncpg://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB} - # Clé distincte de celle de l'API : la détection ne signe ni ne vérifie aucun jeton, et - # Airflow permet d'exécuter du code depuis son interface (cf. ADR 0008). + + # Clé distincte de celle de l'API : les traitements lancés par Airflow ne signent ni ne + # vérifient aucun jeton. Airflow permet d'exécuter du code depuis son interface (ADR 0008). APP_SECRET_KEY: ${AIRFLOW_APP_SECRET_KEY:-} + volumes: - ./etl/airflow/dags:/opt/airflow/dags - ./etl/airflow/plugins:/opt/airflow/plugins @@ -167,6 +169,14 @@ services: airflow-scheduler: <<: *airflow-common command: scheduler + environment: + <<: *airflow-common-env + # LocalExecutor exécute les tâches dans le scheduler : lui seul a besoin des + # identifiants de l'API Mock. + APP_MOCK_API_BASE_URL: ${APP_MOCK_API_BASE_URL:-https://api-mock.charlieandre.fr} + APP_MOCK_API_USERNAME: ${APP_MOCK_API_USERNAME:-} + APP_MOCK_API_PASSWORD: ${APP_MOCK_API_PASSWORD:-} + APP_MOCK_API_TIMEOUT_SECONDS: ${APP_MOCK_API_TIMEOUT_SECONDS:-10} depends_on: db: condition: service_healthy diff --git a/docs/ML-START.md b/docs/ML-START.md index a91a721..07c1abc 100644 --- a/docs/ML-START.md +++ b/docs/ML-START.md @@ -93,7 +93,7 @@ La table `prediction` **n'a pas de contrainte d'unicité sur `(site_id, target_a insère une ligne de plus au lieu d'écraser la précédente. C'est délibéré, et c'est ce qui rend possible la comparaison prévision contre réalisé. La surveillance de dérive s'en sert : elle retient, pour chaque `(site_id, target_at)`, la ligne du run le plus récent, celle-là même que -sert `GET /api/v1/predictions`. Voir l'[ADR 0011](adr/0011-surveillance-de-derive-dans-le-backend.md). +sert `GET /api/v1/predictions`. Voir l'[ADR 0013](adr/0013-surveillance-de-derive-dans-le-backend.md). Trois contraintes de cohérence sont portées par la base et non par le code applicatif : `status = 'available'` exige une `predicted_value` et interdit un `failure_reason` ; @@ -183,7 +183,7 @@ l'entraînement, dont le DAG `ml_train` n'a pas de planification. La surveillance de dérive traverse cette frontière **dans le sens de la table vers le backend**, sans la percer : elle relit `prediction` et `reading` en SQL, ne charge aucun modèle, et n'appelle pas MLflow. Son calcul, son seuil et son refus de comparer à la métrique d'entraînement sont dans -l'[ADR 0011](adr/0011-surveillance-de-derive-dans-le-backend.md). +l'[ADR 0013](adr/0013-surveillance-de-derive-dans-le-backend.md). --- @@ -194,4 +194,4 @@ l'[ADR 0011](adr/0011-surveillance-de-derive-dans-le-backend.md). - [ADR 0006](adr/0006-moteur-de-regles-dans-le-backend.md) : ce qui consomme les prédictions - [`architecture/20-backend.md`](architecture/20-backend.md) : le contrat de `GET /predictions` - [`architecture/40-data.md`](architecture/40-data.md) : le modèle de données -- [ADR 0011](adr/0011-surveillance-de-derive-dans-le-backend.md) : la surveillance de dérive +- [ADR 0013](adr/0013-surveillance-de-derive-dans-le-backend.md) : la surveillance de dérive diff --git a/docs/README.md b/docs/README.md index f7f5afd..b36ffea 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,4 +17,6 @@ | [0008](adr/0008-airflow-execute-le-code-du-backend.md) | Airflow exécute le code du backend en sous-processus, dans son propre environnement | | [0009](adr/0009-deux-environnements-compose-sur-la-vm-eni.md) | Deux environnements sur la VM ENI, un projet Compose chacun, déployés par un runner auto-hébergé | | [0010](adr/0010-terraform-provisionne-github-actions-deploie.md) | Terraform provisionne la machine, GitHub Actions déploie l'application | -| [0011](adr/0011-surveillance-de-derive-dans-le-backend.md) | La surveillance de dérive vit dans le backend et écrit sa propre table | +| [0011](adr/0011-enervision-procedure-deploiement.md) | Procédure de déploiement, telle qu'exécutée le 22/09/2026 | +| [0012](adr/0012-enervision-deploiement-rec-prod-vm-eni.md) | État de la recette et de la production sur la VM ENI | +| [0013](adr/0013-surveillance-de-derive-dans-le-backend.md) | La surveillance de dérive vit dans le backend et écrit sa propre table | diff --git a/docs/adr/0011-enervision-procedure-deploiement.md b/docs/adr/0011-enervision-procedure-deploiement.md new file mode 100644 index 0000000..fb74241 --- /dev/null +++ b/docs/adr/0011-enervision-procedure-deploiement.md @@ -0,0 +1,162 @@ +# EnerVision · procédure de déploiement (22/09/2026) + +Terraform provisionne la machine, GitHub Actions déploie (ADR 0010). Deux environnements Compose +sur la VM ENI `10.101.200.37` : `rec` sur la branche `dev`, `prod` sur `main` (ADR 0009). + +| | recette | production | +|---|---|---| +| Branche, environnement GitHub | `dev`, `rec` | `main`, `prod` | +| Dossier, projet Compose | `/srv/enervision/rec`, `enervision-rec` | `/srv/enervision/prod`, `enervision-prod` | +| URL | `https://rec.enervision.local:8443` | `https://enervision.local` | +| Proxy HTTP / HTTPS | `127.0.0.1:8081` / `8443` | `80` / `443` | +| Postgres / Mailpit / Airflow (locaux) | `5434` / `8026` / `8082` | `5433` / `8025` / `8080` | + +## 0. Avant toute commande + +1. **Clé SSH déposée** sur la VM : `ssh-copy-id -i ~/.ssh/id_ed25519.pub root@10.101.200.37`. + Terraform ne gère **pas** l'authentification par mot de passe (elle finirait dans le state). +2. **L'utilisateur propriétaire existe déjà** sur la VM (ex. `enervision`) : il possède + `/srv/enervision` et fait tourner le runner. Terraform échoue tôt s'il manque, il ne le crée pas. +3. **Jeton d'enregistrement du runner** : Settings > Actions > Runners > New self-hosted runner. + Valable 1 h, une seule inscription, créé par un administrateur du dépôt (ineszang). +4. **`main` est en retard de 64 commits** et ne porte ni `deploy.yml`, ni `provision-host.sh`, ni + le Terraform, ni l'overlay paramétré (ports et `PUBLIC_ORIGIN` en dur). Tant que `dev` n'est pas + remonté dans `main`, seule la recette est déployable : le clone `prod` sera préparé mais son + `make stack-up` publierait 80/443 sans les variables, et aucun push sur `main` ne déclencherait + de déploiement (le workflow n'y existe pas). **Remonter `dev` → `main` avant de toucher à prod.** + +## 1. Provisionner la machine (depuis le poste) + +```bash +cd infra/terraform/environments/vm-eni +cp terraform.tfvars.example terraform.tfvars +terraform init +terraform apply +``` + +`terraform.tfvars`, ignoré par git, trois valeurs à renseigner : + +```hcl +proprietaire = "enervision" # doit exister sur la VM +runner_version = "2.330.0" # épingler depuis github.com/actions/runner/releases +runner_token = "..." # jeton d'1 h, à retirer du fichier après l'apply +``` + +Défauts utiles : `ssh_host = "10.101.200.37"`, `ssh_user = "root"`, +`ssh_private_key_path = "~/.ssh/id_ed25519"`, `racine = "/srv/enervision"`, +`runner_labels = "eni-g3"` (ciblé par `deploy.yml`), `runner_dossier = "/opt/actions-runner"`. + +L'apply fait trois choses, dans cet ordre : Docker + plugin Compose et `usermod -aG docker`, +puis `scripts/provision-host.sh`, puis l'installation et l'enregistrement du runner en service. +Il ne construit aucune image et ne démarre aucun conteneur : un apply n'interrompt pas la stack. + +Rejouable : un clone existant est réaligné, un `.env` présent n'est **jamais** réécrit, un +certificat présent n'est jamais régénéré. Un nouvel apply de la ressource runner redemande un +jeton frais (il expire en 1 h). + +## 2. Variables d'environnement + +Un `.env` par dossier, en `600`, généré sur la machine depuis `.env.example`. **Aucun secret ne +passe par git ni par GitHub** : le runner n'en reçoit aucun (seul `SONAR_TOKEN` existe côté CI). + +**Générés automatiquement** : `POSTGRES_PASSWORD`, `APP_SECRET_KEY`, `AIRFLOW_FERNET_KEY`, +`AIRFLOW_API_SECRET_KEY`, `AIRFLOW_JWT_SECRET`, `AIRFLOW_ADMIN_PASSWORD`, `AIRFLOW_APP_SECRET_KEY`. + +**Fixés par environnement** : `COMPOSE_PROJECT_NAME`, `PUBLIC_HOST`, `PUBLIC_ORIGIN`, +`PROXY_HTTP_PORT`, `PROXY_HTTPS_PORT`, `POSTGRES_PORT`, `MAILPIT_UI_PORT`, `AIRFLOW_PORT`. + +**À renseigner à la main**, dans chaque `.env`, avant le premier démarrage : + +``` +APP_MOCK_API_USERNAME=... +APP_MOCK_API_PASSWORD=... +``` + +Garde-fou : le script refuse d'écrire un `.env` s'il reste un `change_me` hors `APP_MOCK_API_*` +(cas vécu d'une clé renommée en amont, `AIRFLOW_WEBSERVER_SECRET_KEY` sous Airflow 3). + +`APP_ENV=prod` et `APP_DEBUG=false` sont en dur dans l'overlay, pas dans le `.env` : la valeur +`local` du poste reprendrait le dessus et rouvrirait `/docs` sans cookie `__Secure-`. + +`TS_TUNE_MEMORY=2GB` et `TS_TUNE_NUM_CPUS=2` sont obligatoires : deux TimescaleDB sur 8 Go se +réserveraient 25 % de la RAM chacune. La montée à 32 Go est à demander. + +Certificats auto-signés générés par le script (`infra/proxy/tls/`), couvrant le nom d'hôte, +`localhost` et l'IP. Let's Encrypt (`make tls-acme`, `ACME_EMAIL`) reste hors d'atteinte sans +domaine public résolvable. + +## 3. Premier démarrage (manuel, une seule fois, sur la VM) + +```bash +cd /srv/enervision/rec && make stack-up # build + up + alembic upgrade head +cd /srv/enervision/prod && make stack-up # seulement après la remontée dev → main +``` + +`stack-up` refuse de démarrer si le certificat manque ou ne couvre pas `PUBLIC_HOST`, et applique +les migrations : sans elles la stack démarrerait verte sur une base sans schéma. + +Premier administrateur, stack démarrée, dans chaque dossier : + +```bash +docker compose -f docker-compose.yml -f docker-compose.prod.yml exec backend \ + python -m app.cli create-admin --email +``` + +Données historiques : `data/raw` n'est pas dans git. Déposer les fichiers dans chaque dossier +avant de déclencher le DAG `historical_import`. + +## 4. Réglages GitHub (administrateur du dépôt) + +- Environnement `prod` : branche `main` seule autorisée, **approbation d'un relecteur** requise. +- Environnement `rec` : branche `dev` seule autorisée, sans approbation. +- Settings > Actions : **« Require approval for all outside collaborators »**. Un runner + auto-hébergé sur un dépôt public exécute ce qu'on lui envoie ; `deploy.yml` ne se déclenche + jamais sur `pull_request`, et le runner ne tourne jamais en root. + +## 5. Déploiement continu, ensuite + +Un push sur `dev` déploie la recette, un push sur `main` la production après approbation. +Le job (runner `eni-g3`) aligne le clone (`fetch`, `checkout`, `reset --hard`), lance +`make stack-up`, puis sonde `/api/v1/health/ready` derrière le proxy pendant 3 minutes ; en cas +d'échec il publie `ps` et les 50 dernières lignes de `backend` et `proxy`. Pas de `checkout` dans +l'espace du runner : `.env`, certificats et volumes doivent survivre d'un déploiement à l'autre. +Concurrence par branche, sans annulation. + +Déclenchement manuel possible : `workflow_dispatch`. + +## 6. Vérifier + +```bash +curl -k https://localhost:8443/api/v1/health/ready # recette, sur la VM +curl -k https://localhost/api/v1/health/ready # production, sur la VM +``` + +Depuis un poste, ajouter à `/etc/hosts` : + +``` +10.101.200.37 enervision.local rec.enervision.local +``` + +Les deux noms sont obligatoires : le cookie `__Secure-ev_refresh` est posé par hôte et non par +port ; un seul nom déconnecterait la production à chaque connexion en recette. + +## Pièges à connaître + +- Compose **2.24.4 minimum** : l'overlay emploie `!override` et `!reset`, sans quoi l'API resterait + joignable en clair à côté du proxy. Le script le vérifie. +- Le runner doit tourner sous le propriétaire de `/srv/enervision` : sinon git refuse les clones + (propriété douteuse) et le `.env` en `600` lui échappe. Correctif : + `PROPRIETAIRE= bash scripts/provision-host.sh`. +- Chaque environnement reconstruit ses images à partir du même commit : la production n'exécute + pas l'artefact validé en recette, mais un second build. Le passage à GHCR lèvera cette limite. +- Un `.env` perdu se régénère, mais invalide les sessions et les connexions chiffrées par Airflow : + ils ne sont sauvegardés nulle part ailleurs. +- Retirer le runner se fait à la main, depuis les paramètres du dépôt : `terraform destroy` ne le + désinscrit pas. + +## Références dans le dépôt + +`docs/adr/0009-deux-environnements-compose-sur-la-vm-eni.md`, +`docs/adr/0010-terraform-provisionne-github-actions-deploie.md`, +`docs/architecture/50-cicd.md`, `docs/architecture/10-infra.md`, `infra/README.md`, +`scripts/provision-host.sh`, `.github/workflows/deploy.yml`, `docker-compose.prod.yml`. diff --git a/docs/adr/0012-enervision-deploiement-rec-prod-vm-eni.md b/docs/adr/0012-enervision-deploiement-rec-prod-vm-eni.md new file mode 100644 index 0000000..8d01d39 --- /dev/null +++ b/docs/adr/0012-enervision-deploiement-rec-prod-vm-eni.md @@ -0,0 +1,120 @@ +# EnerVision · Recette et production sur la VM ENI, aujourd'hui + +État au lundi 21 septembre 2026, 15h. Cible : deux environnements qui tournent sur la VM +`eadl-2025-nantes-g3` (`10.101.200.37`) avant vendredi 25/09 9h, déployés automatiquement depuis +GitHub. Ce document donne la solution retenue, ce qu'elle change dans le dépôt, et le déroulé de +l'après-midi avec qui fait quoi. + +## 1. La décision en une phrase + +**Deux projets Docker Compose sur la même VM, un par environnement, déployés par un runner GitHub +Actions installé sur la VM.** `dev` alimente la recette, `main` alimente la production. Terraform +reste ce qu'il est : le module k3s, cible à terme, non utilisé pour cette mise en ligne. + +| | Recette (`rec`) | Production (`prod`) | +|---|---|---| +| Branche | `dev` | `main` | +| Environnement GitHub | `rec` (créé ce midi) | `prod` (créé ce midi) | +| Dossier sur la VM | `/srv/enervision/rec` | `/srv/enervision/prod` | +| Projet Compose | `enervision-rec` | `enervision-prod` | +| URL | `https://rec.enervision.local:8443` | `https://enervision.local` | +| Proxy HTTPS | `8443` | `443` | +| Proxy HTTP (redirection) | `127.0.0.1:8081`, inutilisé | `80` | +| PostgreSQL, Mailpit, Airflow | `127.0.0.1` : `5434`, `8026`, `8082` | `127.0.0.1` : `5433`, `8025`, `8080` | +| Certificat | auto-signé, SAN `rec.enervision.local` | auto-signé, SAN `enervision.local` | +| Déclenchement | chaque push sur `dev` | push sur `main`, après approbation dans GitHub | + +Les deux noms d'hôte pointent sur la même IP. Deux lignes dans le `/etc/hosts` des postes de +l'équipe suffisent. Deux noms distincts sont indispensables : le cookie de rafraîchissement +`__Secure-ev_refresh` est posé par hôte, pas par port, et un seul nom ferait se déconnecter la +prod à chaque connexion sur la recette. + +## 2. Pourquoi c'est la solution la plus simple + +- **Tout existe déjà.** L'overlay `docker-compose.prod.yml`, le proxy Nginx TLS, les scripts de + certificat et `make stack-up` sont écrits et validés sur poste (PR #117, ADR 0007). Il ne + manque que quatre variables pour que deux instances cohabitent sur une machine. +- **Un projet Compose isole tout.** Volumes, réseau, noms de conteneurs sont préfixés par le nom + du projet. Casser la recette ne touche pas la prod, ce qui est la raison d'être d'une recette. +- **Le runner sur la VM est la seule façon d'atteindre une IP privée d'école depuis GitHub.** Les + runners hébergés par GitHub ne voient pas `10.101.200.37`. Le runner se connecte en sortie + vers GitHub, aucun port entrant n'est nécessaire. C'était le choix 16 du dossier EC01 : il + redevient tenu. +- **La promotion existe déjà dans la stratégie de branches** : `dev` puis `main` par PR. Le + même code est déployé en recette, puis en production, sans troisième mécanisme. + +Ce qu'on écarte, et pourquoi : + +| Piste | Pourquoi pas cette semaine | +|---|---| +| k3s avec deux namespaces | Le cluster serait vide : aucun manifeste, aucun registre d'images, aucun stockage persistant. Trois jours de travail sans valeur visible au J10 | +| Terraform de `feat/deploy` (nginx système + copie de fichiers) | Revue postée sur l'issue #21 : huit points bloquants, `rec` et `prod` ne passent pas `terraform validate`. On abandonne cette voie | +| Azure ENI pour la prod | Deuxième infrastructure à provisionner, choix à justifier devant le jury (document 03), et rien n'est prêt côté Azure | +| Images publiées sur GHCR | Meilleure pratique, mais un registre de plus à authentifier sur la VM. Les images se construisent sur la VM, où le runner tourne déjà. À faire ensuite, issue à ouvrir | +| Let's Encrypt | Aucun domaine public ne résout vers la VM. Auto-signé assumé, chemin ACME déjà câblé | + +## 3. Ce qui change dans le dépôt (une PR vers `dev`) + +| Fichier | Changement | Raison | +|---|---|---| +| `apps/frontend/Dockerfile` | `FROM nginx:1.28-alpine` à la place de `dhi.io/nginx:...` | Le registre Docker Hardened Images demande une authentification. L'image frontend n'a jamais été construite, sur aucun poste : c'est le premier point où `make stack-up` échouerait sur la VM | +| `docker-compose.prod.yml` | Ports du proxy en variables `PROXY_HTTP_PORT` et `PROXY_HTTPS_PORT`. Origine publique `PUBLIC_ORIGIN` pour CORS et le lien de réinitialisation. `TS_TUNE_MEMORY` sur la base | Deux proxys ne peuvent pas publier 80 et 443. L'origine de la recette porte un port. Deux TimescaleDB sur 8 Go se réserveraient chacune 2 Go sans réglage | +| `.env.example` | `COMPOSE_PROJECT_NAME`, les variables ci-dessus, ports de la recette en commentaire | Le `.env` de chaque dossier est la seule différence entre les deux environnements | +| `.github/workflows/deploy.yml` | Nouveau. `on: push` sur `dev` et `main`, `runs-on: [self-hosted, eni-g3]`, `environment: rec` ou `prod`, puis `git reset --hard origin/` et `make stack-up` dans le dossier de l'environnement | Le D de CI/CD, issue #21 | +| `scripts/provision-host.sh` | Nouveau. Vérifie Docker et Compose 2.24.4 ou plus, crée `/srv/enervision/{rec,prod}`, clone les deux branches | Rejouable, et réutilisable par Terraform plus tard | +| `docs/adr/0009-...md`, `10-infra.md`, `50-cicd.md`, `infra/proxy/README.md` | Décision, vue infra, vue CI/CD, tableau des ports | Règle du dépôt : la vue change dans la même PR que le composant | + +Ce qui ne change pas : `docker-compose.yml`, la configuration Nginx, `infra/terraform`. + +## 4. Déroulé de l'après-midi + +| # | Qui | Quoi | Durée | +|---|---|---|---| +| 1 | **ineszang** (seule admin du dépôt) | Environnement `prod` : branche autorisée `main`, un relecteur requis. Environnement `rec` : branche `dev`. Settings > Actions : « Require approval for all outside collaborators ». Générer le jeton d'enregistrement du runner (Settings > Actions > Runners > New self-hosted runner, Linux x64) et le transmettre à Johan | 10 min | +| 2 | **Johan** | Déposer sa clé sur la VM : `ssh-copy-id -i ~/.ssh/id_ed25519.pub root@10.101.200.37`, mot de passe du compte administrateur local des postes de l'école | 2 min | +| 3 | Johan + Claude | **Fait à 15h** : branche locale `feat/deploy-rec-prod` avec tous les changements du §3, image frontend reconstruite avec succès, fusion Compose vérifiée pour les deux environnements. Reste : commit, push, PR vers `dev` | fait | +| 4 | Claude, par SSH | `scripts/provision-host.sh` sur la VM. Écrire les deux `.env` (secrets générés sur la VM, jamais dans git). Certificats : `PUBLIC_HOST=rec.enervision.local PUBLIC_IP=10.101.200.37 make tls-selfsigned` dans `rec`, idem avec `enervision.local` dans `prod`. Puis `make stack-up` dans chaque dossier | 20 min plus la construction des images | +| 5 | Johan, sur la VM | Installer le runner sous un utilisateur non-root membre du groupe `docker`, label `eni-g3`, en service systemd (`./config.sh --unattended --labels eni-g3`, `sudo ./svc.sh install && sudo ./svc.sh start`) | 10 min | +| 6 | Équipe | Merger la PR dans `dev` : la recette se redéploie seule. Ouvrir la PR `dev` vers `main` : la prod se déploie après approbation dans l'onglet Environments | 15 min | +| 7 | Tous | Vérifier depuis un poste de l'équipe, `/etc/hosts` renseigné : connexion, tableau de bord, Airflow par tunnel SSH | 15 min | + +Contrôle en fin de chaîne, depuis la VM : + +```bash +curl -k https://localhost/api/v1/health/ready # prod +curl -k https://localhost:8443/api/v1/health/ready # rec +docker compose -p enervision-prod ps +docker compose -p enervision-rec ps +``` + +## 5. Ce qui peut faire échouer la journée, et la parade + +| Risque | Parade | +|---|---| +| **8 Go de RAM pour deux stacks complètes** (deux Airflow, deux TimescaleDB, deux API) | Demander dès maintenant le passage à 32 Go, prévu par les consignes. En attendant : `TS_TUNE_MEMORY=2GB` et deux workers gunicorn pour Airflow. Si la RAM ne suit pas, démarrer la recette sans Airflow (`docker compose up -d --scale airflow-webserver=0 --scale airflow-scheduler=0`) | +| **Compose trop ancien sur la VM** (les marqueurs `!override` et `!reset` exigent 2.24.4) | `docker compose version` en premier. Sinon installer le paquet `docker-compose-plugin` depuis le dépôt Docker | +| **Pas de sortie Internet depuis la VM** | `curl -sI https://github.com` et `docker pull hello-world` avant tout. Sans sortie, ni construction d'image ni runner : déploiement manuel par `scp` d'images, plan B lourd | +| **Runner auto-hébergé sur un dépôt public** | Le workflow de déploiement ne s'exécute que sur `push` vers `dev` et `main`, jamais sur `pull_request`. Réglage d'approbation des PR externes (étape 1). Runner sous un utilisateur dédié, jamais root | +| **Premier démarrage avec un volume `pgdata` vide** | C'est le cas nominal sur la VM : `db/init` crée les bases `enervision`, `enervision_test` et `airflow`. Ne pas restaurer un volume de poste | +| **Le jury accepte mal un certificat auto-signé** | Dire pourquoi avant qu'on le demande : aucun DNS public, ACME câblé et documenté, ADR 0007. Un clic « continuer » dans le navigateur | +| **Conflit avec `feat/deploy`** (ineszang y a mergé `dev` à 14h06) | Partager ce document avant de pousser. La PR remplace `feat/deploy`, elle ne s'y ajoute pas | + +## 6. Ce que ça donne pour la grille + +- **EC03, CI/CD** : la chaîne ne s'arrête plus au merge. Deux environnements, déploiement + automatique en recette, promotion approuvée en production, journal des déploiements dans + l'onglet Environments de GitHub. +- **EC04, cloud et sécurisation** : une application déployée et fonctionnelle, une seule surface + exposée par environnement, secrets hors de git et hors de GitHub, base et Airflow joignables + uniquement par tunnel SSH. +- **Dossier EC01** : le choix 16 (runner auto-hébergé, déploiement automatique) passe de « non + fait » à « tenu ». Le choix 12 (Ansible) reste non fait, et la réponse est prête : le + durcissement de la machine n'est pas automatisé, le script de provisionnement en est la + première brique, Terraform pourra l'appeler. + +## 7. Après vendredi, si on continue + +Dans l'ordre de valeur : images construites une fois en CI et publiées sur GHCR, puis déployées +par digest (vraie promotion d'artefact). Racine Terraform `environments/eni-g3` qui provisionne +la machine et le runner à partir du script. Sauvegarde de `pgdata` par `pg_dump` planifié. +Monitoring (issue #26). Et seulement ensuite la bascule k3s, si elle garde un sens. diff --git a/docs/adr/0011-surveillance-de-derive-dans-le-backend.md b/docs/adr/0013-surveillance-de-derive-dans-le-backend.md similarity index 99% rename from docs/adr/0011-surveillance-de-derive-dans-le-backend.md rename to docs/adr/0013-surveillance-de-derive-dans-le-backend.md index a61976f..aec61b0 100644 --- a/docs/adr/0011-surveillance-de-derive-dans-le-backend.md +++ b/docs/adr/0013-surveillance-de-derive-dans-le-backend.md @@ -1,4 +1,4 @@ -# 0011 - La surveillance de dérive vit dans le backend et écrit sa propre table +# 0013 - La surveillance de dérive vit dans le backend et écrit sa propre table - Statut : accepté - Date : 2026-09-22 diff --git a/docs/architecture/00-vue-ensemble.md b/docs/architecture/00-vue-ensemble.md index 5819fd2..5d4ddb6 100644 --- a/docs/architecture/00-vue-ensemble.md +++ b/docs/architecture/00-vue-ensemble.md @@ -72,9 +72,9 @@ intercepteur répond à sa place tant que les endpoints n'existent pas. Voir Le lien `airflow --> db` est maintenant en trait plein : cinq DAGs tournent, deux pour l'entraînement et le scoring du modèle ML (issue #115), un pour la détection d'alertes et la -génération des recommandations (issue #116), et `historical_import` pour l'ingestion du dataset -historique (issue #119). L'orchestration de l'import API Mock et la réconciliation globale des -deux sources restent à compléter dans l'issue #15. +génération des recommandations (issue #116), `historical_import` pour le dataset historique +(issue #119) et `mock_api_import` pour l'ingestion horaire de l'API Mock (issue #15). +La réconciliation globale des données provenant des deux sources reste à compléter dans l'issue #15. Le lien `prom -.-> api` de même : l'API expose bien `/metrics` au format Prometheus, mais aucun collecteur ne vient le lire. @@ -86,18 +86,20 @@ collecteur ne vient le lire. | Backend | FastAPI, Python 3.14 | `apps/backend` | `En cours` | Factory, configuration, journalisation, 2 sondes de santé, `/metrics`, contrat OpenAPI versionné, routes `sites`, `alerts`, `recommendations`, `stats/summary`, `readings`, `sensors/status` et `predictions` en lecture (endpoints → services → repositories → models) | | Frontend | Angular 22, Node 24 | `apps/frontend` | `En cours` | Tableau de bord sur route `/dashboard`, authentification complète (garde de route, intercepteur de jeton), cinq services HTTP, graphiques Chart.js. `stats`/`alerts` sur fixtures, `predictions` branché sur l'API réelle | | Base | PostgreSQL 17 + TimescaleDB | `db` | `Fait` | Bootstrap de l'extension, base de test, chaîne Alembic. Schéma applicatif créé (`site`, `dataset`, `reading` en hypertable, `prediction`, `alert`, `recommendation`) | -| ML | LightGBM, MLflow | `ml` | `En cours` | Pipeline d'entraînement et de scoring (`enervision_ml.train`/`.score`, features par lags/moyennes glissantes partagées entre les deux, baseline de persistance saisonnière, suivi MLflow local), exposé en lecture via `GET /predictions`, orchestré par Airflow (`ml_train`/`ml_score`). Voir [ADR 0005](../adr/0005-modele-prediction-lightgbm.md) et [ML-START.md](../ML-START.md). Surveillance de dérive livrée côté backend (`app.monitoring.drift`, table `drift_report`, `GET /monitoring/drift`, DAG `derive`), voir [ADR 0011](../adr/0011-surveillance-de-derive-dans-le-backend.md) | +| ML | LightGBM, MLflow | `ml` | `En cours` | Pipeline d'entraînement et de scoring (`enervision_ml.train`/`.score`, features par lags/moyennes glissantes partagées entre les deux, baseline de persistance saisonnière, suivi MLflow local), exposé en lecture via `GET /predictions`, orchestré par Airflow (`ml_train`/`ml_score`). Voir [ADR 0005](../adr/0005-modele-prediction-lightgbm.md) et [ML-START.md](../ML-START.md). Surveillance de dérive livrée côté backend (`app.monitoring.drift`, table `drift_report`, `GET /monitoring/drift`, DAG `derive`), voir [ADR 0013](../adr/0013-surveillance-de-derive-dans-le-backend.md) | | Infra | Docker Compose, Nginx, Terraform, k3s single-node | `infra`, `docker-compose.prod.yml` | `En cours` | Reverse proxy et overlay de déploiement écrits et validés, jamais lancés sur le serveur ([ADR 0007](../adr/0007-terminaison-tls-et-reverse-proxy-nginx.md)). Provisionnement de la VM par Terraform, qui installe Docker, prépare les deux environnements et enregistre le runner, jamais appliqué ([ADR 0010](../adr/0010-terraform-provisionne-github-actions-deploie.md)). Module d'installation k3s jamais appliqué, aucune ressource Kubernetes déclarée | | Monitoring | Prometheus, Grafana, Alertmanager | `monitoring` | `Cible` | Rien, hors le `/metrics` exposé par l'API | -| ETL | Apache Airflow | `etl/airflow` | `En cours` | Webserver + scheduler (LocalExecutor) tournent via docker-compose, base de métadonnées Postgres dédiée. Cinq DAGs en sous-processus `uv run` : `ml_train`, `ml_score`, `alertes`, `historical_import` et `derive` (quotidien, surveillance de dérive). Le DAG historique orchestre `app.etl.historical_import` et charge `dataset`, `site` et `reading`. L'orchestration API Mock reste à compléter dans #15 | +| ETL | Apache Airflow | `etl/airflow` | `En cours` | Webserver et scheduler avec LocalExecutor via Docker Compose, sur une base PostgreSQL dédiée. Six DAGs en sous-processus `uv run` : `ml_train`, `ml_score`, `alertes`, `historical_import`, `mock_api_import` et `derive` (quotidien, surveillance de dérive). L'import historique reste manuel et l'import API Mock s'exécute chaque heure. La réconciliation globale des deux sources reste à compléter dans l'issue #15. | | CI/CD | GitHub Actions | `.github/workflows` | `En cours` | 7 workflows, 19 jobs : lint, typage, tests avec seuil de couverture bloquant, tests d'intégration sur TimescaleDB réel, audit de dépendances, SAST Bandit, quality gate SonarCloud, intégrité des DAGs Airflow, formatage et validation du Terraform. Déploiement continu vers la VM ENI écrit par `deploy.yml`, `dev` en recette et `main` en production après approbation ([ADR 0009](../adr/0009-deux-environnements-compose-sur-la-vm-eni.md)), mais jamais exécuté : la machine n'est pas provisionnée et le runner n'y est pas enregistré. Détail dans [50-cicd.md](50-cicd.md) | ## Flux bout en bout -Statut : `En cours`. **Le chemin de lecture tourne** : base, API et frontend. **Le chemin -d'ingestion dessiné ci-dessous n'existe pas** : les DAGs livrés (`ml_train`, `ml_score`, -issue #115 ; `alertes`, issue #116) orchestrent le pipeline ML et la détection d'alertes, pas -l'ingestion, qui reste lancée à la main par les scripts d'import (issues #15 et #16). +Statut : `En cours`. **Le chemin de lecture tourne** entre la base, l'API et le frontend. +**Le chemin d'ingestion est maintenant orchestré par Airflow** : `historical_import` charge le +dataset CSV/JSON sur déclenchement manuel et `mock_api_import` collecte chaque heure les mesures +de l'API Mock. Les DAGs `ml_train` et `ml_score` (issue #115), `alertes` (issue #116) et `derive` +(issue #45) portent le pipeline ML, la détection d'alertes et la surveillance de dérive. La +réconciliation globale des données provenant des deux sources reste à compléter dans l'issue #15. ```mermaid sequenceDiagram diff --git a/docs/architecture/10-infra.md b/docs/architecture/10-infra.md index bdcc894..1fbabda 100644 --- a/docs/architecture/10-infra.md +++ b/docs/architecture/10-infra.md @@ -54,7 +54,7 @@ Trois pièges sont documentés en tête du `docker-compose.yml`, ils ne se devin - `LocalExecutor` exécute les tâches comme sous-processus du **scheduler**, jamais de l'api-server : c'est le scheduler qui a besoin du volume `airflow_ml_state` (modèle, magasin MLflow). -### Airflow (issues #115, #116 et #119) +### Airflow (issues #15, #115, #116 et #119) Quatre services (Airflow 3.3), `docker compose profiles` non utilisés (démarrage explicite via `make airflow-up`, pas dans `make dev`) : @@ -87,6 +87,7 @@ l'[ADR 0008](../adr/0008-airflow-execute-le-code-du-backend.md). | `ml_score` | `0 * * * *` | `enervision_ml.score`, dans `/opt/ml/.venv` | | `alertes` | `15 * * * *` | `app.detection.internal_alerts` puis `app.cli generate-recommendations`, dans `/opt/backend/.venv` | | `historical_import` | manuelle | `app.etl.historical_import`, dans `/opt/backend/.venv` ; les fichiers de `data/raw` sont montés en lecture seule dans `/opt/data/raw` | +| `mock_api_import` | `45 * * * *` | `app.etl.mock_api_import`, dans `/opt/backend/.venv` ; importe l'heure précédant son déclenchement depuis l'API Mock | | `derive` | `30 5 * * *` | `app.monitoring.drift`, dans `/opt/backend/.venv` ; quotidien parce que sa fenêtre couvre 168 h, et sans reprise parce qu'une dérive n'est pas une panne passagère | Le DAG `historical_import` réutilise le pipeline historique existant sans dupliquer sa logique. @@ -94,6 +95,17 @@ Il reste manuel, car le dataset sert à initialiser l'environnement. Le montage `./data/raw:/opt/data/raw:ro` permet au scheduler de lire les fichiers CSV/JSON sans pouvoir les modifier. +Le DAG `mock_api_import` exécute le pipeline API Mock toutes les heures, à la minute `:45`. +Un `CronTriggerTimetable` explicite lui attribue un intervalle d'une heure, y compris lors d'un +déclenchement manuel. Il transmet cet intervalle au script backend et charge les mesures dans +les tables communes `site` et `reading`. Le décalage à `:45` laisse quinze minutes avant le +scoring exécuté à l'heure pile, puis quinze minutes supplémentaires avant les alertes à `:15`. +`max_active_runs=1` empêche deux exécutions du DAG de se chevaucher. + +Le DAG conserve `catchup=False` pour éviter un rattrapage massif depuis sa date de démarrage. +Une interruption du scheduler peut donc créer un intervalle manquant, qui devra être rejoué +explicitement par une opération de backfill. + **Pourquoi `alertes` tourne à la quinzième minute.** Sa règle `anomaly` compare une lecture à la `prediction` du même instant, que `ml_score` écrit à l'heure pile. Le décalage laisse le scoring finir. Aucune dépendance n'est déclarée entre les deux DAGs pour autant, ni `ExternalTaskSensor` ni diff --git a/docs/architecture/20-backend.md b/docs/architecture/20-backend.md index a99e6c4..1b6f9fc 100644 --- a/docs/architecture/20-backend.md +++ b/docs/architecture/20-backend.md @@ -235,7 +235,7 @@ n'ajoute rien. | Métrique | Ce qu'elle dit | |---|---| | `mae` | Erreur moyenne en kWh, la métrique même qu'optimise LightGBM | -| `bias` | Erreur moyenne **signée** : c'est elle qui distingue un modèle plus bruyant d'un modèle qui se trompe systématiquement du même côté. Lue et servie, elle ne fait basculer le verdict que sous `--bias-threshold`, faute d'un seuil en kWh transposable d'un site à l'autre ([ADR 0011](../adr/0011-surveillance-de-derive-dans-le-backend.md)) | +| `bias` | Erreur moyenne **signée** : c'est elle qui distingue un modèle plus bruyant d'un modèle qui se trompe systématiquement du même côté. Lue et servie, elle ne fait basculer le verdict que sous `--bias-threshold`, faute d'un seuil en kWh transposable d'un site à l'autre ([ADR 0013](../adr/0013-surveillance-de-derive-dans-le-backend.md)) | | `mape` | Comparable entre sites de tailles différentes, hors réalisés nuls | | `coverage_ratio` | Part des prévisions disponibles qui ont trouvé leur réalisé : mesure le pipeline, pas le modèle | | `insufficient_data_ratio` | Part des sites privés d'historique suffisant | @@ -246,7 +246,7 @@ d'observations, le service dit qu'il ne sait pas plutôt que de rendre un chiffr fenêtre est fermée à droite par un délai de grâce de 2 h, le temps que l'ingestion livre le réalisé de la dernière heure. `python -m app.monitoring.drift` l'exécute, le DAG `derive` l'ordonnance, et `GET /api/v1/monitoring/drift` sert le dernier rapport de chaque site. Les -arbitrages sont dans l'[ADR 0011](../adr/0011-surveillance-de-derive-dans-le-backend.md). +arbitrages sont dans l'[ADR 0013](../adr/0013-surveillance-de-derive-dans-le-backend.md). ### Détection d'alertes internes diff --git a/docs/architecture/40-data.md b/docs/architecture/40-data.md index c108c54..335bafd 100644 --- a/docs/architecture/40-data.md +++ b/docs/architecture/40-data.md @@ -301,7 +301,7 @@ Les lignes de `drift_report` sont écrites par `app.monitoring.drift`, ordonnanc `derive`. Une ligne dont le `site_id` est `NULL` porte le résultat global, tous sites confondus : c'est pourquoi l'unicité passe par un index sur `coalesce(site_id, '')` et non par une contrainte, qui ne dédoublonnerait jamais deux lignes globales. Le calcul, ses seuils et ce qu'il refuse de -comparer sont dans l'[ADR 0011](../adr/0011-surveillance-de-derive-dans-le-backend.md). +comparer sont dans l'[ADR 0013](../adr/0013-surveillance-de-derive-dans-le-backend.md). Les lignes de `recommendation` sont écrites par le moteur de règles du backend (`app/services/recommendation_rules.py`), déclenché par `POST /api/v1/recommendations/generate`, diff --git a/etl/README.md b/etl/README.md index d789d6b..94f8ba2 100644 --- a/etl/README.md +++ b/etl/README.md @@ -663,16 +663,22 @@ mock_api_import.py La logique d'extraction, de transformation et de chargement est donc disponible pour les deux sources de données du MVP. -Airflow tourne désormais réellement (`etl/airflow/`, `make airflow-up`) et orchestre le pipeline -ML (`ml_train`/`ml_score`, issue #115), la détection d'alertes et la génération des -recommandations (`alertes`, issue #116), ainsi que l'import historique -(`historical_import`, issue #119). +Airflow tourne désormais réellement (`etl/airflow/`, `make airflow-up`) et orchestre cinq DAGs : +le pipeline ML (`ml_train` et `ml_score`, issue #115), la détection d'alertes et la génération +des recommandations (`alertes`, issue #116), l'import historique (`historical_import`, +issue #119) et l'import périodique de l'API Mock (`mock_api_import`, issue #15). -Le DAG `historical_import` est déclenché manuellement. Il exécute -`app.etl.historical_import` avec les fichiers montés en lecture seule depuis `data/raw` vers -`/opt/data/raw`. L'orchestration de l'import API Mock et la réconciliation globale des deux -sources restent couvertes par l'issue #15. +Le DAG `mock_api_import` s'exécute chaque heure, à la minute `:45`. Il appelle +`app.etl.mock_api_import` avec un intervalle explicite d'une heure et une limite de 1 000 lectures +par site. Les deux pipelines normalisent leurs données vers les tables communes `site` et +`reading`, tout en conservant leur source (`csv` ou `api_history`). La réconciliation globale +des deux sources reste à compléter dans l'issue #15. -Airflow permet de planifier les traitements, gérer leur ordre d'exécution, suivre leur état et remonter les erreurs. Il ne remplace pas la logique ETL Python existante : les scripts actuels restent responsables de l'extraction, de la validation, de la transformation et du chargement. `etl/airflow/dags/ml_train.py`, `ml_score.py` et `alertes.py` et `historical_import.py` montrent le patron retenu (des `BashOperator` qui invoquent le script tel quel, dans l'environnement `uv` que l'image embarque pour lui). +Le DAG `mock_api_import` exécute `app.etl.mock_api_import` toutes les heures. Chaque exécution +traite l'intervalle Airflow précédent. Les deux pipelines normalisent leurs données vers les +tables communes `site` et `reading`, tout en conservant leur source (`csv` ou `api_history`). + +Airflow permet de planifier les traitements, gérer leur ordre d'exécution, suivre leur état et remonter les erreurs. Il ne remplace pas la logique ETL Python existante : les scripts actuels restent responsables de l'extraction, de la validation, de la transformation et du chargement. `etl/airflow/dags/ml_train.py`, `ml_score.py`, `alertes.py`, `historical_import.py` et +`mock_api_import.py` montrent le patron retenu (des `BashOperator` qui invoquent le script tel quel, dans l'environnement `uv` que l'image embarque pour lui). Le pipeline Data servira ensuite à préparer les données nécessaires au modèle de Machine Learning. diff --git a/etl/airflow/dags/mock_api_import.py b/etl/airflow/dags/mock_api_import.py new file mode 100644 index 0000000..f0043d0 --- /dev/null +++ b/etl/airflow/dags/mock_api_import.py @@ -0,0 +1,61 @@ +"""DAG d'import périodique des données de l'API Mock EnerVision (issue #15). + +Orchestre le pipeline existant `app.etl.mock_api_import` sans dupliquer sa logique ETL. +Chaque exécution traite l'heure précédant son déclenchement. + +Le pipeline backend reste responsable de la validation, de la normalisation, du suivi de la +qualité, de l'idempotence et du chargement dans PostgreSQL/TimescaleDB. +""" + +from __future__ import annotations + +from datetime import datetime, timedelta + +from airflow.providers.standard.operators.bash import BashOperator +from airflow.sdk import DAG +from airflow.timetables.trigger import CronTriggerTimetable + +# Le backend possède son propre environnement uv dans l'image Airflow (ADR 0008). +COMMANDE_BACKEND = "cd /opt/backend && env -u VIRTUAL_ENV uv run --no-sync python -m" + +# Le pipeline backend et l'API acceptent au maximum 1 000 lectures par site. +# Cette marge évite de perdre silencieusement une lecture si une heure en contient plus de 60. +LIMITE_LECTURES = 1000 + +# Deux reprises donnent trois tentatives au total. Même dans le pire cas, l'exécution reste +# inférieure au pas horaire du DAG. +NOMBRE_REPRISES = 2 +DELAI_ENTRE_REPRISES = timedelta(minutes=2) +PLAFOND_PAR_TENTATIVE = timedelta(minutes=10) + +# L'intervalle est déclaré explicitement pour ne pas dépendre de la valeur du paramètre Airflow +# `create_cron_data_intervals`. Le déclenchement à :45 laisse quinze minutes avant `ml_score`, +# exécuté à l'heure pile, puis avant `alertes`, exécuté à :15. +PLANIFICATION = CronTriggerTimetable( + "45 * * * *", + timezone="UTC", + interval=timedelta(hours=1), +) + +with DAG( + dag_id="mock_api_import", + description="Importe chaque heure les données de l'API Mock dans site et reading.", + schedule=PLANIFICATION, + start_date=datetime(2026, 1, 1), + catchup=False, + # Deux exécutions simultanées pourraient demander et traiter le même intervalle. + max_active_runs=1, + tags=["etl", "mock-api"], +) as dag: + BashOperator( + task_id="import_mock_api", + bash_command=( + f"{COMMANDE_BACKEND} app.etl.mock_api_import " + "--start-time \"{{ data_interval_start.strftime('%Y-%m-%dT%H:%M:%S') }}\" " + "--end-time \"{{ data_interval_end.strftime('%Y-%m-%dT%H:%M:%S') }}\" " + f"--limit {LIMITE_LECTURES}" + ), + retries=NOMBRE_REPRISES, + retry_delay=DELAI_ENTRE_REPRISES, + execution_timeout=PLAFOND_PAR_TENTATIVE, + ) diff --git a/etl/airflow/tests/test_dags.py b/etl/airflow/tests/test_dags.py index bc6cb91..d03dd97 100644 --- a/etl/airflow/tests/test_dags.py +++ b/etl/airflow/tests/test_dags.py @@ -1,22 +1,31 @@ """Tests d'integrite des DAGs : s'importent sans erreur, structure attendue. Pas d'execution reelle des taches (ca reclamerait le conteneur avec `uv`/`enervision_ml`), juste la definition.""" -from datetime import timedelta +from datetime import datetime, timedelta from pathlib import Path import pytest from airflow.dag_processing.dagbag import DagBag from airflow.sdk import BaseOperator +from airflow.timetables.trigger import CronTriggerTimetable DAGS_FOLDER = Path(__file__).resolve().parent.parent / "dags" -DAG_IDS = ["ml_train", "ml_score", "alertes", "historical_import", "derive"] +DAG_IDS = [ + "ml_train", + "ml_score", + "alertes", + "historical_import", + "mock_api_import", + "derive", +] TACHES = [ ("ml_train", "train"), ("ml_score", "score"), ("alertes", "detection"), ("alertes", "recommandations"), ("historical_import", "import_historical"), + ("mock_api_import", "import_mock_api"), ("derive", "derive"), ] @@ -53,6 +62,19 @@ def test_historical_import_has_no_schedule(dagbag: DagBag) -> None: assert dagbag.dags["historical_import"].schedule is None +def test_mock_api_import_uses_an_explicit_hourly_interval(dagbag: DagBag) -> None: + timetable = dagbag.dags["mock_api_import"].timetable + + assert isinstance(timetable, CronTriggerTimetable) + assert timetable.serialize()["expression"] == "45 * * * *" + + manual_interval = timetable.infer_manual_data_interval( + run_after=datetime.fromisoformat("2026-09-22T12:30:00+00:00"), + ) + + assert manual_interval.end - manual_interval.start == timedelta(hours=1) + + def test_ml_train_task_calls_the_training_module(dagbag: DagBag) -> None: tache = dagbag.dags["ml_train"].get_task("train") assert "enervision_ml.train" in tache.bash_command @@ -85,6 +107,20 @@ def test_historical_import_uses_the_expected_source_files(dagbag: DagBag) -> Non assert "--metadata /opt/data/raw/dataset_metadata.json" in commande +def test_mock_api_import_calls_the_existing_backend_module(dagbag: DagBag) -> None: + commande = dagbag.dags["mock_api_import"].get_task("import_mock_api").bash_command + + assert "app.etl.mock_api_import" in commande + + +def test_mock_api_import_uses_the_airflow_data_interval(dagbag: DagBag) -> None: + commande = dagbag.dags["mock_api_import"].get_task("import_mock_api").bash_command + + assert "--start-time \"{{ data_interval_start.strftime('%Y-%m-%dT%H:%M:%S') }}\"" in commande + assert "--end-time \"{{ data_interval_end.strftime('%Y-%m-%dT%H:%M:%S') }}\"" in commande + assert "--limit 1000" in commande + + @pytest.mark.parametrize("task_id", ["detection", "recommandations"]) def test_alertes_tasks_run_in_the_backend_environment(dagbag: DagBag, task_id: str) -> None: # Le backend a son propre venv dans l'image, distinct de celui de ml/ (ADR 0008). @@ -96,6 +132,12 @@ def test_historical_import_runs_in_the_backend_environment(dagbag: DagBag) -> No assert "/opt/backend" in commande +def test_mock_api_import_runs_in_the_backend_environment(dagbag: DagBag) -> None: + commande = dagbag.dags["mock_api_import"].get_task("import_mock_api").bash_command + + assert "/opt/backend" in commande + + def test_alertes_generates_recommendations_after_detecting(dagbag: DagBag) -> None: # `recommendation.alert_id` est une cle etrangere `NOT NULL` : la generation n'a rien a lire # tant que la detection n'a pas ecrit. @@ -137,6 +179,14 @@ def duree_au_pire(tache: BaseOperator) -> timedelta: return (tache.retries + 1) * tache.execution_timeout + tache.retries * tache.retry_delay +def test_mock_api_import_worst_case_stays_below_its_hourly_step( + dagbag: DagBag, +) -> None: + tache = dagbag.dags["mock_api_import"].get_task("import_mock_api") + + assert duree_au_pire(tache) < timedelta(hours=1) + + def test_alertes_worst_case_stays_below_its_hourly_step(dagbag: DagBag) -> None: # Les deux taches s'enchainent : c'est leur somme, reprises comprises, qui doit tenir dans le # pas horaire, sinon `max_active_runs=1` fait attendre l'execution suivante. @@ -160,6 +210,10 @@ def test_historical_import_retries_after_a_transient_failure(dagbag: DagBag) -> assert dagbag.dags["historical_import"].get_task("import_historical").retries >= 1 +def test_mock_api_import_retries_after_a_transient_failure(dagbag: DagBag) -> None: + assert dagbag.dags["mock_api_import"].get_task("import_mock_api").retries >= 1 + + def test_derive_runs_once_a_day(dagbag: DagBag) -> None: assert dagbag.dags["derive"].timetable.expression == "30 5 * * *"