Vue d'ensemble
Delonix Runtime — Manuel du contributeur
Ce manuel s’adresse aux personnes qui veulent modifier le moteur : vous avez cloné le dépôt aujourd’hui et vous voulez envoyer une première pull request sans casser votre hôte ni le moteur. Après cette page, vous saurez comment le manuel est séquencé et quelles pages lire, dans quel ordre, pour votre rôle. Si vous voulez seulement utiliser Delonix, commencez plutôt par le README et le site de documentation utilisateur.
Le workspace compte 28 crates et livre 5 binaires (delonix, delonix-cri, delonix-mcp, delonix-mgmt, delonix-node-api).
Ce qu’est le moteur — et ce qu’il n’est pas#
Delonix Runtime est une abstraction d’exécution pour un nœud : il exécute des containers et des microVM
et gère le réseau et le stockage dont ils ont besoin. Il est déclaratif (ses propres Kinds, regroupés par
apiVersion — voir delonix api-resources), et il ne parle aux providers (le noyau Linux, libvirt,
Cloud Hypervisor, Proxmox VE, le CRI de Kubernetes) qu’à travers des ports, jamais à travers
des branches if provider == … dispersées dans le code.
Trois principes façonnent presque tous les commentaires de revue que vous recevrez :
- Cloud native — plan / apply / dérive, API-first (la CLI, l’API de nœud, le CRI et le serveur MCP exposent les mêmes opérations), observable au moyen de standards ouverts.
- Daemonless — aucun processus résident par défaut. Ce qui doit persister appartient à systemd ou à un processus par workload avec un propriétaire clair. Un nouveau daemon exige un ADR.
- Rootless-first — le chemin normal s’exécute sans root ; le privilège est un opt-in explicite.
Et une frontière imposée par un gate (contrôle CI) : le moteur ne connaît aucun consommateur. Il ne sait pas
qui l’appelle, et il n’a aucune notion de locataire, de compte, d’offre ou de facturation. Une exigence venant d’un
consommateur entre sous la forme d’une capacité générique du moteur, ou elle n’entre pas. Le texte canonique est la
section «Identidade e fronteira do motor» en tête de AGENTS.md.
Deux moitiés : faits générés et récit#
Les pages de ce manuel mélangent deux types de contenu :
- Faits — quels crates existent, leur couche, qui dépend de qui, les binaires, la
toolchain épinglée, les jobs de CI. Ils vivent entre les marqueurs
<!-- dev-docs:begin <key> -->et<!-- dev-docs:end <key> -->et sont générés parpython3 scripts/dev_docs.pyà partir deCargo.toml,scripts/arch_fitness.py,rust-toolchain.tomlet.github/workflows/ci.yml. Ne les modifiez jamais à la main — la CI exécutedev_docs.py --checket échoue. Si un fait est faux, corrigez la source ou le générateur. - Récit — pourquoi les choses sont ainsi, comment les flux fonctionnent, comment contribuer. Il est écrit à la main et relu après chaque release. Voir Publier la documentation.
Comment ce manuel est organisé#
Les pages forment un seul parcours, lu de haut en bas. Chaque page s’ouvre sur une ligne Avant de lire qui nomme les pages antérieures qu’elle suppose acquises, et se termine par une ligne Suivant pointant vers la page qui s’appuie dessus. Le numéro affiché à côté d’une page dans la barre latérale du site est sa position dans cet ordre. Les numéros de section à l’intérieur d’une page (par exemple §3.8 dans l’initiation à Rust, ou 13.4 dans la page des standards) sont des repères locaux maintenus stables pour les liens ; ce ne sont pas des positions de page.
Le parcours est regroupé en huit parties :
| Partie | Pages | Ce que vous en tirez |
|---|---|---|
| Commencer | Commencer ici · IaaS et cloud native | Un checkout qui fonctionne, un premier chemin de contribution, et le modèle mental de la place d’un moteur de nœud dans un cloud |
| Fondations | Fondations Linux · Initiation au cloud native · Initiation à Rust | Les primitives du noyau en pratique, comment le moteur utilise chacune, et le Rust dans lequel ce code est écrit |
| Préparer et compiler | Préparer votre environnement · Cloner, compiler et tester | Un hôte capable d’exécuter les chemins réels, et chaque gate de CI comme commande locale |
| Architecture | Structure du projet · Architecture · Les crates · System Design Interview | Où se trouvent les choses, pourquoi elles sont ainsi découpées, ce que possède chaque crate, et le raisonnement derrière la conception |
| Images et microVM | Delonixfile et VMfile · Construire des microVM | Les deux grammaires de build, et les VM depuis les prérequis de l’hôte jusqu’au démarrage |
| Opérer et déboguer | Diagnostic des problèmes · Comment les noms atteignent /etc/hosts |
Un index par symptôme de ce qu’un gate ou une exécution réelle affiche, et le mécanisme qui publie les noms de service et les hôtes de route sur la machine de l’opérateur |
| Contribuer | Conventions de code · Ajouter un Kind · Flux de contribution · Releases et stabilité · Publier la documentation | Comment le code doit être écrit, comment un Kind déclaratif s’ajoute, comment un changement est envoyé, ce qu’une release promet de ne pas casser, et comment la documentation suit |
| Référence | Standards cloud native · Variables d’environnement · Glossaire | Des pages où l’on cherche des informations : conformité par standard, chaque nom DELONIX_*, chaque terme |
Les concepts sont enseignés une seule fois : une primitive du noyau dans Fondations Linux, comment le moteur l’utilise dans Initiation au cloud native, et le standard qu’elle suit avec son état de conformité dans Standards cloud native. Quand une page mentionne quelque chose enseigné ailleurs, elle y renvoie au lieu de le répéter.
Parcours de lecture par rôle#
Personne n’est censé lire les vingt-deux pages avant un premier changement. Choisissez la ligne qui vous décrit et lisez ses pages dans l’ordre indiqué ; gardez le Glossaire ouvert.
| Rôle | Lisez, dans cet ordre — et pourquoi |
|---|---|
| Première PR, sans temps | 1. Commencer ici — la vérification du jour 0 et les huit étapes d’une première PR. 2. Préparer votre environnement — seulement Pièges d’hôte connus. 3. Cloner, compiler et tester — les gates que vous devez passer. 4. Les crates — seulement la section du crate que vous touchez. 5. Flux de contribution — comment la PR est jugée. |
| Ingénieur DevOps (CI, packaging, installation, releases) | 1. Commencer ici — la configuration et les règles. 2. Préparer votre environnement — ce dont un hôte a besoin et les pièges qui ressemblent à des bugs du moteur. 3. Cloner, compiler et tester — installer un build, chaque job de CI comme commande locale, E2E et chaos. 4. Structure du projet — ce qui est généré, ce que la CI vérifie, ce que release.yml rafraîchit. 5. Diagnostic des problèmes — reconnaître l’échec d’un gate à son message. 6. Releases et stabilité — le gate de version, ce que fait une tag poussée, ce qui est stable. 7. Publier la documentation — ce qui se passe au moment de la release. 8. Variables d’environnement — chaque réglage et lesquels abaissent une frontière. |
| Ingénieur plateforme (qui construit sur les interfaces du moteur) | 1. IaaS et cloud native — quelle couche est le moteur et ce qu’il laisse à un control plane. 2. Initiation au cloud native — les Kinds et le réconciliateur à trois voies. 3. Architecture — les interfaces (CLI, CRI, API de gestion, MCP, contrat de nœud) et les couches. 4. Les crates — delonix-stack, delonix-cri, delonix-mgmt, delonix-mcp. 5. Ajouter un Kind — la table et le câblage du réconciliateur qu’exige un nouveau Kind. 6. System Design Interview — les choix d’API et leurs compromis. 7. Standards cloud native — ce qui est conforme, partiel ou absent, avec des dates. |
| SRE (opérant des nœuds, diagnostiquant des pannes) | 1. Fondations Linux — répondre à « quel namespace, quel cgroup, qui tient ce fd » avec une commande. 2. Préparer votre environnement — diagnostiquer un hôte et ses pièges. 3. Diagnostic des problèmes — un index par symptôme pour les échecs de gate et de runtime. 4. Architecture — quels processus existent en runtime, l’état sur disque, les limitations connues. 5. System Design Interview — modes de panne et limites d’un nœud. 6. Conventions de code — ce que signifie un code de sortie. 7. Variables d’environnement — logging, OTLP et les échappatoires. 8. Standards cloud native — OpenTelemetry et Prometheus. |
| Développeur cloud (Kinds, manifestes, images, compatibilité Compose/Docker) | 1. IaaS et cloud native — les principes tels qu’ils apparaissent dans le code. 2. Initiation au cloud native — images OCI et réconciliation déclarative. 3. Cloner, compiler et tester — compiler et exécuter isolé. 4. Les crates — delonix-stack et delonix-oci. 5. Delonixfile et VMfile — les grammaires de build. 6. Conventions de code — règles pour les Kinds et les champs. 7. Ajouter un Kind — câbler un Kind dans le réconciliateur de bout en bout. 8. Standards cloud native — Kinds propres, API Docker et sous-ensembles de Compose. |
| Développeur Linux (namespaces, cgroups, réseau, VM) | 1. Fondations Linux — les primitives en pratique. 2. Initiation au cloud native — où vit chaque primitive dans le code. 3. Initiation à Rust — unsafe, syscalls, fork/clone dans des processus multithreads. 4. Préparer votre environnement — pièges d’AppArmor et de délégation de cgroup. 5. Architecture — l’infrastructure réseau rootless et les deux flux en séquences. 6. Les crates — delonix-linux, delonix-sdn, delonix-vm. 7. Construire des microVM — KVM, Cloud Hypervisor, libvirt. 8. Conventions de code — les règles pour unsafe et les processus. |
Deux tâches plus étroites ont leur propre raccourci : changer la façon dont la documentation est produite commence à Publier la documentation ; configurer ou isoler une exécution commence à Isoler l’état du moteur puis Variables d’environnement.
Pages#
| Page | Ce à quoi elle répond |
|---|---|
| Commencer ici | Vérification de la configuration au jour 0, votre première contribution de bout en bout, où va une modification, les règles et leurs sources, que faire quand vous êtes bloqué |
| IaaS et cloud native | De quoi est faite une IaaS, quelle couche est ce moteur, ce qu’il laisse à un control plane, et comment les principes cloud native apparaissent dans ses fichiers |
| Fondations Linux | Processus, namespaces, cgroups v2, descripteurs de fichier et signaux — en pratique, avec les commandes pour inspecter chacun |
| Initiation au cloud native | Comment le moteur utilise namespaces, cgroups, capabilities, OCI, réseau, CRI, KVM et réconciliation — avec fichiers et symboles |
| Initiation à Rust pour cette base de code | Le Rust que cette base de code utilise réellement |
| Préparer votre environnement | Ce dont le noyau et l’hôte ont besoin, la toolchain épinglée, et les pièges de l’hôte qui ressemblent à des bugs du moteur |
| Cloner, compiler et tester | Compiler, installer, exécuter les tests, chaque gate de CI comme commande locale, E2E et chaos avec isolation |
| Structure du projet | Ce qu’est chaque fichier et répertoire de premier niveau, qui le modifie, et ce qui est généré |
| Architecture | Couches, le graphe des crates, processus en runtime, chemins de contrôle et de données, état sur disque |
| Les crates | Un bloc par crate : responsabilité, types principaux, par où commencer la lecture |
| System Design Interview | Le moteur conçu comme une réponse d’entretien, puis comparé à ce qui a été construit |
| Delonixfile et VMfile | Les grammaires des fichiers de build et en quoi elles diffèrent d’un Dockerfile |
| Construire des microVM | KVM, Cloud Hypervisor et firmware, libvirt, images de VM |
| Diagnostic des problèmes | Un index par symptôme : messages d’échec de gate, pièges de l’hôte et leurs correctifs, au même endroit |
Comment les noms atteignent /etc/hosts |
Le bloc délimité unique, les deux façons dont un nom y entre (hosts: [host] et delonix hosts sync), ce qu’il refuse, et comment le tester sans root |
| Conventions de code | Comment le code de ce dépôt est écrit, et la liste de contrôle qu’appliquent les relecteurs |
| Ajouter un Kind | La table, le schéma et le câblage du réconciliateur qu’exige un nouveau Kind déclaratif, illustré avec Service |
| Flux de contribution | Worktrees, versions, règle de langue, règles d’architecture, ADR, commits et PR |
| Releases et stabilité | Le gate de version, ce que fait une tag poussée, et ce que la CLI et le schéma de manifeste promettent de ne pas casser |
| Publier la documentation | Comment le site et ce manuel sont générés, contrôlés et publiés |
| Standards cloud native | Chaque standard, ce qu’il exige, comment Delonix l’implémente, et son état de conformité |
| Variables d’environnement | Chaque variable DELONIX_* que lit le code : qui la lit, ce qu’elle change, sa valeur par défaut, et lesquelles abaissent une frontière |
| Glossaire | Les termes du moteur et du cloud native que vous rencontrez ici, avec leur sens dans Delonix et où en lire davantage |
Autres références vers lesquelles on vous renverra : ARCHITECTURE.md (diagrammes C4),
docs/adr/ (décisions d’architecture), SECURITY.md
(signalements privés de vulnérabilités) et CONTRIBUTING.md (la courte porte d’entrée).
Suivant : Commencer ici — vérifiez votre configuration en trente minutes et parcourez une première contribution de bout en bout.