Versions logicielles et reconstructions

Deux variables Terraform définissent le logiciel d’un Customer Edge : ce_os_version pour le système d’exploitation et ce_sw_version pour la version F5 Distributed Cloud. Ces deux variables se comportent d’une façon opposée à ce que leur lecture évidente laisse supposer — un champ vide vous donne la version la plus récente plutôt qu’aucune, et une version qui s’installe sur un nœud peut échouer sur un nœud identique disposant d’un disque plus petit.

Ce que font les champs de version, en deux phases

Distinguer les phases est tout l’enjeu. Confondues, le comportement semble contradictoire.

Au premier démarrage, un nœud installe ce que ce_sw_version désigne. terraform/modules/ce-node déploie l’image marketplace avec version = "latest", de sorte que la version avec laquelle un nœud arrive est celle que cette image embarque à ce moment-là — et cela évolue dans le temps. ce_sw_version choisit la destination, et non si quoi que ce soit se produit ; laisser ce champ vide signifie que le serveur choisit plutôt que le nœud reste en l’état. Il en va de même pour ce_os_version.

Ne supposez pas que cette évolution se fait nécessairement vers une version plus récente. Observé le 2026-07-28, l’image embarquait une version estampillée 20260703-e2c462a — plus récente que le crt-20250613-3382 de cette flotte et plus récente que le crt-20260201-0179 que le tenant annonçait. Nommer une version plus ancienne que celle embarquée par l’image demande au nœud de revenir en arrière, ce qui est courant : cette flotte a été créée ainsi et fonctionne.

Laisser un champ de version vide est le choix le plus risqué, pas le choix neutre. À la création, le serveur ne laisse pas un champ vide tel quel — il le remplit avec la version la plus récente annoncée et l’installe. Un site créé avec les deux champs non renseignés est revenu épinglé à crt-20260201-0179 et à l’OS 9.2026.14, les deux versions que le tenant annonçait, puis l’installation a échoué. Observé le 2026-07-29.

Cela a deux conséquences. Vide signifie « donnez-moi la plus récente », donc un déploiement non épinglé est celui qui a le plus de chances de rencontrer la limite de disque décrite ci-dessous. Et vous ne pouvez pas isoler un champ en laissant l’autre vide, car le serveur le remplit — renseignez les deux délibérément, ou acceptez la plus récente de chacun.

Après le premier démarrage, rien ne se met à niveau automatiquement. F5 Distributed Cloud annonce une version plus récente et attend. C’est là que s’applique « le nœud reste là où il a atterri » — après la création, pas pendant celle-ci.

Les deux phases sont visibles sur l’objet site. Observé le 2026-07-28, cette flotte :

volterra_software_status.available_version   crt-20260201-0179
operating_system_status.available_version    9.2026.14

tandis que les nœuds exécutent crt-20250613-3382 et l’OS 9.2024.6. Une version plus récente est disponible et n’a pas été adoptée — c’est l’état stable, non une mise à niveau bloquée.

Terraform ne peut pas modifier une version. L’API le peut

Ce sont deux faits distincts, et les confondre conduit à un plan erroné.

Terraform ne peut pas. ce_os_version et ce_sw_version sont effectivement des paramètres valables uniquement à la création. Modifiez l’un ou l’autre et appliquez, et l’API rejette la mise à jour avec [BAD_REQUEST] Invalid request parameters. Observé le 2026-07-29 sur des sites jetables, dans les trois directions — épinglage vers l’avant vers une version plus récente, épinglage vers l’arrière vers une version plus ancienne, et désépinglage en effaçant les deux champs. L’avancement n’est pas un cas particulier.

L’API le peut. F5 Distributed Cloud expose une action de mise à niveau dédiée par site, qui démarre la modification en place — sans reconstruction et sans intervention de Terraform :

# version logicielle
curl -X POST -H "Authorization: APIToken $TOKEN" -H 'Content-Type: application/json' \
  --data '{"version": "<software-version>"}' \
  "$API_URL/api/config/namespaces/system/sites/<site-name>/upgrade_sw"

# système d'exploitation
curl -X POST -H "Authorization: APIToken $TOKEN" -H 'Content-Type: application/json' \
  --data '{"version": "<os-version>"}' \
  "$API_URL/api/config/namespaces/system/sites/<site-name>/upgrade_os"

Observé le 2026-07-29 : l’appel logiciel a renvoyé 200, le site est passé à UPGRADING avec deployment_state.phase UPGRADE_IN_PROGRESS, et la version demandée dans l’objet site a été modifiée pour correspondre à celle soumise. Omettre le champ renvoie 400 avec version empty in the request, ce qui a permis de confirmer le nom du champ.

Prévoyez des heures, pas des minutes, et ne paniquez pas en cas d’échec. Sur un nœud avec disque par défaut, la mise à niveau vers crt-20260201-0179 a duré environ une heure, a signalé UPGRADE_FAILED avec result Failed à mi-parcours, puis s’est terminée avec succès sur la nouvelle version. La plateforme réessaie.

Cela a une conséquence directe pour quiconque surveille une mise à niveau ou en écrit le script : un résultat Failed est un état à attendre, pas un verdict. Le traiter comme définitif dès le premier signalement indique un échec pour une mise à niveau qui va réussir.

Notez le groupe dans ce chemin : ces endpoints se trouvent sous config, pas operate. Les mêmes chemins sous operate renvoient 404 API Group could not be determined, qui est un message de routage et non l’affirmation qu’il n’existe pas de mise à niveau — une distinction qui a conduit ce projet à une conclusion erronée.

Une mise à niveau via l'API désynchronise Terraform

Les variables épinglées indiquent toujours ce qu’elles ont toujours indiqué, de sorte que le site en production exécute désormais une version que la configuration ne mentionne pas. Terraform ne la reconciliera pas — il ne peut pas, puisque la mise à jour est rejetée — donc traitez une mise à niveau via l’API comme une étape délibérée hors du contrôle de Terraform, et mettez à jour les épingles pour correspondre lors de la prochaine reconstruction.

Deux affirmations antérieures de cette page, retirées

Cette page indiquait auparavant que faire passer un CE à une version différente implique de recréer le site, et qu’une mise à jour rejetée « efface quand même le champ sur le serveur », laissant Terraform proposer indéfiniment une modification vouée à l’échec. Aucune de ces affirmations n’a résisté aux tests : la mise à niveau via l’API ci-dessus démarre un changement de version en place, sans rien recréer, et après chacune des trois mises à jour rejetées, la spécification du site était inchangée et le site restait ONLINE. La divergence décrite dans le problème de fournisseur xcsh#1387 a été observée sur un site qui avait déjà effectué une mise à niveau automatique au-delà de son épingle, donc elle nécessite peut-être cet état de départ divergent ; elle n’a pas été reproduite sur un site dont la spécification correspondait à son épingle.

Si vous effectuez une reconstruction plutôt qu’une mise à niveau, toutes les conséquences du remplacement d’un CE s’appliquent.

Toutes les conséquences du remplacement d'un CE s'appliquent

Nouvelles clés d’hôte SSH, adresses internes réassignées, un nouvel enregistrement, et la perte de tout ce qui ne résidait que sur le nœud. Cloud-init s’exécute à nouveau sur la nouvelle VM, donc l’accès SSH configuré de cette façon survit — mais il ne s’exécute qu’au premier démarrage, donc tout ce qui a été ajouté manuellement à l’ancien nœud est perdu.

Lisez SSH sur les conséquences pour les clés d’hôte et les adresses avant de planifier cela.

Une version épinglée peut échouer à s’installer, et le site est alors bloqué

Accepter l’épingle n’est pas la même chose que l’installer. Sur un Customer Edge Azure Secure Mesh v2 à nœud unique fraîchement créé, épinglé à crt-20260201-0179, l’objet site a immédiatement signalé la version épinglée — puis l’installation a échoué :

site_state        PROVISIONING
phase             UPGRADE_FAILED
result            Failed
last_installed    (empty)
message           stage: 10, app: voucher obj: voucher objKind: DaemonSet failed ...
                  required replicas: 1, current replicas: 0

Observé le 2026-07-28, et reproduit deux fois le 2026-07-29. L’épingle du système d’exploitation s’est installée normalement lors du même déploiement (9.2024.6 vers 9.2026.14, UPGRADE_COMPLETED) ; seule l’installation logicielle a échoué. Le site n’a jamais atteint ONLINE et last_installed_version est resté vide, donc rien n’est revenu à une version fonctionnelle — il n’y avait pas d’installation réussie antérieure vers laquelle effectuer un retour arrière.

Un échec à la création n’est pas comme un échec lors d’une mise à niveau. Les deux se comportent différemment et la différence est importante quand vous décidez d’intervenir :

	à la création	lors d’une mise à niveau via l’API
réessaie-t-il jusqu’au succès ?	non — resté Failed pendant plus de 20 minutes, deux fois	oui — a récupéré et s’est terminé
où finit le nœud ?	PROVISIONING, rien d’installé	ONLINE sur une version fonctionnelle
est-il prudent de le laisser ?	non, il est bloqué	oui, il récupère ou conserve l’ancienne version

Donc un échec à la création nécessite une reconstruction avec un disque plus grand, tandis qu’une mise à niveau signalant Failed devrait être laissée un moment avant d’en tirer des conclusions.

La cause est le disque, pas la version. Une matrice logiciel × OS × taille de disque, un site Azure Secure Mesh v2 à nœud unique jetable par combinaison, tous issus de la même image marketplace, permet de l’isoler. Observé le 2026-07-29 :

logiciel	OS 9.2024.6 (ce que l’image embarque)	OS 9.2026.14
crt-20250613-3382	s’installe	s’installe
crt-20260201-0179	s’installe	échoue, sur le disque par défaut uniquement

Aucune version n’échoue seule. Seule la paire échoue, et uniquement sur le disque par défaut de l’image — la même paire s’installe sur 33 Go et sur toutes les tailles plus grandes testées. La version plus récente n’est donc pas non prise en charge ici, pas plus que le système d’exploitation plus récent ; ensemble, ils nécessitent légèrement plus de disque qu’un nœud par défaut.

terraform/modules/ce-node ne définit pas disk_size_gb, donc chaque Customer Edge obtient le disque par défaut de l’image — la seule taille sur laquelle cette paire échoue. Pour l’exécuter, agrandissez le disque.

La marge est la partie surprenante, et c’est pourquoi cela a longtemps ressemblé à un problème de version. Le disque par défaut est de 31 Gio (la commande health indique size_gb: 31, et /var fait 29 Go avec 3,5 Go libres sur un nœud en état d’échec). 33 Go s’installe proprement. Donc le disque par défaut est insuffisant d’environ deux gigaoctets, pas d’une large marge.

Ne définissez pas le minimum mesuré

33 Go est la plus petite taille observée comme fonctionnelle — pour cette paire de versions, sur cette image, aujourd’hui. Une version avec un contenu légèrement plus volumineux échouerait à nouveau à 33 Go sans aucun changement de configuration et sans cause évidente, exactement comme le disque par défaut le fait actuellement. Choisissez une marge au-dessus du minimum : les tailles vérifiées ici sont 33, 36, 40, 48 et 64 Go, et le coût des plus grandes représente quelques gigaoctets de disque géré.

Testez un changement de version sur un site jetable avant de l’appliquer à une flotte dans tous les cas : une flotte qui échoue de cette façon est bloquée en PROVISIONING avec la reconstruction comme seule issue.

Ne dimensionnez pas le disque à partir du chiffre F5 pré-mise à niveau

La vérification pré-mise à niveau documentée par F5 requiert 20 Go plus 15 % de capacité libre. Cette vérification conditionne les mises à niveau via l’interface Console et ne s’applique explicitement pas à celles initiées via l’API, donc elle ne décrit pas cet échec. Appliquée ici, elle prédit qu’un disque de 48 Go échouerait ; 48 Go s’installe proprement. Dimensionnez à partir des résultats mesurés ci-dessus, pas à partir de cette formule.

Une explication précédemment proposée sur cette page, désormais retirée

Une version antérieure de cette page suggérait que l’installation échouait parce que la version demandée était plus ancienne que celle de l’image — que le nœud était invité à revenir en arrière. C’est incorrect. Cette flotte a été créée à partir de la même image avec une épingle treize mois plus ancienne et s’est installée normalement, et crt-20260201-0179 s’installe également lorsque l’épingle OS est laissée à la version propre à l’image. Le sens du changement n’est pas la variable.

Quelle version la documentation décrit

La référence des commandes sur ce site décrit crt-20250613-3382, la version que cette flotte exécute. Les commandes qui n’existent que sur des versions plus récentes sont enregistrées dans sitecli/command-classification.json sous not_on_this_build et documentées séparément, dans commandes sur les versions plus récentes, de sorte que rien de ce qui s’y trouve n’apparaît comme exécutable ici. Voir également commandes embarquées.

Atteindre une version plus récente est résolu, et ce n'est pas une reconstruction

Cela était précédemment consigné ici comme non résolu, avec un rapport d’échec de la version plus récente sur des sites Azure Secure Mesh v2 à nœud unique, en contradiction avec l’observation d’un site l’exécutant. Les deux sont maintenant expliqués : la version plus récente s’installe sur cette topologie, et l’échec était dû à la limite de disque ci-dessus, pas à la version.

Il existe donc deux voies et aucune ne nécessite une reconstruction pour elle-même — créez un nœud avec un disque suffisamment grand, ou mettez à niveau un nœud existant via l’API. Observé le 2026-07-29.