Edu-Kit - Gérer les réseaux proxmox et le bastion warpgat avec les APIs

1. Vue d’ensemble

Ce document décrit les appels API que le backend edu-kit doit effectuer pour gérer le réseau Proxmox (SDN) et le bastion SSH (Warpgate) lors des différentes actions de la plateforme.

Architecture 

┌──────────────┐         ┌─────────────────────────────────────────────┐
│   Edu-Kit    │         │            Proxmox Client (PVE 9.x)         │
│  (Cluster)   │         │                                             │
│              │  API    │  vmbr0 (réseau école)                       │
│  - App web   │◄───────►│    │                                        │
│  - Keycloak  │  SSH    │    ├── VM Warpgate (Docker, port 2222/8888) │
│              │         │    │                                        │
└──────────────┘         │    ├── [SDN] Zone env-{id}                  │
                         │    │   └── VNet vnet-{id} (10.200.{id}.0/24)│
                         │    │       ├── VM étudiant A                │
                         │    │       └── VM étudiant B                │
                         │    │                                        │
                         │    └── [SDN] Zone env-{id2}                 │
                         │        └── VNet vnet-{id2}                  │
                         └─────────────────────────────────────────────┘

APIs utilisées

Service Base URL Authentification
Proxmox VE https://{proxmox_host}:8006/api2/json Token API PVE
PVEAPIToken={user}@{realm}!{tokenid}={secret}
Warpgate https://{warpgate_host}:8888/@warpgate/admin/api Bearer token (Authorization: Bearer {token})
Keycloak https://{keycloak_host}/admin/realms/{realm} Bearer token OIDC

2. Setup initial d’un Proxmox client (une seule fois)

Ce setup est exécuté une seule fois lors du déploiement d’un nouveau Proxmox client. Il peut être automatisé dans un script ou playbook.

2.1 Prérequis serveur (SSH) 

# Installer dnsmasq (nécessaire pour le DHCP SDN)
apt install -y dnsmasq
systemctl disable --now dnsmasq

# Vérifier la config réseau
grep -q "source /etc/network/interfaces.d/*" /etc/network/interfaces || \
  echo "source /etc/network/interfaces.d/*" >> /etc/network/interfaces

2.2 Firewall Datacenter (API Proxmox)

Configurer le firewall une seule fois. Ces règles ne changent jamais.

D’abord, ajouter les règles fixes (le firewall est encore désactivé, les règles sont prêtes mais inactives) :

POST /cluster/firewall/rules
{ "type": "in", "action": "ACCEPT", "proto": "tcp", "dport": "2244", "enable": 1, "comment": "SSH access" }

POST /cluster/firewall/rules
{ "type": "in", "action": "ACCEPT", "proto": "tcp", "dport": "8006", "enable": 1, "comment": "Web UI & API access" }

POST /cluster/firewall/rules
{ "type": "in", "action": "ACCEPT", "macro": "DHCPfwd", "enable": 1, "comment": "DHCP global" }

POST /cluster/firewall/rules
{ "type": "in", "action": "ACCEPT", "macro": "DNS", "enable": 1, "comment": "DNS global" }

Ensuite, activer le firewall (les règles sont déjà en place, pas de coupure) :

PUT /cluster/firewall/options
{
  "enable": 1,
  "policy_in": "DROP"
}

2.3 Firewall Nœud (API Proxmox)

D’abord, ajouter la règle FORWARD DROP globale (inactive tant que nftables n’est pas activé) :

POST /nodes/{node}/firewall/rules
{
  "type": "forward",
  "action": "DROP",
  "source": "10.200.0.0/16",
  "dest": "10.200.0.0/16",
  "enable": 1,
  "comment": "Block inter-zone"
}

Cette règle doit toujours rester en dernière position. Toutes les règles FORWARD ACCEPT ajoutées par la suite doivent être insérées avant elle.

Ensuite, activer nftables (la règle DROP est déjà en place) :

PUT /nodes/{node}/firewall/options
{
  "enable": 1,
  "nftables": 1
}

2.4 Déployer la VM Warpgate (à voir pour automatiser)

Créer une VM Debian cloud-init sur vmbr0, installer Docker, déployer Warpgate, configurer le SSO Keycloak. Voir le plan d’implémentation pour les détails.

Dans keycloak :

Ajouter un client dans keycloak :

  • Client type : OpenId Connect
  • Client ID : warpgate-pve5
  • Name : warpgate-pve5
  • Client authetification : On
  • Authorization : off
  • Authentification flow :
    • Standard flow : on
    • Direct access grants : on
    • tout le reste en off
  • Valid redirect URIs : https://<ip-ou-domaine-warpgate>:8888/@warpgate/api/sso/return

Ensuite, une fois le client créé, récupérer le Client Secret dans l’onglet credentials.

Ensuite dans le fichier de config de warpgate, ajouter la partie sso_providers :

Voici une partie du fichier de configuration de warpgate (warpgate.yaml) :

sso_providers:
  - name: keycloak
    label: "Se connecter avec Edu-Kit"
    provider:
      type: custom
      client_id: warpgate-pve4
      client_secret: WceJlnpob34CEFb4TcMJhi6Pb0bMhyH3
      issuer_url: https://keycloak.edu-kit.fr/realms/edukit
      scopes: ["openid", "email"]
recordings:
  enable: true
  path: /data/recordings
external_host: 10.4.0.137:8888
database_url: sqlite:/data/db
ssh:
  enable: true
  listen: '[::]:2222'
  external_port: null
  external_host: null
  keys: /data/ssh-keys
  host_key_verification: prompt
  inactivity_timeout: 5m
  keepalive_interval: null
http:
  listen: '[::]:8888'
  external_port: null
  external_host: null
  certificate: /data/tls.certificate.pem
  key: /data/tls.key.pem
  trust_x_forwarded_headers: false
  session_max_age: 30m
  cookie_max_age: 1day
  sni_certificates: []
kubernetes:
  enable: true
  listen: '[::]:8443'
  external_port: null
  external_host: null
  certificate: /data/tls.certificate.pem
  key: /data/tls.key.pem
  session_max_age: 30m
mysql:
  enable: true
  listen: '[::]:33306'
  external_port: null
  external_host: null

Redémarrer ensuite le conteneur warpgate.

Ajouter une route statique sur la VM Warpgate (dans /etc/netplan/50-cloud-init.yaml) :

Il faut spécifier l’IP du proxmox dans via: …

network:
  version: 2
  ethernets:
    eth0:
      match:
        macaddress: "bc:24:11:4a:6a:f0"
      dhcp4: true
      set-name: "eth0"
      # Ajouter la routes ci-dessous (à adapter selon votre configuration)
      routes:
        - to: 10.200.0.0/16
          via: <ip proxmox>

netplan apply

Ensuite, il faut créer un token API warpgate. Cliquer en haut à droite sur le nom d’utilisateur (admin) puis cliquer sur “API tokens” et enfin sur “create a token”.

Récupérer le token.

Pour utiliser l’api warpgate :

authentification dans postman : api key

key = X-Warpgate-Token

valut = token

3. Création d’un utilisateur dans edu-kit

Déclencheur : un prof crée un utilisateur (étudiant ou prof) dans l’application.

Étape 1 - Créer l’utilisateur dans Keycloak

L’application crée déjà l’utilisateur dans Keycloak. S’assurer que l’email est renseigné et vérifié.

Étape 2 - Créer l’utilisateur dans Warpgate 

POST /@warpgate/admin/api/users
{
  "username": "{email_utilisateur}"
}

Réponse : retourne l’objet utilisateur avec son id.

Ensuite il faut récupérer la liste des utilisateurs afin de récupérer l’id de l’utilisateur créé :

GET /@warpgate/admin/api/users

Étape 3 - Associer le SSO à l’utilisateur Warpgate

Ajouter le credential SSO avec l’email correspondant au compte Keycloak :

POST /@warpgate/admin/api/users//credentials/sso
{
  "provider": "keycloak",
  "email": "student1@edukit.dev"
}

Étape 4 - Créer un rôle personnel pour l’utilisateur 

POST /@warpgate/admin/api/roles
{
  "name": "",
  "description": "string"
}

Pour récupérer l’id du role, lister les roles et récupérer l’id du bon rôle :

GET /@warpgate/admin/api/roles

Étape 5 - Assigner le rôle à l’utilisateur 

POST /@warpgate/admin/api/users//roles/

{

}

Résumé du flux 

Prof crée un utilisateur
    │
    ├──► Keycloak : créer le compte avec email
    │
    ├──► Warpgate : créer l'utilisateur
    │
    ├──► Warpgate : ajouter le credential SSO (email)
    │
    ├──► Warpgate : créer le rôle "user-{user_id}"
    │
    └──► Warpgate : assigner le rôle à l'utilisateur

4. Création d’un environnement de travail

Déclencheur : un prof crée un environnement de travail dans edu-kit et y associe un groupe + un modèle de VM.

Étape 1 - Créer la zone SDN 

POST /cluster/sdn/zones
{
  "zone": "env{id}",
  "type": "simple",
  "ipam": "pve",
  "dhcp": "dnsmasq"
}

Contrainte : l’ID de zone est alphanumérique, max 8 caractères. Actuellement nous déployons des réseaux en /24 soit 254 réseaux disponible donc max 254 environnement de travail. l’id doit strictement correspondre à l’addresse du réseau. Exemple :

  • env1
    • réseau env1 : 10.200.1.0/24
  • env2
    • réseau env2 : 10.200.2.0/24

Il faut donc soit faire une requête api pour récupérer les env{id} existant et donc déduire les env{id} disponibles, ou alors, stocker en base les env id.

Étape 2 - Créer le VNet 

POST /cluster/sdn/vnets
{
  "vnet": "vnet{id}",
  "zone": "env{id}"
}

Idem que ci-dessus, il faudra utiliser un env. A savoir que pour respecter une certaine logique, l’id d’un vnet sera le même que celui de son env associé. (ex: env1 avec vnet1).

Étape 3 - Créer le Subnet 

POST /cluster/sdn/vnets/vnet{id}/subnets
{
  "subnet": "10.200.{id}.0/24",
  "type": "subnet",
  "gateway": "10.200.{id}.1",
  "snat": 1,
  "dhcp-range": "start-address=10.200.{id}.10,end-address=10.200.{id}.200"
}

Étape 4 - Appliquer le SDN 

PUT /cluster/sdn

Important : attendre que la tâche se termine avec succès avant de continuer.

Étape 5 - Ajouter la règle firewall FORWARD ACCEPT 

POST /nodes/{node}/firewall/rules
{
  "type": "forward",
  "action": "ACCEPT",
  "source": "+sdn/vnet{id}-all",
  "dest": "+sdn/vnet{id}-all",
  "enable": 1,
  "comment": "Allow intra env{id}"
}

Important : cette règle doit être insérée AVANT la règle “Block inter-zone” (DROP). Utiliser le paramètre pos pour spécifier la position, ou réordonner après insertion. Vérifier le format exact de référence aux IPSets (+sdn/vnet{id}-all ou +vnet{id}-all).

En gros, idem que ci-dessus, il faut utiliser l’id cohérentes aux éléments précédents.

Étape 6 - Ajouter un target group dans warpgate 

POST /@warpgate/admin/api/target-groups

{
  "name": "Environnement de travail x",
  "description": "string",
  "color": "Primary"
}

Étape 7 - Créer un rôle pour l’environnement de travail 

POST /@warpgate/admin/api/roles

{
  "name": "Environnement de travail x",
  "description": "string"
}

Ensuite on peut lister tous les rôles pour pouvoir récupérer l’id du rôle créé :

GET /@warpgate/admin/api/roles

On peut aussi lister tous les utilisateurs pour récupérer l’id des user profs :

GET /@warpgate/admin/api/users

Étape 8 - Assigner tous les utilisateurs prof au rôle de l’environnement de travail

A faire pour chaque professeur

POST /@warpgate/admin/api/users//roles/

{

}

Résumé du flux 

Prof crée un environnement
    │
    ├──► Proxmox SDN : créer zone → VNet → subnet
    │
    ├──► Proxmox SDN : appliquer
    │
    └──► Proxmox Firewall : ajouter FORWARD ACCEPT intra-VNet
    │
    └──► Warpgate Target groupe : ajouter un target group dans warpget
    │
    └──► Warpgate Rôle env travail : créer rôle pour l'environnement de travail
    │
    └──► Warpgate Rôle en travail prof : Ajouter tous les porfs dans le groupe de l'env de travail

5. Provisionnement des VMs

Déclencheur : le prof clique sur “Provisionner” dans la section Machines Virtuelles. Edu-kit crée X VMs (une par membre du groupe) et les affecte automatiquement.

Étape 1 - Créer/cloner les VMs (existant)

Edu-kit fait déjà ça via l’API Proxmox et cloud-init. La seule modification : configurer l’interface réseau sur le VNet SDN au lieu de vmbr0. A savoir qu’il faudra utiliser le bon id du vnet selon l’environnement de travail.

Pour lister les différents vnet :

GET /api2/json/cluster/sdn/vnets

Ensuite pour modifier la carte réseau d’une vm pour y associer le bon vnet :

(à savoir qu’il faut utiliser le vnet id correspondant à l’environnement de travail comme détaillé plus haut)

PUT /api2/json/nodes/{node}/qemu/{vmid}/config
{
  "net0": "virtio,bridge=vnet{id}",
  "ipconfig0": "ip=dhcp"
}

Étape 2 - Créer un target SSH dans Warpgate pour chaque VM

Attendre que la VM ait reçu son IP DHCP (vérifiable via l’IPAM Proxmox ou le guest agent).

Dès qu’on a récupérer l’ip de la VM, il faut créer le target de la vm dans warpgate.

Nous allons avoir besoins de récupérer l’id du groupe de target. Pour cela, lister les groupes de target :

POST /@warpgate/admin/api/target-groups

Pour le paramètre host, c’est ici qu’il faudra mettre l’ip de la vm.

Il faudra également que la vm ait la clé publique de warpgate.

POST /@warpgate/admin/api/targets
{
  "name": "env-vm",
  "options": {
    "kind": "Ssh",
    "host": "10.200.1.1",
    "port": 22,
    "username": "root",
    "allow_insecure_algos": true,
    "auth": {
        "kind": "PublicKey"
    }
  },
  "groupe_id": ""
}

Possibilité de récupérer la clé publique de wargate de cette façon :

GET /@warpgate/admin/api/ssh/own-keys

Étape 3 - Assigner le target au rôle de l’étudiant, au rôle de l’environnement de travail et au rôle admin

Chaque étudiant a un rôle personnel user-{user_id} (créé à l’étape 3 de la section “Création d’un utilisateur”).

Il faut également ajouter le target au role de l’environnement de travail, et aussi au role admin.

Pour récupérer la liste des targets :

GET /@warpgate/admin/api/targets

Pour récupérer la liste des rôles :

GET /@warpgate/admin/api/targets

Puis utiliser l’id du target et des rôles souhaité pour chacun des rôles.

A faire 3 fois avec les différents rôles (role élèves, rôle environnement de travail et rôle admin)

POST /@warpgate/admin/api/targets//roles/

Résumé du flux 

Prof provisionne les VMs
    │
    ├──► Proxmox : créer/cloner les VMs sur vnet{id} (existant)
    │
    │    Pour chaque VM :
    │    │
    │    ├──► Proxmox : Configurer la carté réseau de la vm pour utiliser le bon vnet
    │    │
    │    ├──► Warpgate : créer le target SSH avec le bon groupe de target
    │    │
    │    ├──► Warpgate : assigner le target au rôle de l'étudiant
    │    │
    │    └──► Warpgate : assigner le target au rôle de l'environnement de travail
    │    │
    │    └──► Warpgate : assigner le target au rôle de l'admin
    │
    └──► Fin

6. Ouverture de ports (accès services web des VMs)

Déclencheur : l’étudiant ou le prof ajoute l’url de sont web (http://ip_de_la_vm:port) dans les paramètres d’une VM depuis l’interface edu-kit afin de pouvoir accéder l’interface web de ce qu’il a installé sur sa vm (exemple : glpi, ou tout autre service ayant une interface web.)

Étape 1 - Créer un target HTTP dans Warpgate

En description, on peut mettre l’id de la vm ou autre élément afin d’identifier à quel vm appartient ce target http.

POST /@warpgate/admin/api/targets
{
  "name": "le site web de ma vm",
  "description" : "<vmid>",
  "options": {
    "kind": "Http",
    "url": "",
    "allow_insecure_algos": true,
    "tls": {
        "mode": "Preferred",
        "verify": false
    }
  },
  "group_id": ""
}

Réponse : retourne l’objet target avec son id. Vérifier le format exact du payload dans la doc API de votre instance Warpgate.

Étape 2 - Assigner les rôles de l’étudiant, de l’environnement de travail et de l’admin au target

(à faire pour chaque rôle)

POST /@warpgate/admin/api/targets//roles/

Étape 4 - Récupérer le lien d’accès depuis Warpgate

On peut lister tous les targets pour pouvoir ensuite filtrer le résultat par rôle et par type. Le but étant de pouvoir avoir directement l’url qui redirige sur la page web du target http.

GET /@warpgate/admin/api/targets

L’URL d’accès pour l’étudiant est au format :

https://{warpgate_host}:8888/?warpgate-target={target_name}

Edu-kit récupère cette information via l’API et affiche le lien cliquable dans l’interface de la VM.

Étape 5 - Suppression d’un target http

Quand l’étudiant ou le prof retire un “port” :

DELETE /@warpgate/admin/api/targets/{target_id}

Résumé du flux 

Étudiant ajoute le port 80 sur sa VM
    │
    ├──► Warpgate : créer target HTTP "env1-vm102-http-80"
    │      (url: http://10.200.1.11:80)
    │
    ├──► Warpgate : assigner au rôle étudiant
    │
    ├──► Warpgate : assigner au rôle de l'environnement de travail
    │
    ├──► Warpgate : assigner au rôle de l'utilisateur admin
    │
    ├──► Warpgate : récupérer les infos du target via l'API
    │
    ├──► Edu-kit : afficher le lien dans l'interface
    │       L'étudiant clique → SSO Keycloak → service web affiché
    └──► Edu-kit : supprimer un port http d'une vm 
    				Warpgate supprimer le target http

7. Connexion SSH d’un étudiant

Aucune action côté edu-kit. L’étudiant se connecte directement :

ssh {username}:{target_name}@{ip_warpgate} -p 2222

Exemple :

ssh jean.dupont@edukit.dev:env1-vm102@10.4.0.170 -p 2222

Warpgate redirige vers la page de login Keycloak (SSO). L’étudiant s’authentifie, puis sa session SSH s’ouvre sur la VM.

L’étudiant ne voit que les targets associés à son rôle. Le prof voit toutes les VMs de ses environnements.

8. Destruction des VMs

Déclencheur : le prof détruit les VMs d’un environnement.

Pour chaque VM :

Étape 1 - Supprimer les targets Warpgate (SSH + HTTP) :

Supprimer le target SSH et tous les targets HTTP associés à la VM :

/@warpgate/admin/api/targets
DELETE /@warpgate/admin/api/targets/{target_id_http_port1}
...

Étape 2 - Arrêter et supprimer la VM (existant) :

Déjà géré par edu-kit

9. Destruction d’un environnement

Déclencheur : le prof supprime un environnement de travail.

Étape 1 - Détruire les VMs et les éléments associés à l’environnement de travail.

Pour lister toutes les vm à supprimer d’un environnement de travail, il faut lister les targets groups

GET /@warpgate/admin/api/target-groups

Ensuite, quand on liste les vms, on peut voir leur target groups

GET /@warpgate/admin/api/targets

Ainsi, à partir de ces données, on peut supprimer toutes les vm comprenant l’id du target group.

DELETE /@warpgate/admin/api/targets/

Une fois cela fait, on peut supprimer le targets group

DELETE /@warpgate/admin/api/target-groups/{id}

Ensuite il faut également lister les rôles pour récupérer l’id du rôle associé à l’environnement de travail

GET /@warpgate/admin/api/roles

Une fois l’id du rôle récupéré, on peut supprimer le rôle en question

DELETE /@warpgate/admin/api/role/{id}

Étape 2 - Supprimer la règle firewall FORWARD ACCEPT

Lister les règles du nœud pour trouver celle correspondant à l’environnement :

GET /api2/json/nodes//firewall/rules

Identifier la règle par son commentaire (Allow intra env{id}) et la supprimer :

DELETE /api2/json/nodes//firewall/rules/

Attention : la suppression se fait par position (pos = position). S’assurer de ne pas supprimer la mauvaise règle.

Étape 3 - Supprimer le SDN 

# Lister les subnets
GET /api2/json/cluster/sdn/vnets/{vnet}/subnets
# Supprimer le subnet
DELETE /api2/json/cluster/sdn/vnets/vnet/subnets/

# Lister les vnets
GET /api2/json/cluster/sdn/vnets
# Supprimer le VNet
DELETE /cluster/sdn/vnets/vnet{id}

# Lister les zones
GET /api2/json/cluster/sdn/zones
# Supprimer la zone
DELETE /api2/json/cluster/sdn/zones/

# Appliquer
PUT /api2/json/cluster/sdn

Note : le format de l’ID du subnet dans l’API est probablement vnet{id}-10.200.{id}.0-24. Vérifier sur votre installation.

10. Suppression d’un utilisateur

Déclencheur : un utilisateur est supprimé de edu-kit.

Étape 1 - Supprimer les targets associés

Si l’utilisateur a encore des VMs actives, supprimer les targets Warpgate correspondants.

Pour cela, lister les utilisateurs warpgate afin de trouver son id

GET /@warpgate/admin/api/users

Lister les rôles de l’utilisateurs afin de récupérer l’id du rôle personnel de l’utilisateur

GET /@warpgate/admin/api/users/{id}/roles

Lister tous les targets associés au rôle de l’utilisateur

GET /@warpgate/admin/api/role/{id}/targets

Pour chaque target associé à ce rôle, les supprimer

DELETE /@warpgate/admin/api/targets/{id}

Étape 2 - Supprimer le rôle personnel 

DELETE /@warpgate/admin/api/roles/{role_id}

Étape 3 - Supprimer l’utilisateur Warpgate 

DELETE /@warpgate/admin/api/users/{user_id}

Étape 4 - Supprimer l’utilisateur Keycloak

Fait par edu-kit (existant).

Points d’attention

SNAT et iptables

Le SNAT est toujours activé. Ne jamais utiliser le toggle SNAT dans l’UI ou l’API Proxmox pour activer/désactiver internet - il cause des doublons de règles iptables (bug connu Proxmox). Si un contrôle internet on/off est nécessaire à l’avenir, gérer les règles iptables directement en SSH.

Ordre des règles firewall du nœud

Les règles FORWARD ACCEPT doivent toujours être avant la règle FORWARD DROP globale. Quand on ajoute une nouvelle règle, utiliser le paramètre pos pour l’insérer à la bonne position.

IPSets auto-générés

Les IPSets +sdn/vnet{id}-all sont auto-générés par Proxmox SDN après un Apply. Ils contiennent le subnet du VNet et se mettent à jour automatiquement. Ne pas les créer manuellement.

Warpgate API

La documentation interactive de l’API Warpgate est accessible sur chaque instance : https://{warpgate_host}:8888/@warpgate/admin/. Les payloads exacts peuvent varier selon la version - toujours se référer à cette doc.

Tech preview

Le SDN DHCP et le firewall nftables de Proxmox sont en “tech preview”. Surveiller les mises à jour Proxmox pour d’éventuels changements de comportement.

Retour en haut

Edu-Kit · Documentation interne

Plateforme de virtualisation pédagogique