--- title: "Exploiter Kodama : identité, configuration et reprise" description: "Initialiser un tenant Kodama, gérer configuration Helm et identifiants, diagnostiquer les charges, mettre à niveau et restaurer code, preuves et état cohérents." canonical_url: https://optimi.com/fr/docs/kodama/exploitation md_url: https://optimi.com/fr/docs/kodama/exploitation.md last_updated: 2026-10-23 --- # Exploitation Exploitez Kodama comme un plan de contrôle avec des backends durables et une exécution Kubernetes limitée à son périmètre. Commencez par [le parcours Helm](/fr/docs/kodama/premiers-pas) pour l’installation ; cette page couvre l’administration initiale et le cycle d’exploitation. ## Initialiser le premier tenant Le bootstrap crée le tenant et son premier administrateur avec un sujet OIDC explicitement désigné. Il utilise l’identifiant propriétaire de la base dans un Job administratif ponctuel, distinct du serveur. Exécutez-le après la migration Helm. Installez et configurez le CLI comme indiqué dans les premiers pas. Obtenez par OAuth un **jeton d’accès** administrateur de courte durée pour l’audience de l’usine. Pour cette opération ponctuelle, un stockage CLI isolé sur fichiers permet d’écrire le jeton dans `admin.token` sans l’afficher : ```sh umask 077 mkdir -m 700 bootstrap-login export KODAMA_CREDENTIAL_DIR="$PWD/bootstrap-login" kodama auth login --credential-store file jq -jr '.accessToken' "$KODAMA_CREDENTIAL_DIR"/*.json > admin.token export TOKEN="$(cat admin.token)" ``` Utilisez un répertoire `bootstrap-login` vide et le contexte de votre issuer. Le stockage fichier est explicite ; `kodama auth login` ordinaire continue d’utiliser le trousseau du système. Le `sub` exact émis pour cette personne constitue le `--eligible-subject` ci-dessous. N’utilisez pas son email sauf s’il s’agit réellement du sujet de l’issuer. Créez un Secret administratif temporaire contenant connexion propriétaire, bundle d’autorités et jeton : ```sh kubectl -n kodama-system create secret generic kodama-bootstrap \ --from-file=database-migration-url=migration-secrets/database-migration-url \ --from-file=ca.crt=migration-secrets/ca.crt \ --from-file=admin.token=admin.token ``` Enregistrez `bootstrap.yaml` ; remplacez empreinte d’image, issuer, audience et sujet : ```yaml apiVersion: batch/v1 kind: Job metadata: name: kodama-bootstrap namespace: kodama-system spec: backoffLimit: 0 activeDeadlineSeconds: 300 template: spec: restartPolicy: Never automountServiceAccountToken: false securityContext: runAsNonRoot: true runAsUser: 65532 runAsGroup: 65532 fsGroup: 65532 seccompProfile: {type: RuntimeDefault} containers: - name: bootstrap image: ghcr.io/optimiware/kodama@sha256:1111111111111111111111111111111111111111111111111111111111111111 args: - bootstrap - --tenant-id=t_acme - --tenant-key=acme - --display-name=Acme - --operator-id=op_initial - --eligible-subject=remplacer-par-sujet-verifie - --token-file=/secrets/admin.token env: - {name: KODAMA_ENV, value: production} - {name: KODAMA_OIDC_ISSUER, value: "https://identity.example.com"} - {name: KODAMA_OIDC_AUDIENCE, value: "https://kodama.example.com/api"} securityContext: allowPrivilegeEscalation: false readOnlyRootFilesystem: true capabilities: {drop: [ALL]} volumeMounts: - {name: secrets, mountPath: /secrets, readOnly: true} volumes: - name: secrets secret: secretName: kodama-bootstrap defaultMode: 0440 ``` ```sh kubectl apply -f bootstrap.yaml kubectl -n kodama-system wait job/kodama-bootstrap \ --for=condition=Complete --timeout=300s kubectl -n kodama-system logs job/kodama-bootstrap ``` Une requête identique retrouve le résultat enregistré ; changer ses paramètres provoque un conflit. Après succès, retirez le Job et le Secret temporaires. Conservez le jeton uniquement pendant la création du projet et des rôles décrite dans les premiers pas, puis supprimez les identifiants locaux temporaires : ```sh kubectl -n kodama-system delete job kodama-bootstrap kubectl -n kodama-system delete secret kodama-bootstrap kodama auth logout --credential-store file rm admin.token rmdir bootstrap-login unset TOKEN KODAMA_CREDENTIAL_DIR ``` La déconnexion supprime un identifiant local sans révoquer le jeton chez l’issuer. Les utilisateurs suivants se connectent et reçoivent des appartenances tenant/projet explicites. ## Configuration d’installation Coordonnez les versions du chart, du CLI et du serveur. Figez les images serveur et injecteur par empreinte. Les [valeurs du chart](https://github.com/optimiware/kodama/blob/main/deploy/helm/kodama/values.yaml) décrivent toute la configuration ; les principales relations sont : | Valeurs Helm | Responsabilité opérationnelle | | --- | --- | | `installation.id` | Identité stable du contexte de chiffrement, conservée après redémarrage et restauration | | `authority.mode` | Sélection explicite de l’autorité autonome ou d’une intégration hébergée supportée par la release | | `secrets.runtime.existingSecret` | Connexion serveur, identifiants broker/objets/Git, clés de curseur/idempotence et signature runtime | | `secrets.migration.existingSecret`, `migration.runtimeRole` | Connexion propriétaire des migrations et rôle runtime non propriétaire à autoriser | | `config.nats`, `config.s3`, `config.oidc` | Endpoints des backends, préfixe objets, issuer et audience | | `kms` et `serviceAccounts.server.annotations` | Un fournisseur de clés cloud et l’identité autorisée | | `execution.tenants` | Correspondance entre tenants et namespaces | | `execution.runtime` | Origine HTTPS accessible aux charges, génération de signature et destinations permises | | `execution.network`, `quota`, `limitRange`, `job`, `volumes` | Sorties réseau, concurrence, ressources et stockage temporaire bornés | | `ingress` | Endpoint TLS public et Secret de certificat existant | Le chart sélectionne la composition cœur et `KODAMA_ENV=production`. `KODAMA_CONFIG_FILE` pointe vers ses paramètres. Les variables d’environnement sont prioritaires ; les valeurs secrètes restent dans des fichiers distincts. Champs inconnus et choix de fournisseurs non supportés font échouer la configuration. Le profil initial utilise une réplique serveur et un déploiement `Recreate`. Dimensionnez séparément PostgreSQL, événements, rétention des objets et quotas des charges ; augmenter la concurrence tenant n’augmente pas automatiquement la capacité des backends. ## Identifiants et confiance Le serveur ne doit jamais détenir l’identifiant propriétaire de migration en fonctionnement normal. Son rôle PostgreSQL ne doit ni posséder les tables applicatives, ni être superutilisateur, ni avoir `BYPASSRLS`. Prédicats tenant et RLS s’ajoutent à l’autorisation applicative. Maintenez des identifiants distincts : - **Lecture et publication Git :** références limitées par préfixe d’URL et tenant dans `git-credentials.json`, sélectionnées par le dépôt du projet. - **Stockage objets :** clés limitées au bucket/préfixe, avec un mode de gestion supporté par votre release. - **Signature runtime :** clé PEM P-256 et génération explicite ; ne réutilisez jamais une génération pour une autre clé. - **Curseurs et idempotence :** valeurs brutes d’au moins 32 octets ; conservez les octets sans nettoyage ni réencodage. - **Livraison :** identifiants d’environnement limités au namespace cible et aux actions prévues. - **Fournisseurs et outils :** identifiants conservés derrière passerelle modèle et proxy MCP. Utilisez issuer et audience exacts. Client public, rappel runtime et backends doivent chacun valider leur pair TLS. Un rappel accessible au poste de travail ne l’est pas nécessairement depuis un Job tenant. Synchronisez `runtime-ca.crt` avec la confiance du callback et renouvelez les certificats avant expiration. Pour tourner un secret, créez et validez une nouvelle version destinée aux admissions futures, puis révoquez l’ancienne selon la politique des runs actifs. Les versions figées et sauvegardes déterminent quelles clés d’enveloppe doivent rester disponibles. Modifier les octets d’un Secret ne prouve pas leur rechargement par chaque processus : appliquez la procédure de rechargement ou de redéploiement de la release. ## Activer agents, livraison et notifications La politique d’installation définit le plafond ; le projet choisit les ressources autorisées. Configurez les documents et leurs montages supportés par votre release : | Politique | Configuration | | --- | --- | | Modèles/outils (`model-tools.json`) | Origines approuvées, destinations MCP et triplets image/wrapper/harness qualifiés | | Actions runtime (`action-ceiling.json` ou politique Kubernetes) | Actions `model.invoke`, `tool.invoke`, `deployment.call`, bornées par le contexte figé | | Registre (`registry.json`) | Registres et dépôts OCI autorisés, vérification de provenance | | Livraison (`delivery-tools.json`) | Images et commandes apply/cleanup exactes dont le protocole de rejeu est qualifié | | Déclencheurs Git (`git-triggers.json`) | Notifications de push natives authentifiées et liaisons d’installation | | Boucle métier (`business-loop.json`) | Origine canonique des notifications, destinations et identité/configuration de correspondance QA | Utilisez le mécanisme de projection supporté : ajouter une clé arbitraire à un Secret ne la monte pas si le chart énumère les clés. L’absence d’approbation n’accorde aucun droit modèle, outil ou déploiement. Enregistrez paramètres modèle et serveurs MCP par API, puis un profil d’agent immuable. Créez les environnements et leurs identifiants limités avant les étapes qui les référencent. Consultez `kodama environment --help`, `kodama agent --help` et le contrat API pour les champs des requêtes. Pour les prévisualisations, configurez le pipeline `kodama-cleanup` du projet avec une entrée string `deployment_id` et la commande de nettoyage qualifiée. L’expiration planifie le nettoyage du déploiement enregistré sans supprimer les objets étrangers de la cible. Les adaptateurs de signaux métier restent des clients API authentifiés. Ils portent validation de signature entrante, association événement/travail et déduplication durable. Les notifications ChatOps contiennent des liens vers des ressources soumises à l’autorisation courante ; transférer un lien ne donne aucun droit et le lire ne décide pas une validation. ## Santé et observation quotidienne `/healthz` indique la vitalité ; `/readyz` vérifie base migrée, JetStream, S3, OIDC et workers. À l’arrêt, le serveur devient non prêt avant l’arrêt HTTP et des workers. Les charges existantes sont réconciliées par le processus suivant. ```sh kubectl -n kodama-system get deployment,pods,jobs kubectl -n kodama-system logs deployment/kodama --since=15m kubectl -n kodama-tenant-acme get jobs,pods curl --fail https://kodama.example.com/readyz kodama run get "$RUN_ID" --output json kodama run steps "$RUN_ID" --output json ``` Corrélez IDs tenant, projet, travail, workspace, run, étape, tentative et requête. Suivez âge de l’outbox, retard des consommateurs, tentatives en attente, publications, annulations, validations anciennes et nettoyage. Gardez les IDs à forte cardinalité dans des enregistrements/journaux protégés, pas dans des labels de métriques partagées sans limites. | Symptôme | Diagnostic et reprise | | --- | --- | | Échec du hook de migration | Connexion propriétaire, CA, rôle runtime, compatibilité du schéma et logs du Job | | Serveur non prêt | Erreur du backend/worker nommé ; distinguer configuration non supportée et panne de connexion | | Connexion CLI réussie, opération refusée | Audience et rôle courant du tenant/projet ; admin ne signifie pas ingénieur ou reviewer | | Job ne démarrant pas | Empreinte/accès image, politique du namespace, quotas, ressources et éléments d’admission | | Job actif, aucun résultat | URL de rappel accessible à la charge, TLS, sorties réseau et autorité de tentative | | Run restant en file | Dépendances, réservation d’écriture, limites et diagnostic du dispatcher | | `output_invalid` / `output_upload_failed` | Noms, types, chemins déclarés, fichiers produits et accès au stockage | | Conflit de publication | Examiner références Git attendue/proposée et pushes humains ; conserver la proposition | | Validation bloquée | Fraîcheur du sujet/preuves, révocation reviewer, annulation et décision enregistrée | | Effet externe inconnu | Observer l’identité stable d’action/déploiement avant répétition | | Journaux incomplets | Examiner origine et exhaustivité de capture séparément du résultat | | Notifications ayant épuisé leurs essais | Lire l’historique et rejouer explicitement avec l’autorité courante et les mêmes corps/clé | ## Mises à niveau et retour arrière 1. Consultez la compatibilité schéma, CLI, runtime et backends de la release. 2. Vérifiez un point de reprise cohérent et l’accès aux clés d’enveloppe nécessaires. 3. Suspendez nouvelles admissions et intégrations à effets externes si le mélange de versions n’est pas supporté ; réglez ou inventoriez les tentatives actives. 4. Exécutez `helm upgrade` avec le nouveau chart et l’empreinte d’image. Le hook de migration propriétaire précède le renouvellement du serveur. 5. Vérifiez readiness, authentification et pipeline borné ; récupérez rapport et journaux avant la reprise normale. Un retour à un ancien binaire exige un schéma compatible. `helm rollback` n’annule ni migrations, ni publications Git, ni déploiements externes. Restaurez et réconciliez si aucun retour compatible n’est possible. ## Sauvegarde et reprise Sauvegardez l’ensemble durable : PostgreSQL/WAL, références et objets Git, preuves S3, images, configuration et versions KMS nécessaires. La rétention doit couvrir les mêmes points de reprise. Les fichiers temporaires non commités n’appartiennent pas à cet ensemble. Utilisez **RPO 15 minutes**, **RTO 4 heures** et **PITR sur 30 jours** comme objectifs à valider par des exercices. La référence de rétention est 90 jours pour les preuves ordinaires, 30 jours pour les logs, un an pour l’audit et 24 heures de TTL par défaut pour les prévisualisations. Les références actives prolongent la conservation. Le contenu brut modèle/outil est désactivé par défaut ; son activation nécessite une politique bornée distincte. Ces objectifs ne sont pas des garanties fournies par une installation Helm. Lors d’une restauration : 1. Arrêtez admissions et consommateurs à effets externes ; neutralisez anciens contrôleurs et éditeurs, y compris leurs identifiants encore détenus. 2. Restaurez un ensemble cohérent base/code/objets/images et vérifiez le déchiffrement. 3. Renouvelez les clés runtime et invalidez les anciennes admissions ; traitez séparément opérations distantes et identifiants déjà livrés. 4. Identifiez les charges par tentative et UID d’instance. Réconciliez publications Git et déploiements avant une nouvelle écriture ou application. 5. Rejouez les événements avec déduplication inbox ; libérez les réservations seulement après résolution des effets incertains. 6. Reprenez un parcours borné et vérifiez historique et preuves restaurés. ## Départ d’un tenant et désinstallation Arrêtez les admissions, révoquez l’accès, réglez le travail actif et appliquez la rétention avant suppression. Distinguez audit conservé, preuves référencées, versions supportées et expiration des sauvegardes. Ne détruisez pas une clé KMS partagée tant que des données conservées en dépendent. `helm uninstall kodama -n kodama-system` retire le plan de contrôle tout en conservant namespaces tenants et protections d’exécution. Les Jobs runtime, bases externes, Git, S3, images, clés et déploiements exigent leurs propres procédures. Retirer un tenant des valeurs Helm préserve également son namespace, qui n’est pas traité comme du stockage jetable. Retour aux **[premiers pas](/fr/docs/kodama/premiers-pas)** ou aux **[exemples de pipelines](/fr/docs/kodama/guide-developpeur)**.