Saltar al contenido
KendorDocs

Referencia de kendor.yaml

Para autores de retos ·

Todas las claves que acepta kendor.yaml, desde runtime y services hasta routing, databases y sandbox, con sus tipos, valores por defecto y las reglas que se comprueban al guardar.

kendor.yaml está en la raíz del proyecto de un reto e indica al sandbox qué ejecutar: un lenguaje y su versión, lenguajes y bases de datos adicionales opcionales, y uno o más servicios con sus comandos de instalación, desarrollo y tests. Solo version, runtime y services son obligatorios. Kendor comprueba todo el archivo al guardar, y un archivo con errores no se guarda.

Dónde está el archivo y cuándo se aplica

El archivo es kendor.yaml, en la raíz del workspace. En un zip subido o un repositorio importado, Kendor también acepta la grafía kendor.yml.

En el editor del reto, abre Configuración y elige Configurar runtime…. El cuadro de Configuración de runtime tiene una pestaña Formulario y otra YAML sin procesar; al guardar se escribe kendor.yaml y se reinicia la vista previa. Si en cambio editas el archivo a mano, aparece un aviso kendor.yaml ha cambiado, porque el sandbox sigue ejecutando la configuración anterior hasta que eliges Guardar y reiniciar.

Al guardar, Kendor ejecuta las comprobaciones indicadas en Reglas de validación y también comprueba que cada versión de lenguaje y de base de datos sea una de las que ofrece Kendor. Cada problema se informa con su ruta en el archivo, por ejemplo services.web.dev.port.

La copia de kendor.yaml dentro de un sandbox en marcha se regenera a partir de la configuración guardada cada vez que arranca el sandbox, así que siempre muestra lo que el sandbox está ejecutando.

Consejo. Empieza el archivo con # yaml-language-server: $schema=https://kendor.dev/config-schema/v1. Los editores que usan el servidor de lenguaje de YAML ofrecerán entonces autocompletado y errores en línea para todas las claves de esta página.

Qué pueden cambiar los candidatos

Un candidato puede editar kendor.yaml en su propio workspace. De su copia solo se leen cuatro claves de nivel superior: install, services, preview y routing. Sus cambios se aplican cuando se reinicia el sandbox, y solo si el archivo combinado sigue superando la validación; de lo contrario, tu configuración se mantiene. runtime, toolchains, databases, sandbox y kendor siempre proceden de tu archivo, y lo mismo ocurre con los comandos de tests: cualquier test que escriba un candidato se descarta, y tus comandos test se conservan en los servicios que definiste.

Un ejemplo completo

Una API de Node.js y un frontend de Vite, con PostgreSQL y Valkey, más un worker de 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

Claves de nivel superior

Las claves desconocidas se rechazan en todo el archivo, salvo dentro de kendor.

Clave Tipo Obligatoria Descripción
version número Sí El formato del archivo. Debe ser 1.
runtime mapa Sí El lenguaje principal y su versión.
toolchains lista No Lenguajes adicionales en el mismo sandbox.
databases lista No Servidores PostgreSQL, MySQL, MongoDB y Valkey dentro del sandbox.
install mapa No Comandos que se ejecutan una vez en la raíz del workspace antes de cualquier servicio.
services mapa Sí Los procesos que se instalan, inician y prueban, con su nombre como clave. Al menos uno.
preview mapa Cuando hay 2 o más servicios Qué servicio muestra el panel de vista previa.
routing lista No Prefijos de ruta de la dirección de la vista previa y el servicio al que va cada uno.
sandbox mapa No Docker o Kubernetes dentro del sandbox.
requests lista No Peticiones HTTP de ejemplo para la pestaña Peticiones del editor.
kendor mapa No Ajustes solo para autores.

Nota. Escribe las versiones como cadenas entre comillas: version: "3.12", no version: 3.12. Sin comillas, YAML lee 3.12 como un número y el archivo no supera la validación. El version: 1 de nivel superior es la excepción; debe ser el número 1.

runtime

Clave Tipo Obligatoria Por defecto Descripción
type cadena Sí Uno de node, php, python, go, java, rust, cpp.
version cadena Sí Una versión que Kendor ofrezca para ese lenguaje, como "22" o "1.27". Consulta Lenguajes y versiones.
packageManager cadena No Sin definir npm, pnpm, yarn o bun. Se guarda como referencia; lo que realmente instala son tus comandos install.

El lenguaje de un reto se fija al crearlo, pero su versión no: cuando runtime.type es el lenguaje del reto, runtime.version decide qué versión ejecuta el sandbox.

toolchains

Una lista de lenguajes adicionales, cada uno con su compilador, sus herramientas y su servidor de lenguaje en el PATH junto al principal. Úsala para un servicio en Go junto a una aplicación de Node, o para Node en las compilaciones de recursos de un proyecto PHP.

Clave Tipo Obligatoria Descripción
type cadena Sí Las mismas opciones que runtime.type.
version cadena Sí Una versión que Kendor ofrezca para ese lenguaje.

Cada lenguaje puede aparecer una sola vez entre runtime y toolchains.

databases

Una lista de servidores de bases de datos que se ejecutan dentro del sandbox en 127.0.0.1 y arrancan antes de cualquier comando de instalación. Consulta Bases de datos en el sandbox para ver los datos de conexión.

Clave Tipo Obligatoria Por defecto Descripción
type cadena Sí postgres, mysql, mongodb o valkey. Cada tipo como máximo una vez, y no postgres y mysql a la vez.
version cadena Sí "18" para PostgreSQL, "8.4" para MySQL, "8.0" para MongoDB, "9" para Valkey.
name cadena No app PostgreSQL, MySQL y MongoDB. La base de datos que se crea: letras minúsculas, dígitos, guiones bajos y guiones, empezando por una letra o un guion bajo, con un máximo de 63 caracteres, y distinta de postgres, template0, template1, admin, local, config, mysql, information_schema, performance_schema y sys.
user cadena No kendor PostgreSQL, MySQL y MongoDB. El usuario con el que se conecta la aplicación, cuando el proyecto espera uno propio (postgres://shop:secret@localhost/shop). Letras, dígitos, guiones bajos y guiones, con un máximo de 32. Todas las variables de conexión lo usan.
password cadena No Sin definir (MongoDB: kendor) PostgreSQL, MySQL y MongoDB. La contraseña de ese usuario, una línea de 128 caracteres como máximo. Kendor rellena user, password y name a partir del .env.example o del docker-compose de un repositorio cuando lo importas.
init cadena No Sin definir PostgreSQL, MySQL y MongoDB. Un archivo de seed, o una carpeta cuyos archivos de seed se ejecutan por orden de nombre, relativa a la raíz del workspace: .sql para PostgreSQL y MySQL, .js para MongoDB. Se ejecuta una vez, después de crear la base de datos.

install

Comandos que se ejecutan una vez en la raíz del workspace, antes de que arranque cualquier servicio. Úsalo para una única instalación que cubra todo el repositorio, como pnpm install en un monorepo.

Clave Tipo Obligatoria Descripción
commands lista de cadenas Sí Al menos una. Se ejecutan en orden; si una termina con un código distinto de cero, se omiten las siguientes.

Las bases de datos ya están en marcha cuando empiezan estos comandos. Pon las migraciones en los comandos migrate de un servicio y no aquí: los comandos de instalación se omiten en un reinicio cuando no ha cambiado ningún archivo de dependencias, así que los archivos de migración nuevos no se aplicarían.

services

Un mapa de nombre de servicio a servicio. Los nombres empiezan por una letra minúscula y contienen solo letras minúsculas, dígitos y guiones, por ejemplo api o web-app. El nombre kendor-db está reservado. Cada servicio se ejecuta en su propia ventana de proceso dentro del sandbox.

Clave Tipo Obligatoria Por defecto Descripción
workDir cadena No . Carpeta en la que se ejecutan los comandos de instalación, desarrollo y tests del servicio, relativa a la raíz del workspace. Sin / inicial y sin ...
install mapa No commands: una lista de al menos un comando, que se ejecutan en orden en workDir después del install de nivel superior. Si uno falla, el comando dev del servicio no arranca.
migrate mapa No commands: una lista de al menos un comando que pone la base de datos al día, como npx prisma migrate deploy o php artisan migrate --force. Se ejecutan en workDir cada vez que arranca el servicio, después de su instalación y antes de dev, con el entorno del servicio. Si uno falla, el error aparece en el proceso del servicio y dev arranca igualmente.
dev mapa No El proceso de larga duración. Consulta más abajo.
test mapa No command: el comando que ejecuta la pestaña Tests. timeout: segundos que puede tardar antes de detenerse, de 10 a 1800 (por defecto, 10 minutos). Súbelo para suites grandes, como una base de datos de pruebas que tarda en prepararse.
publicEnvPrefix cadena No El prefijo de las variables que pueden exponerse con seguridad al código del navegador, como VITE_. Se acepta y se guarda; el sandbox no actúa en consecuencia.

Cada servicio necesita al menos un dev o un test. Un servicio con solo test (y sin install) no tiene ventana de proceso: así se configuran los retos de archivo único.

Cuando un servicio se reinicia, se omite su instalación si los archivos de dependencias de su workDir (package.json, lockfiles, composer.json, requirements.txt, pyproject.toml, go.mod y similares) no han cambiado.

dev

Clave Tipo Obligatoria Descripción
command cadena Sí El comando que inicia el servicio, por ejemplo npm run dev -- --port $PORT.
port entero No De 1 a 65535. El puerto en el que escucha el servicio. Dos servicios no pueden compartir puerto.
env.vars mapa No Variables de entorno para este comando. Los nombres cumplen [A-Za-z_][A-Za-z0-9_]*; los valores son referencias, descritas más abajo.

Kendor define estas variables para todos los comandos de desarrollo, y tienen prioridad sobre cualquier cosa de env.vars:

Variable Valor
HOST 0.0.0.0
PORT El port del servicio, cuando lo tiene.
KENDOR_PUBLIC_HOST El nombre de host público de la vista previa del sandbox.
KENDOR_VITE_ORIGIN El origen público del servicio: la dirección de la vista previa para el servicio de la vista previa, o la dirección del puerto del propio servicio para cualquier otro servicio con puerto. Lo lee el plugin @kendordev/vite.

Enlaza tu servidor a $HOST y $PORT (o a 0.0.0.0 y al puerto declarado) para que la vista previa pueda alcanzarlo. El código del navegador que llama a http://localhost:<port> se envía a ese puerto del sandbox; consulta localhost en la vista previa.

Referencias de variables de entorno

Un valor de env.vars debe usar una de cuatro formas. Cualquier otra falla la validación.

Forma Ejemplo Se resuelve en
routing.<service>.url routing.api.url La URL pública de ese servicio: la dirección de la vista previa más la ruta de routing más larga del servicio. Solo la dirección de la vista previa cuando la ruta del servicio es / o no tiene ruta. El servicio debe existir.
databases.<type>.url databases.postgres.url La URL de conexión de una base de datos declarada en databases.
vars.<NAME> vars.sessionId Un valor que proporciona Kendor: assessmentId, challengeId o sessionId. Otros nombres fallan la validación.
lit:<text> lit:debug El texto que sigue a lit:, tal cual.

Las bases de datos también definen sus propias variables, como DATABASE_URL y REDIS_URL, para todos los procesos del sandbox. Solo necesitas databases.<type>.url cuando tu código lee otro nombre.

preview

Clave Tipo Obligatoria Descripción
service cadena Sí, cuando preview está presente El servicio cuyo servidor de desarrollo muestra el panel de vista previa. Debe existir.

preview es obligatorio cuando hay más de un servicio. Con un solo servicio, ese servicio es la vista previa. Un proyecto cuyos servicios no tienen comando dev no tiene vista previa, solo una terminal.

routing

Una lista de rutas de la dirección de la vista previa del sandbox. Cada petición va a la ruta con el prefijo de ruta coincidente más largo. La ruta completa se reenvía, así que un servicio enrutado en /api recibe /api/products, no /products.

Clave Tipo Obligatoria Descripción
path cadena Sí Empieza por /. Añade una ruta / como comodín.
service cadena Sí Un servicio existente. Las rutas a un servicio sin dev.port se omiten.

Con rutas declaradas, la vista previa muestra una breve página de espera hasta que todos los servicios enrutados acepten conexiones. Consulta Aplicaciones con varios servicios.

sandbox

Permite que el sandbox ejecute sus propias herramientas de contenedores.

Clave Tipo Por defecto Descripción
containers booleano false Un demonio de Docker dentro del sandbox, con docker, docker compose y buildx.
kubernetes booleano false Un clúster k3s de un solo nodo que se inicia en el arranque, con kubectl y helm. También activa containers.

Cualquiera de los dos da más memoria y CPU al sandbox. La vista previa puede abrir los puertos publicados con docker run -p o Compose, y kubectl port-forward con --address 0.0.0.0. Una configuración con containers o kubernetes no puede definir ningún comando test, así que no hay nada que ejecutar desde la pestaña Tests; úsala para retos que revisas leyendo el trabajo. La página de precios incluye los entornos con contenedores en el plan 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

Peticiones HTTP de ejemplo que aparecen, listas para enviar, en la pestaña Peticiones del editor. Las peticiones se envían desde dentro del sandbox, así que localhost funciona igual que con curl en la terminal. Nunca cambian la forma en que arranca el sandbox.

Clave Tipo Obligatoria Por defecto Descripción
name cadena Sí La etiqueta que se muestra en la lista.
method cadena No GET GET, POST, PUT, PATCH, DELETE, HEAD u OPTIONS.
url cadena Sí Una URL completa como http://localhost:3000/api/todos, o una ruta como /api/todos, que se envía al puerto del servicio de la vista previa.
headers mapa No Nombre de cabecera a valor.
body cadena No El cuerpo de la petición.

Un ejemplo con un error se deja fuera de la pestaña; los demás siguen mostrándose.

kendor

Ajustes solo para autores. Un candidato no puede cambiarlos. El bloque acepta claves adicionales sin error.

Clave Tipo Descripción
gradeService cadena El servicio cuyo test.command ejecuta la pestaña Tests. Por defecto, el servicio de la vista previa. Debe nombrar un servicio existente.
gradeServices lista de cadenas Varios servicios cuyos comandos de tests ejecuta la pestaña Tests, cada uno en su propio workDir. Los resultados se muestran como service › test. Todos los servicios nombrados deben existir y tener un test. Usa esta clave o gradeService, no ambas.

El bloque también contiene claves que el catálogo de plantillas de Kendor usa para describir sus plantillas: title, entryFile, order, type, difficulty, category, tags, editablePaths, readonlyPaths y solutionDir. No tienen ningún efecto en tu reto: define las rutas de solo lectura en Configuración del editor de pruebas (consulta Cómo ejecutan los tests los candidatos).

Reglas de validación

Un archivo se guarda solo cuando se cumple todo lo siguiente:

  • version es 1, y están presentes runtime y al menos un servicio.
  • No hay claves desconocidas fuera de kendor.
  • Los nombres de servicio cumplen ^[a-z][a-z0-9-]*$ y ninguno es kendor-db.
  • Cada servicio tiene un dev o un test.
  • workDir y databases[].init son rutas relativas dentro del workspace: sin / inicial, sin letra de unidad y sin ...
  • Dos servicios no usan el mismo dev.port.
  • preview.service nombra un servicio existente, y preview está presente cuando hay dos o más servicios.
  • Cada routing[].service nombra un servicio existente, y cada path empieza por /.
  • Cada valor de env.vars usa una de las cuatro formas de referencia; routing.<service>.url nombra un servicio existente, databases.<type>.url nombra una base de datos declarada y vars.<NAME> es assessmentId, challengeId o sessionId.
  • Cada lenguaje aparece una vez entre runtime y toolchains, y cada tipo de base de datos una vez.
  • Como máximo una base de datos SQL: postgres o mysql, no ambas.
  • name, user, password e init aparecen solo en una base de datos postgres, mysql o mongodb, y name sigue la regla de nomenclatura anterior.
  • kendor.gradeService y cada entrada de kendor.gradeServices nombran servicios existentes, las entradas de gradeServices tienen un test, y las dos claves no se usan a la vez.
  • Con sandbox.containers o sandbox.kubernetes, ningún servicio tiene un test y no se define ni gradeService ni gradeServices.
  • Cada versión de lenguaje y de base de datos es una de las que ofrece Kendor. Las versiones que ya no se ofrecen para retos nuevos siguen pasando, de modo que un reto que usa una sigue guardándose.
¿Te ha resultado útil este artículo?