Aller au contenu
KendorDocs

Référence de kendor.yaml

Pour les auteurs d’exercices ·

Toutes les clés acceptées par kendor.yaml, de runtime et services à routing, databases et sandbox, avec leurs types, leurs valeurs par défaut et les règles vérifiées à l’enregistrement.

kendor.yaml se trouve à la racine du projet d’un exercice et indique au bac à sable ce qu’il doit exécuter : un langage et sa version, éventuellement d’autres langages et des bases de données, et un ou plusieurs services avec leurs commandes d’installation, de dev et de test. Seules version, runtime et services sont obligatoires. Kendor vérifie tout le fichier à l’enregistrement, et un fichier comportant des erreurs n’est pas enregistré.

Où se trouve le fichier et quand il s’applique

Le fichier est kendor.yaml, à la racine de l’espace de travail. Dans un zip importé ou un dépôt importé, Kendor accepte aussi l’orthographe kendor.yml.

Dans l’éditeur d’exercice, ouvrez Paramètres et choisissez Configurer l’exécution…. La boîte de dialogue Configuration d’exécution comporte un onglet Formulaire et un onglet YAML brut ; l’enregistrement écrit kendor.yaml et redémarre l’aperçu. Si vous modifiez plutôt le fichier à la main, une bannière kendor.yaml modifié apparaît, car le bac à sable exécute toujours la configuration précédente tant que vous ne choisissez pas Enregistrer et redémarrer.

À l’enregistrement, Kendor exécute les vérifications listées sous Règles de validation et contrôle aussi que chaque version de langage et de base de données fait partie de celles que Kendor propose. Chaque problème est signalé avec son chemin dans le fichier, par exemple services.web.dev.port.

La copie de kendor.yaml à l’intérieur d’un bac à sable en cours d’exécution est régénérée à partir de la configuration enregistrée à chaque démarrage du bac à sable : elle montre donc toujours ce que le bac à sable exécute.

Astuce. Commencez le fichier par # yaml-language-server: $schema=https://kendor.dev/config-schema/v1. Les éditeurs qui utilisent le serveur de langage YAML proposent alors l’autocomplétion et des erreurs en ligne pour chaque clé de cette page.

Ce que les candidats peuvent modifier

Un candidat peut modifier kendor.yaml dans son propre espace de travail. Seules quatre clés de premier niveau sont lues dans sa copie : install, services, preview et routing. Ses modifications s’appliquent au redémarrage du bac à sable, et seulement si le fichier fusionné passe toujours la validation ; sinon, votre configuration reste en place. runtime, toolchains, databases, sandbox et kendor proviennent toujours de votre fichier, tout comme les commandes de test : tout test écrit par un candidat est ignoré, et vos commandes test sont conservées sur les services que vous avez définis.

Un exemple complet

Une API Node.js et un frontend Vite, avec PostgreSQL et Valkey, plus un worker Python :

kendor.yaml
# yaml-language-server: $schema=https://kendor.dev/config-schema/v1
version: 1
runtime:
  type: node
  version: "22"
  packageManager: npm
toolchains:
  - type: python
    version: "3.12"
databases:
  - type: postgres
    version: "18"
    name: shop
    init: db/init
  - type: valkey
    version: "9"
services:
  api:
    workDir: api
    install:
      commands:
        - npm ci
    dev:
      command: node --watch src/server.js
      port: 3000
      env:
        vars:
          WEB_URL: routing.web.url
          CACHE_URL: databases.valkey.url
          LOG_LEVEL: lit:debug
    test:
      command: node --test
  web:
    workDir: web
    install:
      commands:
        - npm ci
    dev:
      command: npm run dev -- --port $PORT
      port: 5173
      env:
        vars:
          VITE_API_URL: routing.api.url
    publicEnvPrefix: VITE_
  worker:
    workDir: worker
    install:
      commands:
        - pip install --user -r requirements.txt
    dev:
      command: python worker.py
preview:
  service: web
routing:
  - path: /api
    service: api
  - path: /
    service: web
requests:
  - name: List products
    url: http://localhost:3000/api/products
  - name: Create a product
    method: POST
    url: http://localhost:3000/api/products
    headers:
      Content-Type: application/json
    body: '{"name": "Mug", "price": 12}'
kendor:
  gradeService: api

Clés de premier niveau

Les clés inconnues sont rejetées partout dans le fichier, sauf à l’intérieur de kendor.

Clé Type Obligatoire Description
version nombre Oui Le format du fichier. Doit valoir 1.
runtime mapping Oui Le langage principal et sa version.
toolchains liste Non Langages supplémentaires dans le même bac à sable.
databases liste Non Serveurs PostgreSQL, MySQL, MongoDB et Valkey dans le bac à sable.
install mapping Non Commandes exécutées une fois à la racine de l’espace de travail avant tout service.
services mapping Oui Les processus à installer, démarrer et tester, indexés par nom. Au moins un.
preview mapping Quand il y a 2 services ou plus Le service que le volet d’aperçu affiche.
routing liste Non Les préfixes de chemin de l’adresse d’aperçu et le service vers lequel va chacun.
sandbox mapping Non Docker ou Kubernetes dans le bac à sable.
requests liste Non Exemples de requêtes HTTP pour l’onglet Requêtes de l’éditeur.
kendor mapping Non Paramètres réservés aux auteurs.

Remarque. Écrivez les versions comme des chaînes entre guillemets : version: "3.12", et non version: 3.12. Sans guillemets, YAML lit 3.12 comme un nombre et le fichier échoue à la validation. Le version: 1 de premier niveau fait exception : il doit être le nombre 1.

runtime

Clé Type Obligatoire Par défaut Description
type chaîne Oui L’un de node, php, python, go, java, rust, cpp.
version chaîne Oui Une version que Kendor propose pour ce langage, comme "22" ou "1.27". Voir Langages et versions.
packageManager chaîne Non Non défini npm, pnpm, yarn ou bun. Enregistré à titre indicatif ; ce qui installe réellement, ce sont vos commandes install.

Le langage d’un exercice est fixé à sa création, mais pas sa version : quand runtime.type est le langage de l’exercice, runtime.version détermine la version qu’exécute le bac à sable.

toolchains

Une liste de langages supplémentaires, chacun avec son compilateur, ses outils et son serveur de langage dans le PATH à côté du principal. Utilisez-la pour un service Go à côté d’une application Node, ou Node pour les builds d’assets dans un projet PHP.

Clé Type Obligatoire Description
type chaîne Oui Les mêmes choix que runtime.type.
version chaîne Oui Une version que Kendor propose pour ce langage.

Chaque langage ne peut apparaître qu’une fois dans runtime et toolchains réunis.

databases

Une liste de serveurs de bases de données qui s’exécutent dans le bac à sable sur 127.0.0.1 et démarrent avant toute commande d’installation. Voir Bases de données dans le bac à sable pour les détails de connexion.

Clé Type Obligatoire Par défaut Description
type chaîne Oui postgres, mysql, mongodb ou valkey. Chaque type au plus une fois, et pas à la fois postgres et mysql.
version chaîne Oui "18" pour PostgreSQL, "8.4" pour MySQL, "8.0" pour MongoDB, "9" pour Valkey.
name chaîne Non app PostgreSQL, MySQL et MongoDB. La base à créer : lettres minuscules, chiffres, tirets bas et traits d’union, en commençant par une lettre ou un tiret bas, 63 caractères au plus, et différent de postgres, template0, template1, admin, local, config, mysql, information_schema, performance_schema ou sys.
user chaîne Non kendor PostgreSQL, MySQL et MongoDB. L’utilisateur avec lequel l’application se connecte, quand le projet attend le sien (postgres://shop:secret@localhost/shop). Lettres, chiffres, tirets bas et traits d’union, 32 au plus. Toutes les variables de connexion l’utilisent.
password chaîne Non Non défini (MongoDB : kendor) PostgreSQL, MySQL et MongoDB. Le mot de passe de cet utilisateur, une seule ligne de 128 caractères au plus. Kendor renseigne user, password et name à partir du .env.example ou du docker-compose d’un dépôt quand vous l’importez.
init chaîne Non Non défini PostgreSQL, MySQL et MongoDB. Un fichier de seed, ou un dossier dont les fichiers de seed s’exécutent dans l’ordre des noms, relatif à la racine de l’espace de travail : .sql pour PostgreSQL et MySQL, .js pour MongoDB. S’exécute une seule fois, après la création de la base.

install

Des commandes qui s’exécutent une fois à la racine de l’espace de travail, avant le démarrage de tout service. Utilisez-les pour une installation unique couvrant tout le dépôt, comme pnpm install dans un monorepo.

Clé Type Obligatoire Description
commands liste de chaînes Oui Au moins une. Elles s’exécutent dans l’ordre ; si l’une se termine avec un code non nul, les suivantes sont ignorées.

Les bases de données sont déjà en cours d’exécution quand ces commandes démarrent. Placez les migrations dans les commandes migrate d’un service plutôt qu’ici : les commandes d’installation sont ignorées lors d’un redémarrage quand aucun fichier de dépendances n’a changé, et les nouveaux fichiers de migration ne seraient donc pas appliqués.

services

Un mapping entre nom de service et service. Les noms commencent par une lettre minuscule et ne contiennent que des lettres minuscules, des chiffres et des traits d’union, par exemple api ou web-app. Le nom kendor-db est réservé. Chaque service s’exécute dans sa propre fenêtre de processus dans le bac à sable.

Clé Type Obligatoire Par défaut Description
workDir chaîne Non . Dossier dans lequel s’exécutent les commandes d’installation, dev et de test du service, relatif à la racine de l’espace de travail. Pas de / initial ni de ...
install mapping Non commands : une liste d’au moins une commande, exécutées dans l’ordre dans workDir après l’install de premier niveau. Si l’une échoue, la commande dev du service ne démarre pas.
migrate mapping Non commands : une liste d’au moins une commande qui met la base de données à jour, comme npx prisma migrate deploy ou php artisan migrate --force. Elles s’exécutent dans workDir à chaque démarrage du service, après son installation et avant dev, avec l’environnement du service. Si l’une échoue, l’erreur s’affiche dans le processus du service et dev démarre quand même.
dev mapping Non Le processus de longue durée. Voir plus bas.
test mapping Non command : la commande qu’exécute l’onglet Tests. timeout : durée maximale en secondes avant l’arrêt, de 10 à 1800 (par défaut : 10 minutes). Augmentez-la pour les grosses suites, par exemple une base de test longue à préparer.
publicEnvPrefix chaîne Non Le préfixe des variables qu’on peut exposer sans risque au code navigateur, comme VITE_. Accepté et stocké ; le bac à sable n’en tient pas compte.

Chaque service a besoin d’au moins un dev ou un test. Un service avec seulement test (et sans install) n’obtient pas de fenêtre de processus : c’est ainsi que sont configurés les exercices à fichier unique.

Quand un service redémarre, son installation est ignorée si les fichiers de dépendances de son workDir (package.json, fichiers de verrouillage, composer.json, requirements.txt, pyproject.toml, go.mod et similaires) n’ont pas changé.

dev

Clé Type Obligatoire Description
command chaîne Oui La commande qui démarre le service, par exemple npm run dev -- --port $PORT.
port entier Non De 1 à 65535. Le port sur lequel le service écoute. Deux services ne peuvent pas partager un port.
env.vars mapping Non Variables d’environnement de cette commande. Les noms correspondent à [A-Za-z_][A-Za-z0-9_]* ; les valeurs sont des références, décrites plus bas.

Kendor définit ces variables pour chaque commande dev, et elles l’emportent sur tout ce qui figure dans env.vars :

Variable Valeur
HOST 0.0.0.0
PORT Le port du service, quand il en a un.
KENDOR_PUBLIC_HOST Le nom d’hôte d’aperçu public du bac à sable.
KENDOR_VITE_ORIGIN L’origine publique du service : l’adresse d’aperçu pour le service d’aperçu, ou l’adresse du port propre du service pour tout autre service doté d’un port. Lue par le plugin @kendordev/vite.

Liez votre serveur à $HOST et $PORT (ou à 0.0.0.0 et au port déclaré) pour que l’aperçu puisse l’atteindre. Le code navigateur qui appelle http://localhost:<port> est envoyé vers ce port dans le bac à sable ; voir localhost dans l’aperçu.

Références de variables d’environnement

Une valeur dans env.vars doit utiliser l’une des quatre formes. Toute autre échoue à la validation.

Forme Exemple Se résout en
routing.<service>.url routing.api.url L’URL publique de ce service : l’adresse d’aperçu suivie du plus long chemin routing du service. L’adresse d’aperçu seule quand le chemin du service est / ou qu’il n’a pas de route. Le service doit exister.
databases.<type>.url databases.postgres.url L’URL de connexion d’une base de données déclarée sous databases.
vars.<NAME> vars.sessionId Une valeur fournie par Kendor : assessmentId, challengeId ou sessionId. Les autres noms échouent à la validation.
lit:<text> lit:debug Le texte après lit:, tel quel.

Les bases de données définissent aussi leurs propres variables, comme DATABASE_URL et REDIS_URL, pour chaque processus du bac à sable. Vous n’avez besoin de databases.<type>.url que lorsque votre code lit un autre nom.

preview

Clé Type Obligatoire Description
service chaîne Oui, quand preview est présent Le service dont le serveur de dev est affiché par le volet d’aperçu. Il doit exister.

preview est obligatoire quand il y a plus d’un service. Avec un seul service, c’est lui l’aperçu. Un projet dont les services n’ont pas de commande dev n’a pas d’aperçu, seulement un terminal.

routing

Une liste de routes sur l’adresse d’aperçu du bac à sable. Chaque requête va vers la route dont le préfixe de chemin correspond le plus long. Le chemin complet est transmis : un service routé sur /api reçoit donc /api/products, et non /products.

Clé Type Obligatoire Description
path chaîne Oui Commence par /. Ajoutez une route / comme route par défaut.
service chaîne Oui Un service existant. Les routes vers un service sans dev.port sont ignorées.

Quand des routes sont déclarées, l’aperçu affiche une courte page d’attente jusqu’à ce que chaque service routé accepte des connexions. Voir Applications à plusieurs services.

sandbox

Permet au bac à sable d’exécuter ses propres outils de conteneurs.

Clé Type Par défaut Description
containers booléen false Un démon Docker dans le bac à sable, avec docker, docker compose et buildx.
kubernetes booléen false Un cluster k3s à nœud unique démarré au boot, avec kubectl et helm. Active aussi containers.

L’une ou l’autre donne au bac à sable davantage de mémoire et de CPU. L’aperçu peut ouvrir les ports publiés par docker run -p ou Compose, et par kubectl port-forward avec --address 0.0.0.0. Une configuration avec containers ou kubernetes ne peut définir aucune commande test : il n’y a donc rien à lancer depuis l’onglet Tests ; réservez-la aux exercices que vous évaluez en lisant le travail. La page des tarifs liste les environnements de conteneurs dans l’offre Enterprise.

kendor.yaml
version: 1
runtime:
  type: node
  version: "22"
sandbox:
  containers: true
services:
  app:
    install:
      commands:
        - npm ci
    dev:
      command: docker compose up

requests

Des exemples de requêtes HTTP qui apparaissent, prêts à être envoyés, dans l’onglet Requêtes de l’éditeur. Les requêtes sont envoyées depuis l’intérieur du bac à sable : localhost fonctionne donc comme avec curl dans le terminal. Elles ne changent jamais la façon dont le bac à sable démarre.

Clé Type Obligatoire Par défaut Description
name chaîne Oui Le libellé affiché dans la liste.
method chaîne Non GET GET, POST, PUT, PATCH, DELETE, HEAD ou OPTIONS.
url chaîne Oui Une URL complète comme http://localhost:3000/api/todos, ou un chemin comme /api/todos, qui est envoyé au port du service d’aperçu.
headers mapping Non Nom d’en-tête vers valeur.
body chaîne Non Le corps de la requête.

Un exemple comportant une erreur est exclu de l’onglet ; les autres s’affichent quand même.

kendor

Paramètres réservés aux auteurs. Un candidat ne peut pas les modifier. Ce bloc accepte des clés supplémentaires sans erreur.

Clé Type Description
gradeService chaîne Le service dont l’onglet Tests exécute la test.command. Par défaut, le service d’aperçu. Doit désigner un service existant.
gradeServices liste de chaînes Plusieurs services dont l’onglet Tests exécute les commandes de test, chacune dans son propre workDir. Les résultats sont listés sous la forme service › test. Chaque service nommé doit exister et avoir un test. Utilisez soit cette clé, soit gradeService, pas les deux.

Le bloc contient aussi des clés que le catalogue de modèles de Kendor utilise pour décrire ses modèles : title, entryFile, order, type, difficulty, category, tags, editablePaths, readonlyPaths et solutionDir. Elles n’ont aucun effet sur votre exercice : définissez plutôt les chemins en lecture seule dans les Paramètres de l’éditeur d’épreuve (voir Comment les candidats lancent les tests).

Règles de validation

Un fichier n’est enregistré que si toutes ces conditions sont réunies :

  • version vaut 1, et runtime ainsi qu’au moins un service sont présents.
  • Aucune clé inconnue en dehors de kendor.
  • Les noms de services correspondent à ^[a-z][a-z0-9-]*$ et aucun n’est kendor-db.
  • Chaque service a un dev ou un test.
  • workDir et databases[].init sont des chemins relatifs à l’intérieur de l’espace de travail : pas de / initial, pas de lettre de lecteur, pas de ...
  • Deux services n’utilisent pas le même dev.port.
  • preview.service désigne un service existant, et preview est présent quand il y a deux services ou plus.
  • Chaque routing[].service désigne un service existant, et chaque path commence par /.
  • Chaque valeur d’env.vars utilise l’une des quatre formes de référence ; routing.<service>.url désigne un service existant, databases.<type>.url désigne une base de données déclarée, et vars.<NAME> vaut assessmentId, challengeId ou sessionId.
  • Chaque langage apparaît une fois dans runtime et toolchains réunis, et chaque type de base de données une fois.
  • Au plus une base de données SQL : postgres ou mysql, pas les deux.
  • name, user, password et init n’apparaissent que sur une base de données postgres, mysql ou mongodb, et name respecte la règle de nommage ci-dessus.
  • kendor.gradeService et chaque entrée de kendor.gradeServices désignent des services existants, les entrées de gradeServices ont un test, et les deux clés ne sont pas utilisées ensemble.
  • Avec sandbox.containers ou sandbox.kubernetes, aucun service n’a de test et ni gradeService ni gradeServices n’est défini.
  • Chaque version de langage et de base de données fait partie de celles que Kendor propose. Les versions qui ne sont plus proposées pour les nouveaux exercices passent quand même : un exercice qui en utilise une continue donc de s’enregistrer.
Cet article vous a-t-il aidé ?