Asgard Forge

1 Présentation

Forge est un conteneur Docker que vous installez sur une VM Linux de votre réseau. Il n'a aucune copie de votre infrastructure as code : à chaque exécution, il télécharge votre dépôt GitLab au commit exact et lance les outils sur ces fichiers.

• OpenTofu crée la VM en clonant le template Proxmox (dossier Terraform du dépôt).
• Ansible la configure ensuite (dossier Ansible du dépôt) : réseau, comptes, swap, langue, agents…
• Packer reconstruit le template quand vous le demandez (dossier Packer du dépôt).
• Le formulaire est généré à partir des fichiers : une variable ajoutée dans GitLab apparaît toute seule dans Forge.

Navigateur ──▶ Forge :8080  (VM Linux, docker, réseau de l'hôte)
                 │
                 ├─▶ GitLab        archive du dépôt au commit · variables CI/CD · un état Terraform par VM
                 ├─▶ Proxmox       listes (nœuds, stockages, templates, étiquettes) · contrôles · clonage
                 ├─▶ nouvelle VM   OpenTofu → attente SSH → Ansible → agents
                 └─▶ Argos · Wazuh · ntfy · Discord   (facultatif)

Chaque VM a son propre état Terraform dans GitLab (forge-<vmid>-<nom>) : déployer une machine n'en détruit jamais une autre.

2 Prérequis

• VM Linux avec Docker et docker compose (amd64 ou arm64), 2 Go de RAM et une vingtaine de Go de disque (caches des providers et plugins). Elle doit joindre GitLab, Proxmox et le réseau des futures VM (SSH).
• Un dépôt GitLab organisé en trois dossiers (ex. 01_packer/, 02_terraform/, 03_ansible/) avec un .gitlab-ci.yml : Forge y lit les dossiers, les valeurs par défaut et la commande Ansible.
• Un jeton d'accès de projet GitLab : rôle Maintainer, portée api (lecture du dépôt et des variables CI/CD, écriture des états Terraform).
• Dans les variables CI/CD du projet : PROXMOX_HOST (URL de l'API, avec /api2/json), PROXMOX_TOKEN_ID et PROXMOX_TOKEN_SECRET — les mêmes que pour le pipeline.
• Un template Proxmox avec cloud-init et l'agent QEMU (ou l'ISO pour le construire avec Packer).

3 Installation

L'image est publiée sur le Docker Hub (anpms/asgard-forge:latest, amd64 et arm64, chaque version aussi sous son numéro) : elle contient Forge, OpenTofu, Packer et Ansible — rien à installer sur la VM à part Docker.

1. 1 Préparer le dossier

   mkdir -p ~/asgard-forge/data && cd ~/asgard-forge
   # compose.yml : dépôt asgard-forge, dossier deploy/ — aucun .env

2. 2 Le compose.yml

   services:
     forge:
       image: anpms/asgard-forge:latest
       container_name: asgard-forge
       restart: unless-stopped
       network_mode: host          # Proxmox doit joindre le serveur HTTP de Packer (8802)
       volumes:
         - ./data:/data
       stop_grace_period: 40s      # OpenTofu relâche son verrou d'état

3. 3 Démarrer et créer le compte

   docker compose up -d
   docker compose logs -f        # « à l'écoute sur 0.0.0.0:8080 »

   Ouvrez http://<ip-vm>:8080 : au premier accès, Forge propose de créer le compte administrateur. Réglez ensuite les accès dans Paramètres, cliquez sur Tester pour chacun et activez la double authentification.

Le dossier data/ (base SQLite avec les paramètres chiffrés, clé maître secret.key, journaux, caches) doit appartenir à l'uid 1000, utilisateur du conteneur.

4 Les paramètres

Tout se règle dans Paramètres, par onglet, appliqué sans redémarrage. Seul le jeton GitLab est indispensable : les accès Proxmox et les options viennent de GitLab, comme pour le pipeline. Les secrets sont chiffrés et jamais réaffichés.

Mot de passe perdu : ADMIN_RESET_PASSWORD: "…" dans le compose, docker compose up -d, connectez-vous, retirez la ligne.

5 Ce que Forge lit dans GitLab

Rien n'est figé dans Forge : changez le dépôt, Forge suit (relecture toutes les 5 minutes, ou bouton Relire GitLab). La page GitLab de Forge affiche les fichiers du commit utilisé.

# .gitlab-ci.yml — une option apparaît dans Forge, libellé compris
variables:
  INSTALL_DOCKER: "false"  # Installer Docker et ajouter l'utilisateur au groupe docker

6 Déployer une machine

1. 1 Remplir le formulaire

   Identité (nom, VMID libre proposé, nœud, template, étiquettes), ressources, réseau, accès, options. Les listes viennent de Proxmox : nœuds avec leur mémoire libre, stockages avec leur place, templates du nœud, étiquettes déjà utilisées.

2. 2 Profils

   Enregistrez un jeu de valeurs (ex. « serveur Docker VLAN 20 »). Le nom, le VMID, l'IP et le mot de passe restent propres à chaque VM.

3. 3 Vérifier

   Contrôles avant envoi : formats, VMID libre, nom unique, IP qui ne répond pas, template présent, place sur le stockage, mémoire du nœud, clés SSH, état Terraform inexistant. Une erreur bloque, un avertissement non ; ils sont refaits au lancement.

4. 4 Suivre en direct

   Le journal défile en temps réel, secrets masqués ; une exécution à la fois, les suivantes attendent dans la file et peuvent être annulées.

7 Options du déploiement

Celles du dépôt machine-conf de référence ; elles sont toutes déclarées dans GitLab et utilisables aussi par le pipeline.

Toujours appliqués : swap /swap.img (mémoire, 4 Go au plus), langue fr_FR.UTF-8, fuseau Europe/Paris, ballooning mémoire actif, cloud-init purgé.

8 Intégrations

• Agent Argos — Automatique (Docker si l'option Docker est cochée, sinon natif), Natif (service systemd) ou Docker (vérifie la présence de Docker avant d'inscrire la machine). À la destruction, la machine est retirée d'Argos (Argos 0.3.2 et plus).
• Fiche Asgard Remote — la VM est proposée à Remote (dossier « homelab », sans identifiant) par l'intermédiaire d'Argos ; Remote l'ajoute à son coffre chiffré.
• Discord — fiche de la VM à la fin du déploiement (nom, ID, IP, utilisateur, ressources, commande SSH, nœud, VLAN, démarrée), l'erreur en cas d'échec, et un message à la destruction. Le webhook se règle dans Paramètres → Intégrations → Discord : Forge l'écrit dans la variable CI/CD DISCORD_WEBHOOK_URL, partagée avec le pipeline.
• Wazuh — Paramètres → Intégrations → Wazuh : un utilisateur de l'API Wazuh (lecture et suppression des agents), vérifié auprès du serveur puis enregistré dans les variables CI/CD (WAZUH_API_USER, et le mot de passe en base64 dans WAZUH_API_PASSWORD_B64, toujours masquable par GitLab). L'agent est alors supprimé du serveur à la destruction de la VM, et un ancien agent déconnecté du même nom est retiré avant un déploiement.
• ntfy — succès ou échec, avec lien vers le journal.

Chaque intégration se coche ou se décoche à chaque déploiement, dans le panneau Intégrations.

Créer l'utilisateur d'API Wazuh

L'API Wazuh (port 55000) a ses propres utilisateurs, distincts de ceux du tableau de bord. Pour Forge, un utilisateur dédié limité à deux droits suffit : dans le tableau de bord, Server management → Security :

1. Policies → Create policy : forge-agents, actions agent:read et agent:delete, ressource agent:id:*, effet Allow.
2. Roles → Create role : forge, avec la policy forge-agents.
3. Users → Create user : forge-api (mot de passe de 8 à 64 caractères avec majuscule, minuscule, chiffre et symbole), rôle forge.

Ou en ligne de commande sur le serveur Wazuh, avec l'administrateur de l'API (wazuh, mot de passe dans wazuh-passwords.txt) :

API=https://localhost:55000
TOKEN=$(curl -sk -u wazuh:'<mot de passe admin>' -X POST "$API/security/user/authenticate?raw=true")
H=(-sk -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json")
curl "${H[@]}" -X POST "$API/security/policies" -d '{"name":"forge-agents","policy":{"actions":["agent:read","agent:delete"],"resources":["agent:id:*"],"effect":"allow"}}'
curl "${H[@]}" -X POST "$API/security/roles" -d '{"name":"forge"}'
curl "${H[@]}" -X POST "$API/security/users" -d '{"username":"forge-api","password":"<mot de passe>"}'
# puis, avec les identifiants renvoyés :
curl "${H[@]}" -X POST "$API/security/roles/<id_role>/policies?policy_ids=<id_policy>"
curl "${H[@]}" -X POST "$API/security/users/<id_user>/roles?role_ids=<id_role>"

9 Machines & destruction

La page Machines liste les VM créées par Forge avec leur état réel sur Proxmox (allumée, éteinte, absente), leurs ressources, agent Argos, commit et état Terraform. Les options n'y figurent que si elles distinguent la VM : cases cochées sous un nom court (Docker, Wazuh), nombre de clés SSH, réglages différents du défaut (libellé complet au survol).

• Détruire exige de retaper le nom de la VM. Forge rejoue OpenTofu avec la configuration du commit du déploiement (même si le dépôt a changé depuis), supprime l'état Terraform de GitLab, puis retire la machine d'Argos et son agent de Wazuh.
• Une VM en échec peut être détruite (nettoyage) ou simplement retirée de la liste.
• Le mot de passe de la VM n'est jamais enregistré : notez-le, ou déposez une clé SSH.

10 Template Packer

Chaque sous-dossier de 01_packer/ qui contient des fichiers .pkr.hcl est un template : la page Template les propose tous (onglets), celui du job CI en premier. Le dépôt de référence en contient deux :

Les deux ont le même réseau (netplan + systemd-networkd), cloud-init et l'agent QEMU : le playbook Ansible est commun et s'adapte à la distribution (dépôt Docker, langue, sudo). Le template à cloner se choisit dans le formulaire de déploiement ; dans la CI GitLab, TEMPLATE_NAME (déploiement) et PACKER_TEMPLATE (construction).

Avant de lancer, Forge vérifie : ISO présent sur le stockage, VMID cible, nœud, IP de Forge pour le serveur HTTP de Packer.

1. Packer construit le nouveau template sur un VMID temporaire : l'ancien reste utilisable pendant ce temps.
2. En cas de succès, l'ancien est supprimé et le nouveau reprend le VMID et le nom du dépôt.
3. En cas d'échec, rien ne change.

11 Sécurité

• Secrets chiffrés dans la base de Forge ou dans les variables CI/CD GitLab ; l'interface n'en réaffiche aucun.
• Les outils reçoivent les secrets par variables d'environnement, jamais en argument ; ils sont masqués dans les journaux. Les outils ne voient pas l'environnement de Forge.
• Session par cookie, protection CSRF, limitation des tentatives, double authentification TOTP.
• Chaque exécution d'Ansible part d'un dossier vierge (empreintes SSH, connexions) : une VM qui reprend une IP déjà vue n'est pas bloquée.
• Réseau local ou VPN uniquement : Forge crée et détruit des VM.

12 Mise à jour & sauvegarde

cd ~/asgard-forge
docker compose pull && docker compose up -d

Le compose.yml suit le tag latest : ces deux commandes suffisent à passer à la dernière version (affichée en bas du menu de Forge). Pour figer une version, remplacez latest par un numéro (ex. anpms/asgard-forge:0.4.0) dans le compose.

À sauvegarder : le dossier data/ (forge.db avec VM, profils, historique et paramètres, et secret.key). Les états Terraform sont dans GitLab.

Si votre .gitlab-ci.yml lance un job de déploiement à chaque push sur main, poussez vos modifications de configuration avec git push -o ci.skip.

13 Dépannage