Aller au contenu principal

A12 - Workflow d'approbation

GroupeTechnologieStatutServicePhase de la feuille de routeContrats
A - Gouvernance, identité et sécuritéPostgreSQL + API (adaptateur Temporal optionnel)à développerapprovals3audit-event

Retour à l'index - English

Rôle et responsabilités​

Demandes d'approbation durables avec séparation des tâches pour promotions, outils sensibles et exceptions.

Modèle de données​

Tables (schéma eai, chaque table tenant porte tenant_id uuid NOT NULL avec une politique RLS sur current_setting('app.tenant_id', true)::uuid) : eai.approvals, eai.audit_events.

Endpoints API​

  • GET /v1/approvals
  • POST /v1/approvals
  • GET /v1/approvals/{id}
  • POST /v1/approvals/{id}/decide
POST /v1/approvals HTTP/1.1
Host: <control-plane-host>
X-API-Key: eai_xxx_secret
Accept-Language: fr
Content-Type: application/json

{"action": "deploy", "resource_type": "agent", "resource_id": "invoice-agent", "reason": "Promote version 1.4.0 to production", "approver_roles": ["security_officer"], "quorum": 1}
{
  "id": "a1ab0542-301d-4eef-a8be-64d5173ad21e",
  "requester": "alice",
  "action": "deploy",
  "resource_type": "agent",
  "resource_id": "invoice-agent",
  "run_id": null,
  "reason": "Promote version 1.4.0 to production",
  "payload": {},
  "quorum": 1,
  "approver_roles": ["security_officer"],
  "status": "pending",
  "expires_at": "2026-10-31T01:35:52.793643Z",
  "decided_at": null,
  "created_at": "2026-10-30T01:35:52.792996Z",
  "updated_at": "2026-10-30T01:35:52.792996Z",
  "decisions": [],
  "approvals_count": 0
}

Les erreurs utilisent l'enveloppe commune {"error": {"code", "message", "message_i18n", "details", "request_id"}} ; les listes sont paginées avec limit et cursor.

Promotions contrôlées​

Faire passer un modèle, un outil ou un agent à approved ou active ouvre une demande d'approbation (action: promotion, rôles approbateurs tenant_admin et security_officer) et répond 202 avec approval_id. Le demandeur ne peut pas l'approuver. À l'approbation : un système classé à haut risque (dernière évaluation de risque high, ou agent de risk_level high) exige une évaluation de risque approuvée ; puis les suites d'évaluation bloquantes de la cible s'exécutent (evaluation.on_promotion) ; le statut n'est appliqué que si elles passent. Le résultat est enregistré dans payload.promotion et audité (promotion.request, promotion.apply, promotion.blocked). Les skills (POST /v1/skills/{name}/status) et serveurs MCP (POST /v1/mcp/servers/{id}/status) répondent 202 de la même façon ; les plugins deviennent actifs par l'installation, protégée par la relation owner ; une skill ne peut plus passer à approved hors d'une promotion approuvée (409 promotion_requires_approval). Les retraits restent immédiats et audités. Les modèles de plateforme modifiés par un admin de plateforme sans tenant ne sont pas couverts, les approbations étant rattachées à un tenant.

Utilisation des SDK​

Python (enterprise_ai):

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_xxx_secret")
items = client.approvals.list()

TypeScript (@enterprise-ai/sdk):

import { EnterpriseAI } from "@enterprise-ai/sdk";

const eai = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY });
const items = await eai.approvals.list();

Java (enterprise-ai-java):

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .build();
var items = client.approvals().list();

Go (enterprise-ai-go):

client, _ := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")))
items, err := client.Approvals.List(ctx)

Configuration​

  • Environnement : EAI_DATABASE_URL, EAI_OTEL_EXPORTER_OTLP_ENDPOINT.
  • Valeurs Helm : controlPlane.enabled, controlPlane.replicas, controlPlane.resources, controlPlane.config.

Contrôles de sécurité​

  • Authentification par JWT OIDC, clé API tenant avec scopes, ou mTLS SPIFFE ; le tenant est résolu depuis l'identifiant, jamais depuis le corps.
  • Autorisation par décisions OpenFGA et OPA ; chaque mutation et décision écrit une ligne eai.audit_events chaînée par hash.
  • Les secrets ne sont jamais renvoyés par l'API ; TLS partout ; les politiques réseau Cilium restreignent qui peut joindre le service.

Séparation des tâches : le demandeur ne peut pas approuver sa propre demande (409 separation_of_duties).

Observabilité​

  • Métriques : eai_approval_workflow_requests_total, eai_approval_workflow_errors_total, eai_approval_workflow_latency_seconds (Prometheus).
  • Traces : spans OpenTelemetry eai.approvals.* avec propagation W3C traceparent, spans IA envoyés à Opik.
  • Actions d'audit : approval.request, approval.decide, approval.expire, policy.evaluate.

Aspects FinOps​

Le coût d'exploitation est imputé par tenant et projet via les labels des Usage Events et les requêtes de ressources Kubernetes ; pas de coût direct par appel.

Modes de défaillance et résilience​

  • Réplicas sans état derrière l'API Gateway, PostgreSQL HA pour l'état ; la sonde GET /readyz retire les pods défaillants.
  • Système externe indisponible : échec fermé pour les décisions de sécurité, code d'erreur explicite, aucun contournement silencieux.

Adoption autonome (client d'un client)​

Un client d'un client peut adopter cette brique seule avec le sous-client SDK Python client.approvals (TS eai.approvals, Java client.approvals(), Go client.Approvals). Déploiement minimal : Control Plane API + PostgreSQL + Keycloak (ou clés API), le Control Plane charge tous les domaines de services/control-plane/src/eai/domains ; les composants optionnels du chart se coupent dans deploy/helm/enterprise-ai/values.yaml (vllm.enabled, qdrant.enabled, nats.enabled, workers.enabled).

Tests d'acceptation​

  1. Un tenant ne peut ni lire ni modifier les ressources d'un autre tenant (test RLS).
  2. Chaque mutation produit un événement d'audit vérifiable par GET /v1/audit/verify.
  3. Les erreurs sont renvoyées en anglais et en français selon Accept-Language.