---
title: "Exploiter Kodema : installer, mettre à niveau, restaurer"
description: "Choisir une installation Kodema, déployer les charts de référence sur Kubernetes, suivre santé et métriques, mettre à niveau, restaurer : limites de la 0.2.1."
canonical_url: https://optimi.com/fr/docs/kodema/exploitation
md_url: https://optimi.com/fr/docs/kodema/exploitation.md
language: fr
alternates:
  - lang: en
    url: https://optimi.com/en/docs/kodema/operations
    md_url: https://optimi.com/en/docs/kodema/operations.md
last_updated: 2026-11-14
---

# Exploitation

Cette page s’adresse à la personne qui installe et exploite Kodema. Elle résume
les runbooks du dépôt pour **Kodema 0.2.1** et renvoie vers eux pour les
procédures.

## Choisir une installation

| Installation | À utiliser pour | Identité | Clés |
| --- | --- | --- | --- |
| **`kodema up`** | Essayer Kodema et développer des pipelines sur votre machine | Connexion intégrée, quatre personas, sans mot de passe | Fichier de clés local |
| **Bundle Podman** (`deploy/podman`) | Une installation de test sur un seul hôte avec un fournisseur d’identité distinct ; le test de fumée de la version s’exécute dessus | OAuthSonas, un fournisseur de développement | Fichier de clés local |
| **Kubernetes** (charts Helm, racines OpenTofu) | Production | Votre fournisseur OIDC | Un KMS cloud |

Les deux premières sont des environnements `test` : un seul hôte, des
opérateurs locaux de confiance. Seul le déploiement Kubernetes exécute le
profil `production`, qui refuse les adaptateurs de test.

## Exploiter une installation locale

Le **[démarrage rapide](/fr/docs/kodema/premiers-pas)** couvre `kodema up`.
Pour l’exploitation au quotidien :

```sh
kodema status            # --json for a machine-readable report
kodema up                # safe to repeat; renews the credentials
kodema down              # stop, keep the state
kodema down --purge      # remove containers, volumes and state
```

- L’état se trouve dans `~/.kodema/instances/<name>` : l’autorité de
  certification, les certificats, le fichier de clés, les jetons et `env.sh`.
- Les jetons d’administrateur durent 24 heures et l’identifiant du service Git
  8 heures. `kodema up` les renouvelle.
- `kodema up --name <name> --listen <address>` lance une seconde installation.
- Pour mettre à niveau, relancez l’installateur, puis `kodema up`.

Le bundle Podman installe l’image publiée à partir d’une copie de travail du
dépôt à la même version :

```sh
git clone --branch v0.2.1 https://github.com/optimiware/kodema && cd kodema
podman pull ghcr.io/optimiware/kodema/kodema:0.2.1
KODEMA_LOCAL_KODEMA_IMAGE=ghcr.io/optimiware/kodema/kodema:0.2.1 ./deploy/podman/install.sh
```

Il nécessite Podman 5, `git` 2.44, `jq`, `openssl`, `curl` et `socat`. Son
[runbook](https://github.com/optimiware/kodema/blob/master/docs/runbooks/podman-quickstart.md)
couvre la connexion, le provisionnement d’un dépôt de projet, une tâche
protégée, le renouvellement des identifiants et le dépannage.

## Ce que publie une version

| Artefact | Emplacement |
| --- | --- |
| `kodema` et `kodactl` pour Linux et macOS, amd64 et arm64 | Archives jointes à la [version GitHub](https://github.com/optimiware/kodema/releases), avec `SHA256SUMS` |
| L’image `kodema`, `linux/amd64` et `linux/arm64` | `ghcr.io/optimiware/kodema/kodema:<version>` ; les notes de version donnent l’empreinte |
| Les charts `kodema` et `kodema-stack` | `oci://ghcr.io/optimiware/kodema/charts` |

`latest` suit les versions qui ne sont pas des préversions. Une version publiée
n’est jamais remplacée. Rien n’est signé et aucun SBOM n’est produit. En
production, épinglez l’image par l’empreinte indiquée dans les notes de version.

## Déployer sur Kubernetes

Le dépôt fournit **des déploiements de référence, pas une infrastructure de
niveau production**. Considérez chaque valeur par défaut comme un point de
départ à relire, dimensionner et tester. Le
[guide de déploiement en production](https://github.com/optimiware/kodema/blob/master/docs/runbooks/production-deployment.md)
constitue la procédure ; cette section en est la carte.

**Ce qui est fourni**

| Élément | Ce qu’il vous apporte |
| --- | --- |
| Racines OpenTofu `deploy/scw`, `deploy/gcp`, `deploy/aws` | Un cluster, un PostgreSQL managé, une clé KMS, un réseau privé et un état distant |
| Chart `kodema` | Un Deployment du plan de contrôle, un Service HTTPS, le RBAC, un volume de journaux conservés, des namespaces de tenant avec limites et politiques réseau |
| Chart `kodema-stack` | Le chart applicatif plus un StatefulSet NATS JetStream en TLS |
| `scripts/deploy`, `scripts/bootstrap-secrets`, `scripts/bootstrap-state`, `scripts/image` | Le cycle de vie OpenTofu et Helm, les Secrets du cluster, la construction de l’image |

**Ce qui n’est pas inclus**

- **Pas de haute disponibilité du plan de contrôle.** Une seule réplique avec
  un déploiement `Recreate` ; une mise à niveau entraîne une courte
  interruption.
- **Pas de cluster NATS.** Une seule réplique ; les événements persistent dans
  PostgreSQL.
- **Pas d’ingress.** Le chart génère un Service `ClusterIP` sur le port 8443.
  L’exposition publique, le DNS et un certificat externe sont à votre charge.
- **Pas de gestionnaire de certificats, de pile de supervision ni
  d’automatisation des sauvegardes** au-delà des sauvegardes propres à la base
  de données managée.
- **Pas de quota de ressources** par namespace de tenant, seulement un
  `LimitRange`.

**État par cloud**

| | Scaleway | Google Cloud | AWS |
| --- | --- | --- | --- |
| Cluster | Kapsule | GKE | EKS |
| Service de clés | Key Manager (`scw-kms`) | Cloud KMS (`gcp-kms`) | AWS KMS (`aws-kms`) |
| Identifiant KMS | Clé d’API statique | Workload Identity | IRSA |
| A fonctionné en conditions réelles | Oui, pour la 0.1.0 | Non | Non |

Les trois sont des cibles prises en charge. Scaleway est la seule à avoir
fonctionné en conditions réelles ; AWS et GCP sont implémentés et n’ont pas été
validés sur un cloud réel.

**La séquence**

```sh
scripts/bootstrap-state <scw|gcp|aws> --project <id>      # once per cloud account; --account for aws
scripts/deploy <cloud> init
scripts/deploy <cloud> plan
scripts/deploy <cloud> apply
scripts/deploy <cloud> kubeconfig
scripts/bootstrap-secrets <cloud>
scripts/deploy <cloud> migrate                            # before the controller serves traffic
scripts/deploy <cloud> helm
```

`migrate` et `helm` ont besoin de l’image, épinglée par empreinte, dans
`KODEMA_IMAGE_REPOSITORY` et `KODEMA_IMAGE_DIGEST`. Ensuite,
`kodema bootstrap-admin` crée le premier tenant et le premier administrateur à
partir d’un jeton OIDC.

**Exigences de production imposées par le serveur**

- NATS en TLS : une seule URL `tls://`.
- PostgreSQL avec `sslmode=verify-full` sur les quatre connexions de rôle.
- Exactement un KMS cloud, avec une référence de clé de la famille
  correspondante.
- Un émetteur OIDC en HTTPS : `KODEMA_OIDC_ISSUER`, `KODEMA_OIDC_AUDIENCE`,
  `KODEMA_OIDC_JWKS_URL` et `KODEMA_OIDC_TENANT_CLAIM`.

**Réseau**

Chaque tenant reçoit un namespace `kodema-tenant-<tenant>` dont le trafic
entrant et sortant est refusé par défaut. Les charges de travail peuvent
joindre le DNS du cluster, le plan de contrôle et, lorsqu’il est activé, le
service Git. Toute autre destination, comme un registre de paquets, doit être
ajoutée délibérément, par FQDN lorsque le cluster utilise Cilium. Les charges
de travail des tenants n’atteignent jamais PostgreSQL ni NATS.

**Blocs optionnels**, désactivés par défaut : `gitService` (un StatefulSet
`kodema git serve` par tenant, avec un volume conservé à la désinstallation) et
`services` (un Deployment `kodema services` par adaptateur). La passerelle de
modèles, le proxy MCP et les registres privés nécessitent une surcouche de
l’opérateur : le chart n’a pas de valeurs pour eux.

## Santé et métriques

| Point d’accès | Signification |
| --- | --- |
| `GET /healthz` | Le processus peut répondre. Il n’appelle aucune dépendance |
| `GET /readyz` | 200 uniquement lorsque PostgreSQL, le broker et le fournisseur de clés répondent tous ; sinon 503 |
| `GET /metrics` | Texte Prometheus : `kodema_publication_backlog`, `kodema_consumer_lag`, `kodema_pending_cleanup`, et les compteurs `kodema_refused_pushes_total`, `kodema_refused_reports_total`, `kodema_dependency_errors_total` |

Les trois sont servis sur l’écouteur HTTPS sans authentification. Le chart ne
fournit ni configuration de collecte, ni tableau de bord, ni règle d’alerte.
Alertez au minimum sur :

| Signal | Pourquoi c’est important |
| --- | --- |
| `/readyz` différent de 200 pendant cinq minutes | Une dépendance est en panne ; aucun nouveau travail ne peut être admis en sécurité |
| Redémarrages de pods | Un refus de configuration, un problème de certificat ou de clé, ou une boucle de plantages |
| Arriéré de publication en hausse | Les événements n’atteignent pas NATS. Les exécutions avancent quand même |
| Nettoyage en attente avec tentatives épuisées | Un Job ou un volume ne peut pas être supprimé ; la capacité est menacée |
| Sauvegarde de la base plus ancienne que votre objectif | La fenêtre de perte de données est trop large |
| Volume de journaux conservés ou volume JetStream au-dessus de 80 % | La conservation des journaux et la publication sont limitées par la capacité |

Une panne du broker dégrade la publication et les journaux en direct ; elle
n’arrête ni les exécutions, ni les réponses aux demandes, ni les échéances.

## Inspecter le nettoyage d’une exécution

Le résultat d’une exécution et le nettoyage de ses ressources sont
indépendants. `kodactl inspect <execution-id>` renvoie un objet `cleanup` avec
son `state` (`none`, `pending` ou `complete`), les identités de la charge de
travail et de l’espace de travail, les tentatives et la dernière erreur.

Un nettoyage en attente dont les tentatives sont épuisées est visible, pas
terminé. **Ne supprimez pas le Job pour que l’enregistrement paraisse
propre** : supprimer un Job Kubernetes ne prouve pas que le processus s’est
arrêté, et un arrêt incertain bloque le passage de relais de l’espace de
travail.

## Mettre à niveau

1. Lisez les migrations de la version cible. Repérez les verrous exclusifs ou
   les réécritures volumineuses.
2. Effectuez ou vérifiez une sauvegarde de la base de données, et confirmez que
   le Secret de clés est sauvegardé.
3. Épinglez la nouvelle image par empreinte.
4. Lancez `scripts/deploy <cloud> migrate`, idéalement avec l’ancien contrôleur
   arrêté.
5. Lancez `scripts/deploy <cloud> helm`. Attendez-vous à une courte
   interruption de la disponibilité et de la publication.
6. Vérifiez `/readyz`, lancez un petit pipeline et lisez ses journaux.

Les migrations vont **uniquement vers l’avant**. Le retour arrière pris en
charge consiste à redéployer l’empreinte d’image précédente, et il n’est sûr
que si les nouvelles migrations sont compatibles avec le binaire précédent. Il
n’y a ni retour arrière du schéma ni retour arrière automatique des données :
restaurez plutôt à partir d’une sauvegarde vérifiée.

## Sauvegarder et restaurer

Sauvegardez comme **un seul ensemble de reprise** :

- PostgreSQL, qui inclut la table des événements et les secrets chiffrés ;
- le Secret de clés (`kodema-keys`) et ce qui authentifie auprès du KMS ;
- le volume de journaux conservés et le volume JetStream.

Une sauvegarde de la base sans la clé ne permet pas de déchiffrer les secrets,
et la clé seule ne restaure rien. Les espaces de travail sont jetables et
exclus. Les dépôts Git et les registres appartiennent à leurs opérateurs ;
coordonnez leur conservation, car les commits et les empreintes cités par les
exécutions conservées doivent rester accessibles.

Les déploiements de référence configurent uniquement les sauvegardes planifiées
de la base de données managée. Les sauvegardes des volumes et des Secrets sont
à votre charge.

Restaurez dans cet ordre : migrez la cible, contrôlez la sauvegarde au
préalable, **isolez** les anciens contrôleurs, services et consommateurs,
restaurez, réconciliez les charges de travail et les effets externes à partir
de leurs identités stables, puis activez la distribution. Une exécution dont
l’espace de travail ne peut pas être récupéré échoue de façon visible ; un
opérateur peut lancer une nouvelle tentative.

| Objectif recommandé | Valeur |
| --- | --- |
| Point de reprise | 15 minutes ou moins |
| Temps de reprise | 4 heures ou moins |
| Fenêtre de récupération PostgreSQL | 30 jours |

Kodema ne les impose pas. La configuration de référence Scaleway sauvegarde
toutes les six heures, ce qui ne respecte pas l’objectif de 15 minutes, et
aucun service n’a été repris à partir d’une base restaurée sur un déploiement
cloud ; il n’existe donc aucun temps de reprise mesuré. Mesurez le vôtre avec
un exercice.

| Conservation par défaut | Durée |
| --- | --- |
| Journaux | 30 jours |
| Preuves ordinaires | 90 jours |
| Métadonnées d’audit | Un an |
| Reçus d’opération | Jusqu’à la suppression du projet |
| Contenu brut des modèles et des outils | Désactivé ; une activation autorisée commence à sept jours |

## Identifiants et rotation

| Identifiant | Durée de vie et rotation |
| --- | --- |
| Jetons d’exécution | Huit heures au plus, renouvelés par le contrôleur, révoqués avec l’exécution |
| Jetons de compte de service | Une expiration explicite ; `service.credential.rotate` en remplace un immédiatement |
| Clé de tenant | `tenant.rotate_key` invalide tous les jetons d’exécution et de service du tenant |
| PKI de l’installation | `scripts/bootstrap-secrets <cloud> --rotate-pki` remplace l’autorité de certification et les certificats feuilles ; redémarrez le broker et le contrôleur ensemble. Il n’y a pas de renouvellement automatique |
| Clé de l’installation (`kodema-keys`) | Créée une seule fois. La supprimer ou la régénérer rend illisibles tous les secrets stockés |

Sauvegardez le répertoire de travail PKI de `scripts/bootstrap-secrets` avec le
Secret de clés : la clé privée de l’autorité de certification n’existe que là.

## Limites connues de la 0.2.1

**Installation locale**

- `kodema up` nécessite Podman et refuse un moteur Docker. Il n’a fonctionné
  que sur Linux ; les binaires macOS sont construits et n’ont pas été exécutés.
- La connexion intégrée ne demande aucun mot de passe et ne répond qu’à sa
  propre machine.
- `kodactl run` affiche la sortie d’une charge de travail à la fin de
  l’exécution, pas pendant qu’elle tourne.
- L’installateur installe la 0.2.1 ou une version plus récente ; les versions
  antérieures n’ont pas d’archive `kodema`.

**Pipelines et Git**

- Une action qui déclare `secrets:` est refusée, car la liste d’autorisation
  des secrets des charges de travail n’est pas encore configurable.
- Les suppressions de références Git sont refusées, même là où `RW+` les
  autorise.

**Intégrations**

- Les abonnements NATS par des personnes et des navigateurs sont refusés ;
  lisez les événements et les journaux par HTTP ou MCP.
- Les types de service `webhook` et `email` ne délivrent rien vers
  l’extérieur ; la création de tâches à partir d’e-mails entrants fonctionne.
- Un `tools/list` MCP non authentifié répond 200 ; seuls les appels d’outils
  répondent 401.
- Le proxy de modèles des charges de travail transmet n’importe quel chemin
  d’un fournisseur configuré ; il n’a pas de liste d’autorisation de modèles ou
  de points d’accès.
- `kodema auth serve` ne limite pas le débit des tentatives de connexion ni des
  enregistrements de clients.

**Déploiement**

- Scaleway est le seul cloud à avoir fonctionné en conditions réelles. L’image
  `linux/arm64` est construite et n’a pas été exécutée.
- Les artefacts ne sont pas signés.

Le [journal des modifications](https://github.com/optimiware/kodema/blob/master/CHANGELOG.md)
conserve cette liste pour chaque version.
