Template CI/CD

Cadence.CI s’appuie sur la technologie Mélodium pour fournir un service puissant et efficace. Ce tutoriel explique comment créer un CI/CD détaillé avec Mélodium.

Pour le CI/CD au sein de services existants, les intégrations GitHub et GitLab sont expliquées dans les sections suivantes.

Note

Vous avez besoin de Mélodium version 0.10.0 ou supérieure installée.

Créer un projet CI/CD Mélodium

À la racine du dépôt git, exécutez la commande melodium new --template cicd --path .melodium-ci cicd. Un dossier .melodium-ci/ est alors créé, contenant le code de base pour un CI fonctionnel.

Ce dossier contient trois fichiers :

Compo.toml
lib-root.mel
advanced.mel

Le fichier Compo.toml contient la configuration du programme CI/CD. lib-root.mel contient le programme CI/CD lui-même, et advanced.mel le même programme mais implémenté de façon avancée (ignoré dans cette page, voir Implémentation Avancée).

Dans lib-root.mel se trouve le traitement main, désigné comme point d’entrée principal par la configuration de base. Il n’est pas obligatoire pour un programme d’avoir un tel point d’entrée principal ; différents points d’entrée peuvent être utilisés pour différents modes de fonctionnement.

Le traitement main contient tous les éléments de base pour faire fonctionner le CI/CD :

quelques paramètres pour gérer l’échange de données en dehors du processus CI/CD,
un CicdDispatchEngine pour gérer la distribution du travail entre les différents services et runners,
des traitements tels que startup, build et test.

Le traitement startup est fourni par la bibliothèque standard Mélodium pour déclencher n’importe quoi dès le début du programme.

Implémentation CI/CD

Les traitements build et test sont basés sur simpleStep et simpleStepWithInput.

Ils prennent tous les deux le modèle CicdDispatchEngine et un signal d’entrée trigger.


build: simpleStep[cicd=cicd](
    name="build",
    image="ubuntu:noble",
    commands=|raw_commands([
    "apt-get update",
    "apt-get install -y git",
    "git config --global url.https://.insteadOf  git://",
    |format("git clone --branch {repository_clone_ref} --depth 1 {repository_clone_url} project",
        |map([
            |entry("repository_clone_ref", repository_clone_ref),
            |entry("repository_clone_url", repository_clone_url)
        ])
    ),
    "sh -c \"cd project/ ; ls -l --almost-all | tee files-list.txt\"",
    "mv project/files-list.txt /mnt/data/"
    ]),
    out_file="files-list.txt"
)


test: simpleStepWithInput[cicd=cicd](
    name="test",
    image="alpine",
    in_file="list.txt",
    commands=[
        |command("test", ["-s", "/mnt/data/list.txt"]),
        |command("cat", ["/mnt/data/list.txt"])
    ]
)

Ils prennent tous les deux quelques paramètres :

name, une chaîne nommant l’étape elle-même, utilisée dans les logs et les rapports ;
image, l’image de conteneur à utiliser ;
pull_secret, le secret (optionnel) à utiliser pour récupérer l’image de conteneur ;
commands, la liste des commandes à exécuter ;
out_file, le fichier (optionnel) à streamer comme sortie data.

Quelques paramètres sont disponibles pour configurer plus précisément une étape :

memory, mémoire (en mébioctets) dédiée au conteneur ;
cpu, quantité de CPUs (en millicores) ;
storage, espace disque (en mébioctets) disponible ;
arch, désignant l’architecture matérielle sur laquelle l’étape doit s’exécuter (ARM64 par défaut).

Actuellement les architectures AMD64/x86_64 |amd64() et ARM64/aarch64 |arm64() sont supportées.

Traitement des commandes

Le paramètre commands est une liste de commandes exécutées dans le conteneur.

Les commandes peuvent être spécifiées de plusieurs façons :

fonction |command(), pour une commande détaillée avec liste d’arguments ;
fonction |raw_command(), pour une commande en chaîne brute ;
fonction |raw_commands(), pour une liste complète de commandes en chaîne.

Déclencher et connecter les étapes

Les traitements simpleStep et simpleStepWithInput fournissent tous les deux des entrées et des sorties :

entrée trigger, pour instancier le conteneur et démarrer le traitement ;
sortie started, pour signaler quand les commandes commencent à s’exécuter ;
sortie completed, pour signaler la complétion réussie de l’étape ;
sortie failed, pour signaler l’échec de l’étape ;
sortie finished, pour signaler que l’étape est terminée, qu’elle ait réussi ou non ;
sortie data, streamant les données du fichier donné dans out_file.

De plus, simpleStepWithInput fournit une entrée data pour écrire le fichier in_file dans le conteneur avant d’exécuter les commandes.


startup.trigger -> build.trigger,data -> test.data
startup.trigger -----------------------> test.trigger

Dispatch et distribution

Mélodium distribue le travail parmi les workers situés sur différents conteneurs et machines, selon les exigences données. Le même programme CI/CD unique peut s’exécuter sur plusieurs processus et machines et permet une synchronisation et une planification précises entre des systèmes hétérogènes.

Un CicdDispatchEngine peut être configuré pour distribuer le travail via l’API cloud ou localement en utilisant la composition de conteneurs, indépendamment de l’endroit où le processus initial s’exécute.

Le paramètre location spécifie la méthode de dispatch à utiliser, avec les valeurs "api" (par défaut) ou "compose", envoyant respectivement les demandes de runner au dispatch à l’API ou les lançant via Podman Compose ou Docker Compose. Dans le cas de la composition de conteneurs, la satisfaction des exigences dépend des capacités de la machine, notamment l’architecture et la mémoire totale disponible.

Note

La distribution "compose" peut être utilisée dans des services CI/CD comme GitHub Actions et GitLab CI pour tirer pleinement parti des runners fournis sans dépendre de runners externes supplémentaires.

Exécuter le CI/CD localement avec distribution distante

Pour exécuter le programme CI/CD, invoquez Mélodium avec les paramètres du programme :


melodium .melodium-ci/Compo.toml --api_token <VOTRE_TOKEN_RUN_API> --output_directory /votre/répertoire/de/sortie --repository_clone_url <URL_CLONE_COMPLETE>.git --repository_clone_ref <BRANCHE_OU_TAG>

Où VOTRE_TOKEN_RUN_API est un token Run de Cadence.CI. Cela exécute le “moteur principal” du CI/CD depuis l’ordinateur local et distribue le travail sur des workers distants.

Tous les logs CI/CD sont affichés dans le terminal, et les données sont écrites dans /votre/répertoire/de/sortie.

Exécuter le CI/CD localement avec distribution locale

Si Podman Compose ou Docker Compose est installé localement, il est possible de lancer le CI/CD avec distribution locale :


melodium .melodium-ci/Compo.toml --work_location compose --api_token <VOTRE_TOKEN_RUN_API> --output_directory /votre/répertoire/de/sortie --repository_clone_url <URL_CLONE_COMPLETE>.git --repository_clone_ref <BRANCHE_OU_TAG>

Notez que le CI/CD est alors contraint aux capacités de la machine hôte, notamment en termes de mémoire et d’architecture.

Note

Le service Container Runtime doit être en cours d’exécution. C’est le cas par défaut avec Docker. Avec Podman, le service podman doit être lancé (ex. : podman system service --time 0 unix:///run/user/1000/podman/podman.sock).

Exécuter le CI/CD sur un service

Le CI/CD est exécutable sur tout service capable de faire tourner Mélodium. Les plus courants sont GitHub et GitLab, pour lesquels des procédures détaillées sont données dans les sections suivantes.

Construire un pipeline CI/CD Implémentation Avancée