Mettre à niveau le runtime de cluster à partir de Azure CLI

Cet article explique comment effectuer la mise à niveau du runtime pour un cluster Nexus d’opérateur.

Prerequisites

1. Installez la dernière version des extensions Azure CLI appropriées.
2. Accès par abonnement pour exécuter les commandes d’extension CLI de l’infrastructure réseau (NF) et du cloud réseau (NC) d'Azure Operator Nexus.
3. Collectez les informations suivantes :
   • ID d’abonnement (SUBSCRIPTION)
   • Nom du cluster (CLUSTER)
   • Groupe de ressources (CLUSTER_RG)
4. L’état détaillé du cluster doit être Running.
5. La connectivité de Cluster à Cluster Manager doit être Connected.
6. Azure prérequis (espace de travail Log Analytics, compte Storage, Key Vault) doivent être validés. Ces ressources sont vérifiées avant le début de la mise à niveau. Consultez l'identité managée du cluster et les ressources fournies par l'utilisateur.
7. Sous Cluster > Charge de travail > Serveur de calcul
   • Exigences d’intégrité du nœud du plan de contrôle avant la mise à niveau sont les suivantes :
     • S’il n’existe aucun nœud de plan de contrôle de rechange, tous les nœuds du plan de contrôle doivent être sains : état d’alimentation, Onétat RestrictionUncordoned, état Prêt Yes, état Dégradé No.
     • Si un nœud de plan de contrôle de secours existe, seul le nœud de secours peut être dans l’état d’alimentation Off, l’état Prêt No et l’état DégradéNo. Tous les autres nœuds du plan de contrôle doivent être sains : état d’alimentation On, statut de cordon Uncordoned, état Prêt Yes et Dégradé No.

     Note

     Si la machine de plan de contrôle de secours a déjà fait l’objet d’un processus de provisionnement, il est normal qu’elle soit à l’état Restriction Cordoned. Si ce n’est pas le cas, il doit être à l’état Restriction Uncordoned.

   • Les serveurs du plan de gestion sont divisés en deux groupes, disposés sur des racks numérotés impairs et pairs. Dans chaque groupe, plus de 50 % des serveurs doivent être en bon état : État de l’alimentation On, Statut de mise en réserve Uncordoned, État « Prêt » Yes et Dégradé No.
     • Dans les deux groupes de plans d’administration, au moins 75% des machines de gestion doivent être saines.
   • Les numéros de serveur du plan de calcul varient en fonction des paramètres de seuil d’exécution du cluster individuels. Les utilisateurs doivent déterminer leur nombre minimal en fonction de leurs paramètres, recherchant l'état d'alimentation On, l'état de cordon Uncordoned, l'état prêt Yes, et l'état dégradé No.
8. Sous Cluster > Managed Resource Group, sélectionnez le nom du groupe pour accéder à la page du groupe de ressources.
   • Dans le groupe de ressources, recherchez Kubernetes - Azure Arc pour identifier les informations Azure Arc et sélectionnez-la. L’état doit être Connected.
     • Dans la page Azure Arc, sélectionnez Paramètres > Extensions.
       • nc-platform-extension doit être dans l’état Succeeded.
       • nc-platform-runtime-extension doit être dans l’état Succeeded.

Vérification de la version d'exécution actuelle

Vérifiez la version actuelle du runtime du cluster avant la mise à niveau : découvrez comment vérifier la version actuelle du runtime du cluster.

Recherche des versions de runtime disponibles

Au moyen du portail Azure

Pour rechercher les versions d’exécution pouvant être mises à niveau disponibles, accédez au cluster cible dans le Azure portal. Dans le volet vue d’ensemble du cluster, accédez à l’onglet Versions de mise à niveau disponibles .

Sous l’onglet Versions de mise à niveau disponibles , vous pouvez voir les différentes versions de cluster disponibles pour la mise à niveau. Sélectionnez la version du runtime cible dans la liste, puis passez à la mise à niveau du cluster.

Via l’interface de ligne de commande Azure

Les mises à niveau disponibles sont récupérables via le Azure CLI :

az networkcloud cluster show --name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>" | grep -A8 availableUpgradeVersions

Dans la sortie, vous voyez la propriété availableUpgradeVersions et le champ targetClusterVersion :

  "availableUpgradeVersions": [
    {
      "controlImpact": "True",
      "expectedDuration": "Upgrades may take up to 4 hours + 2 hours per rack",
      "impactDescription": "Workloads will be disrupted during rack-by-rack upgrade",
      "supportExpiryDate": "2023-07-31",
      "targetClusterVersion": "3.3.0",
      "workloadImpact": "True"
    }
  ],

S’il n’existe aucune mise à niveau de cluster disponible, la liste est vide.

Configurer les paramètres de seuil de calcul pour la mise à niveau du runtime à l’aide du cluster updateStrategy

La commande Azure CLI suivante permet de configurer les paramètres de seuil de calcul pour une mise à niveau du runtime :

az networkcloud cluster update \
--name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>" \
--update-strategy strategy-type="<strategyType>" threshold-type="<thresholdType>" \
threshold-value="<thresholdValue>" max-unavailable="<maxNodesOffline>" \
wait-time-minutes="<waitTimeBetweenRacks>"

Paramètres obligatoires :

• strategy-type : définit la stratégie de mise à jour. Les paramètres utilisés sont Rack (Rack-by-Rack) OU PauseAfterRack (Pause pour l’utilisateur avant le démarrage de chaque rack). La valeur par défaut est Rack. Pour effectuer une mise à niveau du runtime de cluster à l’aide de la PauseAfterRack stratégie, suivez les étapes décrites dans Upgrade Cluster Runtime with PauseAfterRack Strategy.
• threshold-type : détermine la façon dont le seuil doit être évalué, appliqué dans les unités définies par la stratégie. Les paramètres utilisés sont PercentSuccess OR CountSuccess. La valeur par défaut est PercentSuccess.
• threshold-value : valeur de seuil numérique utilisée pour évaluer une mise à jour. La valeur par défaut est 80.

Paramètres facultatifs :

• max-unavailable : nombre maximal de nœuds Worker pouvant être hors connexion, c’est-à-dire en cours de mise à niveau sur un rack simultanément. La valeur par défaut est 32767.
• wait-time-minutes : délai ou période d’attente avant la mise à jour d’un rack. La valeur par défaut est 15.

Comportement de mise à jour basé sur le type de seuil PercentSuccess

L’exemple suivant est destiné à un client utilisant la stratégie Rack-by-Rack avec un pourcentage de réussite de 60% et une pause de 1 minute.

az networkcloud cluster update --name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--update-strategy strategy-type="Rack" threshold-type="PercentSuccess" \
threshold-value=60 wait-time-minutes=1 \
--subscription "<SUBSCRIPTION>"

Vérifiez la mise à jour :

az networkcloud cluster show --name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>" | grep -A5 updateStrategy

  "updateStrategy": {
    "maxUnavailable": 32767,
      "strategyType": "Rack",
      "thresholdType": "PercentSuccess",
      "thresholdValue": 60,
      "waitTimeMinutes": 1

Dans cet exemple, une fois 60% des machines d’un rack sont correctement mises à niveau, le système considère le seuil atteint et passe à la mise à niveau du rack suivant, tout en continuant à approvisionner les machines restantes dans le rack actuel. Si le seuil n’est pas atteint, c’est-à-dire que moins de 60 % des machines du rack ont pu être mises à niveau, les autres ayant échoué, alors la mise à niveau du cluster est mise en pause. Lorsqu’une mise à niveau est suspendue, le système fournit un message d’état détaillé sur le cluster expliquant la raison. À ce stade, les machines problématiques du rack doivent être réparées, et une opération continue de mise à jour du cluster doit être déclenchée pour reprendre et terminer la mise à niveau.

Pour afficher l’état de mise à niveau via le Azure portal, accédez à la ressource de cluster ciblée. Dans l’écran Vue d’ensemble du cluster, l’état détaillé est fourni avec un message d’état détaillé.

La mise à niveau du cluster est en cours quand detailedStatus est défini sur Updating et detailedStatusMessage montre la progression de la mise à niveau. Exemples de progression de mise à niveau indiquée dans detailedStatusMessage : Waiting for control plane upgrade to complete..., Waiting for nodepool "<rack-id>" to finish upgrading..., etc.

La mise à niveau du cluster est terminée quand detailedStatus est défini sur Running et detailedStatusMessage affiche le message Cluster is up and running

Si le message d’état détaillé indique que la mise à niveau est suspendue, le message s’affiche comme suit : Cluster is deployed but the upgrade has been paused. Machines in rack "<rack-id>" are unhealthy. Fix the machines and perform cluster continue-update-version action to finish the upgrade

Pour reprendre la mise à niveau du runtime, exécutez la commande az networkcloud cli suivante.

az networkcloud cluster continue-update-version --cluster-name "<CLUSTER>" \
--resource-group="<CLUSTER_RG>" \
--subscription="<SUBSCRIPTION>" \
--safeguard-mode <SAFEGUARD_MODE>

Paramètres facultatifs :

• --safeguard-mode : spécifie la façon dont les mécanismes de sécurité sont appliqués lors de l’opération continue-update-version. Utilisez All pour exécuter toutes les vérifications de validation préalables à l’exécution. Permet None de contourner les mesures de protection qui bloquent la mise à niveau lorsqu’elles détectent des problèmes. La valeur par défaut est All.

Comportement de mise à niveau basé sur le type de seuil CountSuccess

L’exemple suivant est destiné à un client utilisant la stratégie Rack-by-Rack avec un type CountSuccess de seuil de 10 nœuds par rack et une pause de 1 minute.

az networkcloud cluster update --name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--update-strategy strategy-type="Rack" threshold-type="CountSuccess" \
threshold-value=10 wait-time-minutes=1 \
--subscription "<SUBSCRIPTION>"

Vérifiez la mise à jour :

az networkcloud cluster show --name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>" | grep -A5 updateStrategy

  "updateStrategy": {
    "maxUnavailable": 32767,
      "strategyType": "Rack",
      "thresholdType": "CountSuccess",
      "thresholdValue": 10,
      "waitTimeMinutes": 1

Dans cet exemple, si au moins 10 nœuds sont correctement mis à niveau, la mise à niveau passe au rack suivant tout en continuant à provisionner les machines restantes dans le rack actuel. Si au moins 10 machines du rack ne parviennent pas à mettre à niveau, la mise à niveau du cluster s’interrompt. Lorsque cela se produit, le matériel requis doit être réparé avant d’exécuter l’action continue-update-version pour reprendre et terminer la mise à niveau.

Pour résoudre les problèmes liés aux machines bare metal, reportez-vous à Déboguer les problèmes du serveur Azure Operator Nexus

Validations qui peuvent bloquer la mise à niveau du runtime du cluster

Lorsque vous déclenchez une mise à niveau du runtime de cluster, le processus exécute une série de validations de prégradation avant le démarrage de la mise à niveau du runtime sur les machines nues du cluster. Ces validations confirment que la mise à niveau du runtime peut réussir en fonction de l’état actuel du cluster. Pour plus d’informations, consultez Vérifications préalables de la mise à niveau du runtime du cluster.

Mettre à niveau le runtime de cluster à l’aide de l’interface CLI

Pour mettre à niveau la version du runtime du cluster, utilisez la commande Azure CLI suivante :

az networkcloud cluster update-version\
--cluster-name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>" \
--target-cluster-version "<versionNumber>" \
--safeguard-mode "<SAFEGUARD_MODE>"

Paramètres obligatoires :

• --target-cluster-version: version à appliquer au cluster pendant la mise à jour.

Paramètres facultatifs :

• --safeguard-mode: spécifie la façon dont les protections sont appliquées pendant l’opération de version de mise à jour. Utilisez All pour exécuter toutes les vérifications de validation préalables à l’exécution. Permet None de contourner les mesures de protection qui bloquent la mise à niveau lorsqu’elles détectent des problèmes. La valeur par défaut est All.

Cette commande lance le processus de mise à niveau du runtime pour le cluster spécifié. La commande elle-même se termine généralement dans environ cinq minutes, mais elle démarre uniquement le processus de mise à niveau une fois les validations réussies. La mise à niveau réelle du runtime continue à s’exécuter en arrière-plan et peut prendre plusieurs heures, car elle met à niveau les nœuds rack par rack et installe la nouvelle version du système d’exploitation.

Des informations détaillées sur l’état et le diagnostic de l’étape d’initiation sont disponibles dans Azure portal dans la ressource JSON View de la ressource Cluster (Opérateur Nexus). Les informations suivantes sont incluses dans l’entrée updateVersion du champ properties.actionStates, lors de l’utilisation de la version 2025-07-01-preview de l’API ou ultérieure.

• Heure de début et de fin de l’action.
• État actuel (Succeeded, Failedou InProgress).
• Tout contexte ou message d’erreur supplémentaire associé à l’état actuel.
• ID de corrélation de l’opération cluster update-version d’origine, comme indiqué dans le journal d’activité Azure.
• Liste triée des étapes individuelles et de leur état , par exemple Validate Cluster conditions and upgrade versions, et Initiate Platform Runtime Extension update.

Exemple de résultat JSON View pour la ressource Cluster (Opérateur Nexus) :

{
  "properties": {
    "actionStates": [
      {
        "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
        "status": "Completed",
        "actionType": "Microsoft.NetworkCloud/clusters/updateVersion",
        "endTime": "2025-08-01T03:46:13Z",
        "message": "Cluster upgrade to 4.6.0 successfully initiated - monitor progress via cluster detailed status",
        "startTime": "2025-08-01T03:42:08Z",
        "stepStates": [
          {
            "status": "Completed",
            "endTime": "2025-08-01T03:42:08Z",
            "message": "Cluster validation and version checks passed",
            "startTime": "2025-08-01T03:42:08Z",
            "stepName": "Validate Cluster conditions and upgrade versions"
          },
          {
            "status": "Completed",
            "endTime": "2025-08-01T03:46:11Z",
            "message": "Platform Runtime Extension deployment initiated",
            "startTime": "2025-08-01T03:42:39Z",
            "stepName": "Initiate Platform Runtime Extension update"
          },
          {
            "status": "Completed",
            "endTime": "2025-08-01T03:46:11Z",
            "message": "Platform Runtime Extension installation completed",
            "startTime": "2025-08-01T03:46:11Z",
            "stepName": "Monitor Platform Runtime Extension readiness"
          },
          {
            "status": "Completed",
            "endTime": "2025-08-01T03:46:13Z",
            "message": "Platform Cluster version updated successfully",
            "startTime": "2025-08-01T03:46:13Z",
            "stepName": "Update Platform Cluster version specification"
          }
        ]
      }
    ]
  }
}

Une fois cette commande terminée, le processus de mise à niveau du runtime complet commence. Ce processus peut prendre plusieurs heures, en fonction du nombre de racks dans le cluster et du nombre de nœuds de calcul de chaque rack.

• La mise à niveau commence par mettre à niveau les nœuds du plan de contrôle, puis les nœuds de gestion, puis successivement, baie par baie, les nœuds de travail.
• Les serveurs d’administration sont séparés en deux groupes, qui sont mis à niveau séparément. Cette approche permet aux composants s’exécutant sur les serveurs d’administration de garantir la résilience pendant la mise à niveau du runtime en appliquant des règles d’affinité.
• Les réseaux de services cloud utilisent également cette fonctionnalité en plaçant une instance dans chaque groupe d’administration.
• Il n’existe aucune interaction client avec cette fonctionnalité. Toutefois, il peut y avoir d’autres étiquettes visibles sur les nœuds de gestion pour identifier les groupes.

La mise à niveau est considérée comme terminée lorsque les seuils configurés par le updateStrategy du cluster pour les racks de nœuds de travail sont atteints et qu’au moins 50 % des nœuds de gestion de chaque groupe ont été mis à niveau avec succès. Les charges de travail peuvent être affectées lors de la mise à niveau des nœuds Worker d’un rack, mais les charges de travail de tous les autres racks ne sont pas affectées. Nous vous encourageons à placer les charges de travail en fonction de cette conception d’implémentation.

Surveillez la progression à l'aide de l'état détaillé du cluster, disponible via le portail Azure ou Azure CLI.

Pour afficher l’état de mise à niveau via le Azure CLI, utilisez az networkcloud cluster show.

az networkcloud cluster show --cluster-name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>"

La sortie inclut les informations du cluster cible, ainsi que son état détaillé et son message d’état détaillé. Pour obtenir des informations plus détaillées sur la progression de la mise à niveau, les nœuds individuels de chaque rack peuvent être vérifiés pour obtenir l’état. Un exemple est fourni dans la section de référence sous Rôles BareMetal Machine.

Pour afficher l’état de mise à niveau via le portail Azure, accédez à la ressource de cluster ciblée. Dans l’écran Vue d’ensemble du cluster, vous pouvez afficher l’état détaillé avec un message d’état détaillé.

La mise à niveau du cluster est en cours lorsque detailedStatus est défini sur Updating et detailedStatusMessage indique la progression de la mise à niveau. Voici quelques exemples de progression de mise à niveau affichés dans detailedStatusMessage : Waiting for control plane upgrade to complete... et Waiting for nodepool "<rack-id>" to finish upgrading....

La mise à niveau du cluster est terminée lorsque detailedStatus est défini sur Running et que detailedStatusMessage affiche Cluster is up and running.

La mise à niveau du cluster est suspendue lorsque detailedStatus est défini sur Updating et detailedStatusMessage indique la raison ou le composant qui a provoqué la suspension de la mise à niveau.

Mise à niveau suspendue de l’environnement d’exécution du cluster

La mise à niveau s’interrompt quand l’une des opérations suivantes se produit :

1. Toutes les machines du plan de contrôle ne peuvent pas être correctement mises à niveau et ne sont pas configurées et prêtes.
2. Plus de 50 % des machines d’un groupe du plan de gestion ne peuvent pas être mises à niveau et ne sont pas provisionnées ni prêtes. Les serveurs du plan de gestion sont divisés en deux groupes, disposés sur des racks numérotés impairs et pairs.
3. Les machines de nœud de calcul ou de nœud de travail configurées selon un seuil ne peuvent pas être mises à niveau et ne sont ni provisionnées ni prêtes.

Examinez le message d’état détaillé du cluster pour identifier le composant ayant provoqué le passage de la mise à niveau à l’état suspendu. Les exemples ci-dessous montrent des messages d’état détaillés pour chaque composant.

Message d’état détaillé de la défaillance du plan de contrôle (KCP)

• « Le cluster est déployé, mais la mise à niveau a été suspendue. La mise à niveau du plan de contrôle a échoué, car le capiCluster <clusterName> n’est pas en bon état. MachineHealthCheck peut échanger des machines KCP non saines avec des machines du plan de gestion pour restaurer le quorum. Attendez la fin de la correction, puis exécutez l’action continue-update-version pour terminer la mise à niveau. »

Message d’état détaillé de défaillance du groupe du plan de calcul ou de gestion

• « Le cluster est déployé, mais la mise à niveau a été suspendue. Les machines dans le rack «<rack-id>» sont en mauvais état. Réparez les machines et exécutez l’action continue-update-version sur le cluster pour terminer la mise à niveau.

Une fois que le composant concerné (plan de contrôle, gestion ou calcul) est identifié, procédez comme suit :

Étape 1 : Vérifiez l’état des machines bare metal individuelles pour le composant concerné.

Un exemple est fourni dans la section de référence sous Rôles BareMetal Machine.

Après avoir identifié les machines nues pour le composant concerné, vérifiez l’état de chaque machine et effectuez les actions suivantes en fonction de son état.

Étape 2 : Vérifiez les journaux d’état des actions pour le BMM.

Pour vérifier les journaux d’état des actions d’un BMM, accédez à la ressource BMM >Opérations>Journal des actions.

Une fois le problème résolu et que la machine Baremetal est configurée et prête, exécutez l’action de cluster continue-update-version pour reprendre et terminer la mise à niveau.

az networkcloud cluster continue-update-version \
-g <CLUSTER_RG> \
-n <CLUSTER_NAME> \
--subscription <CUSTOMER_SUB_ID> \
--safeguard-mode <SAFEGUARD_MODE>

Paramètres facultatifs :

• --safeguard-mode : spécifie la façon dont les mécanismes de sécurité sont appliqués lors de l’opération continue-update-version. Utilisez All pour exécuter toutes les vérifications de validation préalables à l’exécution. Permet None de contourner les mesures de protection qui bloquent la mise à niveau lorsqu’elles détectent des problèmes. La valeur par défaut est All.

Questions fréquentes

Identification du blocage ou de l'arrêt de la mise à niveau du cluster

Pendant une mise à niveau du runtime, le cluster entre dans un état suspendu une fois que le processus de mise à niveau détermine que la mise à niveau ne peut pas continuer sans intervention manuelle. Toutefois, le processus de mise à niveau peut parfois échouer alors que l’état détaillé reflète toujours la mise à niveau en cours. Étant donné que la mise à niveau du runtime peut prendre beaucoup de temps pour se terminer, il n’y a pas de délai d’expiration défini actuellement spécifié. Vérifiez régulièrement l’état détaillé et les journaux de votre cluster pour déterminer si votre mise à niveau reste indéfiniment en tentative de mise à niveau.

Vous pouvez identifier une mise à niveau indéfiniment bloquée en examinant les journaux du cluster, les messages détaillés et le message d’état détaillé. Si cette condition se produit, vous constatez que le cluster effectue en continu la réconciliation du même état sans progresser. Vérifiez les journaux du cluster ou l’espace de travail Log Analytics (LAW) configuré afin de déterminer s’il y a un échec ou une étape spécifique à l’origine de l’absence de progression.

Identification de la mise à niveau de machine nue bloquée

Un guide permettant d’identifier les problèmes de provisionnement des nœuds de travail est fourni dans Troubleshooting Bare Metal Machine Provisioning.

Une défaillance matérielle ne nécessite pas la réexécution de la mise à niveau

Si une panne matérielle se produit pendant une mise à niveau, la mise à niveau d'exécution se poursuit tant que les seuils définis sont respectés pour les nœuds de calcul et de gestion/contrôle. Une fois la machine corrigée ou remplacée, elle est provisionnée avec le système d'exploitation du runtime de la plateforme actuelle, qui contient la version cible du runtime. Si un rack a été mis à jour avant une défaillance, la version du runtime mis à niveau est utilisée quand les nœuds sont reprovisionnés. Si la spécification du rack n’a pas été mise à jour vers la version du runtime mise à niveau avant la défaillance matérielle, la machine provisionne avec la version précédente du runtime lorsque le matériel est réparé. La machine est mise à niveau avec le rack lorsque le rack démarre sa mise à niveau.

Après une mise à niveau du runtime, le cluster affiche l’état d’approvisionnement « Échec »

Pendant une mise à niveau du temps d'exécution, le cluster entre dans l’étatUpgrading. Si la mise à niveau du runtime échoue, le cluster passe à un état d’approvisionnement Failed . Les composants d’infrastructure (par exemple, l’appliance de stockage) peuvent entraîner des défaillances pendant la mise à niveau. Dans certains cas, il peut être nécessaire de diagnostiquer la défaillance avec le support Microsoft.

Bare Metal Machine est en état dégradé après la mise à jour de l'environnement d'exécution.

Certaines situations peuvent amener un nœud à revenir à l’état Degraded. Cet état se produit si l’une des conditions décrites dans Résoudre les erreurs liées à l’état dégradé est remplie. L’état détérioré signifie que le nœud est automatiquement cordonné pour empêcher la planification de nouvelles charges de travail sur le nœud jusqu’à ce que le problème sous-jacent soit résolu.