Migration d'Easypanel vers Tugport : cinq dysfonctionnements et leçons tirées

Le 24 octobre, un développeur a migré son serveur de production principal de la plateforme de déploiement Easypanel vers Tugport, un nouvel outil qu'il est en train de développer. La migration a impliqué le déplacement de 14 projets et 57 services, y compris des bases de données, des blogs et des bots, en utilisant une seule instruction de ligne de commande. Bien que la transition ait été largement réussie, cinq problèmes spécifiques sont apparus lors du processus, mettant en évidence les pièges courants des migrations d'infrastructure automatisées.

Ce qui s'est passé

Le processus de migration a commencé par une simulation (dry run) pour cartographier les services sans effectuer de modifications, suivi de l'exécution réelle de la commande tugport migrate easypanel. Tugport, un binaire basé sur Rust qui fonctionne aux côtés de Docker, a importé l'état depuis Easypanel, y compris les projets, les variables d'environnement, les domaines et les certificats. Il a ensuite déplacé les bases de données une par une, en veillant à ce que l'ancienne instance soit arrêtée avant que la nouvelle ne démarre sur le même répertoire de données afin de prévenir toute corruption. Les applications ont été démarrées à côté de leurs homologues anciens en utilisant exactement les mêmes images, évitant ainsi les reconstructions lors du basculement.

Le basculement du trafic a eu lieu lorsque le proxy de Tugport a pris le contrôle des ports 80 et 443 depuis le proxy Traefik d'Easypanel en moins d'une demi-seconde. Un mécanisme de sécurité garantissait que si le nouveau proxy ne répondait pas dans les 30 secondes, l'ancien proxy reprendrait le contrôle. Le système journalisait chaque étape, permettant une reprise ou un retour en arrière si nécessaire. Les volumes et les montages bind sont restés en place, et les certificats ont été importés plutôt que réémis. Au final, 54 services tournaient sur Tugport, tandis que trois services précédemment réduits restaient arrêtés.

Malgré une conception soignée, cinq bugs ont émergé lors de cette première migration en production. Premièrement, les modèles de variables d'environnement d'Easypanel, tels que $(PROJECT_NAME), ont été copiés littéralement au lieu d'être résolus, nécessitant une correction manuelle. Deuxièmement, les domaines fictifs attribués par Easypanel ont perturbé les vérifications de santé de Tugport, faisant planter les services non-web en attendant des réponses HTTP. Troisièmement, un conflit de sous-réseau est survenu car l'ancienne pile de CI runner conservait encore son réseau épinglé, nécessitant un nettoyage manuel. Quatrièmement, un code d'erreur inoffensif a été affiché lors des relances, provoquant une alarme inutile. Enfin, les bots de polling Telegram ont rencontré des conflits temporaires alors que les instances anciennes et nouvelles tentaient simultanément de récupérer des mises à jour.

Détails clés

• La migration a déplacé 57 services répartis sur 14 projets, incluant des bases de données Postgres, MySQL et Mongo.
• Cinq bugs spécifiques ont été identifiés : copie littérale des modèles d'environnement, échecs des vérifications de santé dus aux domaines fictifs, chevauchements de pools réseau, journalisation cosmétique d'erreurs et conflits de polling des bots.
• Les vérifications de santé des bases de données expiraient initialement sous forte charge car elles s'exécutaient toutes les 5 secondes avec un délai d'attente de 5 secondes ; ces paramètres ont été ajustés à des intervalles de 30 secondes avec des délais d'attente de 15 secondes.
• Une balise Docker flottante (mysql:9) a causé une mise à niveau mineure involontaire de la version 9.7.0 à la 9.7.4, entraînant trois minutes d'indisponibilité.
• L'outil de migration épingle désormais les images de base de données à leurs versions exactes et résout automatiquement les modèles de variables d'environnement.

Contexte

Tugport est un panneau de déploiement auto-hébergé écrit en Rust. Il fonctionne aux côtés de Docker sur un serveur appartenant à l'utilisateur, gérant les builds issus des pushes git, la terminaison HTTPS et la gestion des services. Contrairement à certaines plateformes qui masquent l'infrastructure sous-jacente, Tugport est conçu pour la transparence et le contrôle, offrant des clés API à portée limitée pour les agents IA et des outils de migration intégrés pour les concurrents comme Easypanel et Coolify. L'outil est open-source sous licence MIT.

Easypanel est un panneau de gestion de serveur populaire qui simplifie le déploiement d'applications via Docker. Il utilise Traefik comme proxy inverse et gère les services via une interface graphique. Lors de la migration entre de telles plateformes, le défi ne réside pas seulement dans le déplacement des données, mais aussi dans la traduction des nuances de configuration, des paramètres réseau et de la logique de vérification de santé qui sont souvent implicites dans la plateforme d'origine.

Pourquoi c'est important

Pour les équipes exécutant des logiciels auto-hébergés, cette étude de cas illustre que les migrations automatisées sont rarement transparentes. Même avec un outil bien conçu, les différences dans la manière dont les plateformes gèrent les variables d'environnement, le réseau interne et les vérifications de santé peuvent provoquer des interruptions de service. Comprendre ces modes de défaillance aide les ingénieurs à anticiper les risques lors du changement de fournisseurs ou d'outils d'infrastructure. Cela souligne la nécessité de tests approfondis et l'importance de lire attentivement les sorties de simulation avant d'exécuter des changements en direct.

L'incident lié à la balise Docker flottante sert de rappel critique pour les environnements de production. S'appuyer sur des balises mutables comme latest ou des balises indiquant uniquement la version majeure peut entraîner des mises à jour inattendues et des temps d'arrêt. Épingler les images à des versions spécifiques garantit la reproductibilité et la stabilité, une bonne pratique souvent négligée jusqu'à ce qu'une migration force une réévaluation des configurations de déploiement.

Ce que vous pouvez faire

• Effectuez toujours une simulation de migration en premier lieu pour identifier les problèmes de mapping, les configurations manquantes et les services qui ne se transféreront pas automatiquement.
• Épinglez toutes les images de conteneurs à des versions spécifiques plutôt que d'utiliser des balises flottantes pour éviter les mises à jour involontaires lors des redéploiements.
• Passez en revue et ajustez les intervalles et les délais d'attente des vérifications de santé après la migration, surtout si la nouvelle plateforme présente des schémas d'utilisation des ressources différents par défaut.
• Vérifiez manuellement les variables d'environnement utilisant une syntaxe de modèle, car les outils automatisés peuvent ne pas résoudre correctement les espaces réservés spécifiques à la plateforme.
• Prévoyez des conflits temporaires pour les services basés sur le polling, tels que les bots de chat, en vous assurant que les anciennes instances sont complètement arrêtées avant que les nouvelles ne commencent à traiter les requêtes.
• Nettoyez les anciens réseaux et les ressources inutilisées après une migration réussie pour libérer de l'espace disque et prévenir les conflits de sous-réseaux.