kantama.yaml
kantama.yaml vit à la racine du dépôt du projet. Il déclare ce que la console peut faire, et l'agent refuse tout ce qui n'y figure pas. Clés en anglais, valeurs libres.
Un exemple complet
kantama.yaml
# Exemple : ce que CAS-MARKET déclarerait pour la console. # Chaque action devient un formulaire dans l'espace du projet ; l'agent # refuse tout ce qui n'est pas listé ici (ou dans le socle « core. »). version: 1 project: name: cas-market label: CAS-MARKET environments: [production, preproduction] services: # compose : un fichier, ou plusieurs empilés dans l'ordre (« docker compose -f base -f prod »). - name: api_core kind: compose compose: [infra/docker-compose.yml, infra/docker-compose.prod.yml] health: http: https://api.casmarketgn.com/health expect: 200 - name: api_payment kind: compose compose: [infra/docker-compose.yml, infra/docker-compose.prod.yml] health: http: https://api.casmarketgn.com/payment/health expect: 200 actions: - id: payments.reconcile label: Relancer la vérification d'un paiement description: Interroge le prestataire et met à jour un paiement resté en attente. level: single params: - name: reference label: Référence du paiement type: string required: true pattern: "PAY-[0-9]{1,12}" run: service: api_payment command: [python, -m, app.ops.paiements, reconcile, --reference, "{reference}"] timeout: 2m - id: escrow.release label: Débloquer un séquestre description: Libère les fonds d'une livraison bloquée vers le vendeur. level: double irreversible: true environments: [production] params: - name: delivery_id label: Livraison type: int required: true min: 1 - name: amount label: Montant type: int required: true min: 1 # Montant inhabituel : au-delà, la case « J'ai vérifié ce montant » fait partie de l'ordre signé. unusual: {above: 5000000, times_average: 3, unit: GNF} - name: reason label: Motif type: string required: true max_length: 200 run: service: api_core command: [python, -m, app.ops.sequestres, release, --delivery, "{delivery_id}", --amount, "{amount}", --reason, "{reason}"] - id: withdrawals.reject label: Refuser un retrait level: single params: - name: withdrawal_id type: int required: true min: 1 - name: motive type: choice required: true choices: [numero_invalide, fraude_suspectee, doublon] run: service: api_payment command: [python, -m, app.ops.retraits, reject, "{withdrawal_id}", "{motive}"] # Lot J : une procédure, signée en un seul ordre ; l'agent exécute les étapes dans l'ordre et s'arrête à la # première en échec. Un paramètre écrit ici est fixé ; les autres se choisissent à la préparation. procedures: - id: rattrapage-paiements label: Rattrapage des paiements description: Redémarre le service de paiement, attend qu'il réponde, puis relance la vérification d'un paiement. environments: [production] steps: - action: core.service.restart params: {service: api_payment} - action: core.probe.check params: {service: api_payment, timeout: 120} - action: payments.reconcile # la référence est choisie à la préparation
Clés de premier niveau
| Clé | Requis | Rôle |
|---|---|---|
version | oui | Toujours 1. |
project.name | oui | Nom du projet : [a-z0-9][a-z0-9-]{1,62}. |
project.label | non | Libellé affiché. |
environments | oui | Au moins un environnement. |
services | non | Ce que l'agent pilote. |
actions | non | Vos actions métier. |
backups | non | Sauvegardes faites sur le serveur (Sauvegardes testées). |
jobs | non | Tâches planifiées que l'application signale (100 au plus). |
connectors | non | Plateformes lues par l'agent (20 au plus). |
procedures | non | Suites d'actions signées en un seul ordre, 50 au plus (Procédures). |
drift | non | Outil d'analyse des vulnérabilités déjà installé sur le serveur (Dérive). |
source | non | Le clone de travail d'un projet docker compose, déployé par un ordre signé (Déploiements). |
services
| Clé | Rôle |
|---|---|
name | [a-z][a-z0-9_-]{0,62}, requis. |
kind | compose : un service existant de votre docker-compose ; app : construit et déployé par l'agent. |
compose | Votre fichier docker-compose, ou la liste de vos fichiers (1 à 8, sans doublon) dans l'ordre où vous les empilez (docker compose -f base -f prod). Un chemin relatif part du dossier de kantama.yaml. L'agent passe chaque fichier, dans cet ordre, et prend le dossier du premier comme dossier du projet : il vise les mêmes conteneurs que vous à la main. Si un fichier manque, il ne lance rien. |
health.http, health.expect | Sonde de santé appelée depuis le serveur toutes les 30 s ; code attendu, 200 par défaut. |
health.docker | Service compose : l'état de santé Docker du conteneur sert de sonde (son healthcheck), pour une API que votre frontal n'expose pas ; unhealthy ou arrêté = échec. L'un ou l'autre, jamais avec health.http. |
build | Service compose : il se reconstruit au déploiement (Déploiements). Exige le bloc source ; tous les services build partagent les mêmes fichiers compose et env_file. |
deploy.repo, deploy.branch | Dépôt Git et branche : seuls les commits de cette branche sont déployables. |
deploy.port | Port du conteneur, requis. |
deploy.context, deploy.dockerfile | Dossier de build (.) et Dockerfile (Dockerfile). |
deploy.health | Chemin du contrôle de santé avant la bascule (/up par défaut). |
deploy.hosts, deploy.tls | Domaines par environnement ; certificat Let's Encrypt automatique. |
deploy.env_file | Chemin absolu d'un fichier de variables sur le serveur. |
deploy.previews | Prévisualisations par branche : environment, host (avec {branch}), max (3), ttl (72h). |
actions
| Clé | Rôle |
|---|---|
id | domaine.verbe, 64 caractères au plus ; core. est réservé. |
label | Libellé, requis. |
description | Texte libre. |
level | single (une passkey) ou double (deux passkeys distinctes), requis. |
environments | Où l'action est permise ; absent : partout. |
irreversible | Effet qui ne se défait pas, affiché à la relecture. |
signers | Nombre de membres distincts qui doivent signer, de 1 à 5 : un entier partout (signers: 2) ou par environnement (signers: {production: 2}). Vérifié par l'agent, en plus de level. |
run.service | Service où la commande s'exécute, requis. |
run.command | argv, jamais de shell. {nom} occupe un élément entier, et le paramètre doit être required. |
run.timeout | Durée Go (90s, 2m), 60 s par défaut, 30 min au plus. |
actions[].params
| Clé | Rôle |
|---|---|
name | [a-z][a-z0-9_]{0,31}, requis. |
type | string, int, bool ou choice, requis. |
label, required | Libellé du champ ; champ obligatoire. |
pattern | Expression régulière, ancrée automatiquement. |
min, max | Bornes d'un entier. |
max_length | Longueur maximale d'un texte (1 à 4 096). |
choices | Valeurs permises d'un choice. |
unusual | Garde « montant inhabituel » d'un entier : above (seuil), times_average (multiple de la moyenne des 30 derniers jours), unit. |
backups et jobs
| Clé | Rôle |
|---|---|
backups[].kind | postgres (pg_dump dans le service) ou files (path ou volume). |
backups[].every, at, keep | Fréquence (1m à 744h), heure UTC, nombre gardé sur le serveur (7 par défaut). |
backups[].test_every, check | Restauration d'essai planifiée ; requête témoin. |
jobs[].every ou cron | Période, ou 5 champs cron en UTC. |
jobs[].grace | Tolérance avant l'alerte (5m par défaut). |
connectors
| Clé | Rôle |
|---|---|
provider | vercel, cloudflare, supabase, eas ou github. |
token | Le nom de la variable qui porte le jeton, jamais sa valeur. |
env | Environnement où vit le jeton et où se signent les gestes. |
project, team, zones, app, repo, workflows | Ce que l'agent lit chez le fournisseur. |
costs | Source des coûts : api (Vercel), org:… ou user:… (GitHub) ; absent : saisis dans la console. |
procedures
| Clé | Rôle |
|---|---|
id | [a-z][a-z0-9_-]{0,47}, unique, requis. |
label | Libellé, requis (120 caractères au plus). |
description | Texte libre (500 caractères au plus). |
environments | Où la procédure est permise ; absent : partout. |
steps[].action | Une action de la liste fermée (déclarée ou du socle), de 1 à 10 étapes. Ni confiance, ni politique, ni état du projet, ni core.secrets.apply, ni action à unusual. |
steps[].params | Paramètres fixés ; ceux qui manquent se choisissent à la préparation. Mêmes règles que les paramètres de l'action. |
L'empreinte de chaque procédure s'affiche avec kantama agent manifeste kantama.yaml : c'est celle que l'ordre signé doit porter.
source
| Clé | Rôle |
|---|---|
path | Chemin absolu du clone de travail sur le serveur (/opt/cas-market), requis. |
branch | Seuls les commits de cette branche distante se déploient, requis ; le clone doit être dessus. |
remote | Dépôt distant (origin par défaut). |
env | Environnement où le déploiement se signe ; facultatif s'il n'y en a qu'un. |
after_deploy | Actions déclarées lancées après un déploiement sain, dans l'ordre (8 au plus) : sans paramètre, level: single, un seul membre, pas irreversible. |
fetch_every | Récupération périodique de la branche, pour proposer les derniers commits : 5m par défaut, de 1m à 24h. |
health_timeout | Attente maximale de l'état sain des services reconstruits : 5m par défaut, de 10s à 30m. |
drift
| Clé | Rôle |
|---|---|
scanner.tool | trivy ou grype, déjà installé sur le serveur, avec sa base de vulnérabilités. Requis si scanner est présent. |
scanner.path | Chemin absolu de l'exécutable ; absent : cherché dans le PATH. |
scanner.every | Intervalle entre deux analyses d'une même image, de 1h à 744h (24h par défaut). |
La surveillance de la dérive n'a besoin d'aucune clé : elle est toujours active. Ce bloc ne sert qu'à l'analyse des vulnérabilités, que l'agent fait hors ligne, sans jamais télécharger de base.
Cette page vous a-t-elle aidé ?Modifier cette page
Les propositions de modification de la documentation ne sont pas encore ouvertes au public.