---
title: "Architecture de Kodama"
description: "Comprendre les liens entre API Kodama, charges Kubernetes, PostgreSQL, JetStream, Git, stockage objets, fournisseurs de modèles et revue humaine."
canonical_url: https://optimi.com/fr/docs/kodama/architecture
md_url: https://optimi.com/fr/docs/kodama/architecture.md
last_updated: 2026-10-23
---

# Architecture

Kodama sépare **le plan de contrôle**, propriétaire des autorisations et de
l’état durable, des **charges d’exécution**, qui exécutent commandes et agents.
Helm déploie le plan de contrôle et les politiques des tenants ; le serveur crée
un Job Kubernetes ordinaire pour chaque tentative d’étape exécutable.

## Vue du système

**Un plan de contrôle, des exécutions limitées à leur périmètre**

![CLI et intégrations API s’authentifient par OIDC auprès du plan de contrôle Kodama. Celui-ci utilise PostgreSQL, JetStream, Git et S3, puis lance des Jobs tenants dont les rappels, modèles et outils passent par des interfaces limitées.](/diagrams/kodama/architecture-fr.svg)

*État durable et identifiants restent derrière le plan de contrôle. Les Jobs ne reçoivent que les droits nécessaires à leur tentative.*

Le chart initial exécute une réplique serveur avec la stratégie `Recreate`.
PostgreSQL et JetStream sont exploités séparément. Git, stockage compatible S3,
registre OCI, OIDC et KMS cloud complètent l’installation.

## Responsabilité de chaque backend

| Backend | Données et responsabilité | Éléments à conserver |
| --- | --- | --- |
| PostgreSQL | Travail, exécutions, tentatives, appartenances, configuration, validations, déploiements, audit et coordination événementielle | Sauvegardes et WAL avec le code, les objets et les clés correspondants |
| NATS JetStream | Transport durable des événements métier et coordination des workers | Streams et consommateurs durables, avec reprise outbox/inbox |
| Git | Commits acceptés, branches de travail et références protégées | Chaque commit référencé par une exécution, revue, version ou point de reprise |
| Stockage compatible S3 | Rapports, traces, artefacts et journaux conservés | Contenu des objets et empreintes vérifiées |
| Registre OCI | Images exécutables et livrables | Images figées par empreinte pour les exécutions et versions supportées |
| KMS | Clés d’enveloppe des identifiants chiffrés par périmètre | Versions nécessaires aux données actives et restaurables |

PostgreSQL fait autorité sur l’état. Une transaction écrit ensemble son changement
métier et un événement dans l’outbox ; un producteur transmet les événements
validés à JetStream. Les consommateurs dédupliquent avec l’inbox. La réconciliation
récupère notifications manquées et travail interrompu. Une panne du broker
n’efface pas le travail accepté, mais JetStream reste une dépendance obligatoire.

## Vie d’une tentative

1. **Admission :** authentifier l’appelant, vérifier droits et limites, puis
   figer définition, source, révision de contenu et configuration.
2. **Dispatch :** enregistrer une réservation et demander à Kubernetes de créer
   ou adopter la charge au nom déterministe, hors transaction de base.
3. **Admission runtime :** lier l’identité de charge et échanger les éléments
   d’admission contre un jeton de tentative de courte durée.
4. **Exécution :** `kodama step` prépare la source, lance la commande déclarée
   et collecte ses résultats dans les limites de ressources et de temps.
5. **Publication :** réserver et envoyer les artefacts ; pour un écrivain,
   proposer la source et comparer la pointe Git attendue avant publication.
6. **Finalisation :** vérifier autorité, types, provenance des artefacts et
   publication avant de valider le résultat de l’étape.
7. **Résolution :** réconcilier annulation ou incertitude, conserver les journaux
   et retirer les charges dont le résultat durable est établi.

Une réponse perdue ne prouve pas un échec. Le processus de contrôle suivant
observe la charge ou l’effet distant avant de décider si une autre action est
nécessaire. Un Job étranger portant le même nom n’est pas adopté. Une tentative
annulée ne peut finaliser un nouveau résultat avec un ancien jeton.

## Espaces Git et stockage d’exécution

Un espace de travail est un contexte source logique, pas un Pod de développement
persistant. Chaque tentative reçoit un espace temporaire privé et un commit figé.
Git conserve les points de reprise acceptés ; S3 conserve les sorties. Supprimer
le stockage temporaire ne supprime donc ni code accepté ni rapports.

Les étapes en lecture ne publient pas. Les écrivains sont ordonnés et comparent
la pointe attendue pour détecter un push humain concurrent plutôt que l’écraser.
Les lecteurs suivants choisissent le commit initial ou celui d’un écrivain
ancêtre. L’évolution d’une branche ne modifie jamais silencieusement les entrées
d’une exécution existante.

## Isolation et identifiants

L’autorisation couvre lectures et écritures API, journaux, événements, artefacts
et source. La propriété tenant/projet suit chaque ressource. Le rôle PostgreSQL
du serveur n’est ni propriétaire ni superutilisateur et ne possède pas
`BYPASSRLS` ; les migrations utilisent une identité propriétaire distincte.

L’exécution Kubernetes utilise des namespaces tenants, Pod Security restreint,
quotas, volumes bornés, comptes de charge sans jeton et sorties réseau explicites.
Les charges ne reçoivent pas les identifiants base, NATS ou cluster du plan de
contrôle. Ce profil vise des ingénieurs de confiance sur des conteneurs ordinaires ;
la séparation par namespace n’est pas un sandbox général pour du code public hostile.

Les secrets sont des références versionnées. L’admission fige la version
autorisée ; la lecture pour usage revérifie l’autorité. Un déploiement reçoit
uniquement les identifiants de sa cible. Gardez leurs valeurs hors des documents
de pipeline, commits et artefacts.

## Modèles et outils

Un profil d’agent sélectionne une image de harness qualifiée, des instructions,
un modèle, des outils et des limites. L’agent s’exécute comme une tentative
ordinaire. Ses requêtes modèle passent par une passerelle compatible OpenAI ;
les outils externes passent par un proxy MCP. Les identifiants des fournisseurs
restent côté serveur.

La politique d’installation définit destinations, capacités du wrapper et
actions runtime. Les paramètres modèle et outils du projet restreignent ces
choix. Révoquer une approbation interdit de nouveaux usages sans réécrire
l’historique. Un flux modèle interrompu ou un résultat d’outil inconnu est
enregistré explicitement ; un appel pouvant produire un effet n’est pas répété
à l’aveugle.

## Frontières d’intégration

| Interface | Appelant et usage |
| --- | --- |
| `/api/v1` | Utilisateurs et intégrations authentifiés : travail, pipelines, exécutions, validations et livraison |
| Flux d’événements projet/exécution | Observateurs autorisés avec curseurs durables et `Last-Event-ID` |
| `/runtime/v1` | Points d’entrée limités à la tentative : admission, contexte figé, artefacts et résultats |
| Passerelle modèle / proxy MCP | Tentatives agent autorisées utilisant leur jeton runtime |
| Hook Git / adaptateur métier | Signaux authentifiés traduits en source exacte ou entrées typées |
| ChatOps sortant | Notifications durables contenant des liens vers des ressources authentifiées |

Les intégrateurs utilisent le [document OpenAPI public](https://github.com/optimiware/kodama/blob/main/api/openapi.yaml)
ou le client généré. Ils ne se connectent pas directement aux tables et ne
publient pas d’événements internes à la place des opérations API autorisées.

Suite : **[installation Helm](/fr/docs/kodama/premiers-pas)** ou
**[exemples de pipelines](/fr/docs/kodama/guide-developpeur)**.