Aggiornare il runtime del cluster da interfaccia della riga di comando di Azure

Questo articolo illustra come eseguire l'aggiornamento di runtime per un cluster Operator Nexus.

Prerequisiti

1. Installare la versione più recente delle estensioni dell'interfaccia della riga di comando appropriate.
2. Accesso alla sottoscrizione per eseguire i comandi dell'estensione CLI di network fabric (NF) e network cloud (NC) per Operatore Nexus di Azure.
3. Raccogliere le informazioni seguenti:
   • ID sottoscrizione (SUBSCRIPTION)
   • Il nome del cluster (CLUSTER)
   • Gruppo di risorse (CLUSTER_RG)
4. Lo stato dettagliato del cluster deve essere Running.
5. La connettività tra il cluster e il Cluster Manager deve essere Connected.
6. I prerequisiti di Azure (area di lavoro di Log Analytics, account di archiviazione, Key Vault) devono essere verificati e convalidati. Queste risorse vengono controllate prima dell'inizio dell'aggiornamento. Vedere Identità gestita del cluster e risorse fornite dall'utente.
7. Sotto Cluster > Workload > Server di calcolo
   • I requisiti di integrità dei nodi del piano di controllo prima dell'aggiornamento sono:
     • Se non esiste alcun nodo del piano di controllo di riserva, tutti i nodi del piano di controllo devono essere integri: stato di alimentazione On, stato Cordon Uncordoned, stato Ready Yes e Degradato No.
     • Se esiste un nodo di riserva del piano di controllo, solo il nodo di riserva può trovarsi nello stato Power Off, nello stato Ready No e in stato Degraded No. Ogni altro nodo del piano di controllo deve essere integro: stato di alimentazione On, stato di Cordon Uncordoned, stato Ready Yes e Degraded No.

     Annotazioni

     Se la macchina del piano di controllo di riserva ha già completato un processo di provisioning, è previsto che si trovi nello stato Cordon Cordoned. In caso contrario, dovrebbe essere nello stato UncordonedCordon.

   • I server del piano di controllo sono suddivisi in due gruppi su rack con numeri dispari e pari. In ogni gruppo, più del 50% dei server deve essere integro: stato di alimentazione On, stato Cordon Uncordoned, stato Pronto Yes e stato Degradato No.
     • In entrambi i gruppi del piano di gestione, almeno 75% dei computer di gestione devono essere integri.
   • I numeri del server del piano di calcolo variano in base alle singole impostazioni della soglia di runtime del cluster. I clienti devono determinare il numero minimo in base alle impostazioni, cercando lo stato di alimentazione On, lo stato Cordon Uncordoned, lo stato Pronto Yes e lo stato Degradato No.
8. Selezionare il nome del gruppo in Gruppo di risorse gestite del cluster > per accedere alla pagina del gruppo di risorse.
   • Nel gruppo di risorse, cercare Kubernetes - Azure Arc per identificare le informazioni di Azure Arc e selezionarle. Lo stato deve essere Connected.
     • Nella pagina Azure Arc selezionare Impostazioni > Estensioni.
       • nc-platform-extension deve essere nello stato Succeeded.
       • nc-platform-runtime-extension deve essere nello stato Succeeded.

Verifica della versione di runtime corrente

Verificare la versione corrente del runtime del cluster prima dell'aggiornamento: vedere Come controllare la versione corrente del runtime del cluster.

Ricerca delle versioni di runtime disponibili

Tramite il portale di Azure

Per trovare le versioni di runtime aggiornabili disponibili, passare al cluster di destinazione nella Azure portal. Nel riquadro Panoramica del cluster passare alla scheda Versioni di aggiornamento disponibili .

Nella scheda Versioni di aggiornamento disponibili è possibile visualizzare le diverse versioni del cluster disponibili per l'aggiornamento. Selezionare la versione del runtime di destinazione dall'elenco e quindi procedere con l'aggiornamento del cluster.

Tramite interfaccia della riga di comando di Azure

Gli aggiornamenti disponibili sono recuperabili tramite il interfaccia della riga di comando di Azure:

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

Nell'output è possibile trovare la proprietà availableUpgradeVersions ed esaminare il campo 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"
    }
  ],

Se non sono presenti aggiornamenti del cluster disponibili, l'elenco è vuoto.

Configurare i parametri della soglia di calcolo per l'aggiornamento del runtime tramite cluster updateStrategy

Il comando interfaccia della riga di comando di Azure seguente viene usato per configurare i parametri della soglia di calcolo per un aggiornamento di 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>"

Parametri obbligatori:

• strategy-type: definisce la strategia di aggiornamento. Le impostazioni usate sono Rack (Rack-by-Rack) OR PauseAfterRack (Pausa per l'utente prima dell'avvio di ogni rack). Il valore predefinito è Rack. Per eseguire un aggiornamento del runtime del cluster usando la PauseAfterRack strategia, seguire i passaggi descritti in Aggiornare il runtime del cluster con la strategia PauseAfterRack.
• threshold-type: determina la modalità di valutazione della soglia, applicata nelle unità definite dalla strategia. Le impostazioni usate sono PercentSuccess OR CountSuccess. Il valore predefinito è PercentSuccess.
• threshold-value: valore soglia numerico usato per valutare un aggiornamento. Il valore predefinito è 80.

Parametri facoltativi:

• max-unavailable: numero massimo di nodi di lavoro che possono essere offline, ovvero un rack aggiornato alla volta. Il valore predefinito è 32767.
• wait-time-minutes: il ritardo o il periodo di attesa prima di aggiornare un rack. Il valore predefinito è 15.

Comportamento di aggiornamento basato sul tipo di soglia Percentuale di Successo

L'esempio seguente è destinato a un cliente che usa la strategia Rack-by-Rack con percentuale di successo pari a 60% e una pausa di 1 minuto.

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>"

Verificare l'aggiornamento:

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

In questo esempio, una volta che 60% dei computer in un rack vengono aggiornati correttamente, il sistema considera la soglia raggiunta e procede per aggiornare il rack successivo, continuando a eseguire il provisioning di eventuali computer rimanenti nel rack corrente. Se la soglia non viene raggiunta, vale a dire meno di 60% dei computer nel rack sono stati in grado di eseguire l'aggiornamento e invece non è riuscito, l'aggiornamento del cluster viene sospeso. Quando un aggiornamento viene sospeso, il sistema fornisce un messaggio di stato dettagliato nel cluster che spiega il motivo. A questo punto, i computer problematici nel rack devono essere riparati e un'operazione di aggiornamento continuo del cluster deve essere attivata per riprendere e completare l'aggiornamento.

Per visualizzare lo stato dell'aggiornamento tramite il Azure portal, passare alla risorsa cluster di destinazione. Nella schermata Panoramica del cluster viene fornito lo stato dettagliato insieme a un messaggio di stato dettagliato.

L'aggiornamento del cluster è in corso quando detailedStatus è impostato su Updating e detailedStatusMessage mostra lo stato di avanzamento dell'aggiornamento. Alcuni esempi di avanzamento dell'aggiornamento illustrati in detailedStatusMessage sono Waiting for control plane upgrade to complete..., Waiting for nodepool "<rack-id>" to finish upgrading... e così via.

L'aggiornamento del cluster è completo quando detailedStatus è impostato su Running e detailedStatusMessage mostra il messaggio Cluster is up and running

Se il messaggio di stato dettagliato indica che l'aggiornamento è in pausa, il messaggio sarà simile al seguente: 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

Per riprendere l'aggiornamento del runtime, eseguire il comando az networkcloud cli seguente.

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

Parametri facoltativi:

• --safeguard-mode: specifica la modalità di applicazione delle misure di sicurezza durante l'operazione continue-update-version. Usare All per eseguire tutti i controlli di convalida della preoperazione. Usare None per ignorare le misure di sicurezza che bloccano l'aggiornamento quando rilevano problemi. Il valore predefinito è All.

Comportamento di aggiornamento basato sulla soglia di tipo CountSuccess

L'esempio seguente è destinato a un cliente che usa la strategia Rack-by-Rack con un tipo di CountSuccess soglia di 10 nodi per rack e una pausa di 1 minuto.

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>"

Verificare l'aggiornamento:

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

In questo esempio, se almeno 10 nodi vengono aggiornati correttamente, l'aggiornamento passa al rack successivo continuando a eseguire il provisioning di tutti i computer rimanenti nel rack corrente. Se almeno 10 computer nel rack non riescono ad eseguire l'aggiornamento, l'aggiornamento del cluster viene sospeso. In questo caso, è necessario ripristinare l'hardware necessario prima di eseguire l'azione continue-update-version per riprendere e completare l'aggiornamento.

Per la risoluzione dei problemi relativi ai computer bare metal, vedere Risoluzione dei problemi del server Operatore Nexus di Azure

Convalide che possono bloccare l'aggiornamento del runtime del cluster

Quando si attiva un aggiornamento di runtime del cluster, il processo esegue una serie di convalide di preupgradazione prima dell'avvio dell'aggiornamento di runtime nei computer bare metal del cluster. Queste convalide confermano che l'aggiornamento del runtime può avere esito positivo in base allo stato corrente del cluster. Per altre informazioni, vedere Convalida preliminare dell'aggiornamento del runtime del cluster.

Aggiornare il runtime del cluster tramite l'interfaccia della riga di comando

Per aggiornare la versione del runtime del cluster, usare il comando interfaccia della riga di comando di Azure seguente:

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

Parametri obbligatori:

• --target-cluster-version: versione da applicare al cluster durante l'aggiornamento.

Parametri facoltativi:

• --safeguard-mode: specifica la modalità di applicazione delle misure di sicurezza durante l'operazione di aggiornamento della versione. Usare All per eseguire tutti i controlli di convalida della preoperazione. Usare None per ignorare le misure di sicurezza che bloccano l'aggiornamento quando rilevano problemi. Il valore predefinito è All.

Questo comando avvia il processo di aggiornamento del runtime per il cluster specificato. Il comando stesso termina in genere entro circa cinque minuti, ma avvia il processo di aggiornamento solo dopo che le convalide hanno esito positivo. L'aggiornamento di runtime effettivo continua a essere eseguito in background e può richiedere diverse ore, perché aggiorna i nodi rack per rack e installa la nuova versione del sistema operativo.

Lo stato dettagliato e le informazioni di diagnostica per il passaggio di avvio sono disponibili in Azure portal nella risorsa JSON View della risorsa Cluster (Operator Nexus). Le informazioni seguenti sono incluse nella updateVersion voce del properties.actionStates campo, quando si usa la versione 2025-07-01-preview API o versione successiva.

• Ora di inizio e fine dell'azione.
• Stato corrente (Succeeded, Failedo InProgress).
• Qualsiasi contesto o messaggio di errore aggiuntivo associato allo stato corrente.
• ID di correlazione per l'operazione originale cluster update-version, come illustrato anche nel log delle attività di Azure.
• Elenco ordinato di singoli passaggi e relativo stato, ad esempio Validate Cluster conditions and upgrade versions, e Initiate Platform Runtime Extension update.

Output di esempio JSON View per la risorsa Cluster (Operator 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"
          }
        ]
      }
    ]
  }
}

Al termine di questo comando, viene avviato il processo di aggiornamento completo del runtime. Il completamento di questo processo può richiedere diverse ore, a seconda del numero di rack nel cluster e del numero di nodi di lavoro in ogni rack.

• L'aggiornamento interessa prima i nodi del piano di controllo, quindi i nodi di gestione e infine i nodi worker, in sequenza, un rack alla volta.
• I server di gestione sono separati in due gruppi, che vengono aggiornati separatamente. Questo approccio consente ai componenti in esecuzione nei server di gestione di garantire la resilienza durante l'aggiornamento di runtime applicando regole di affinità.
• Le reti di servizi cloud usano anche questa funzionalità inserendo un'istanza in ogni gruppo di gestione.
• Non esiste alcuna interazione del cliente con questa funzionalità. Tuttavia, potrebbero essere presenti altre etichette nei nodi di gestione per identificare i gruppi.

L'aggiornamento viene considerato completato quando vengono soddisfatte le soglie configurate dal cluster per i rack dei updateStrategy nodi di lavoro e almeno 50% dei nodi di gestione in ogni gruppo vengono aggiornati correttamente. I carichi di lavoro potrebbero essere interessati durante l'aggiornamento dei nodi di lavoro in un rack, ma i carichi di lavoro in tutti gli altri rack non sono interessati. È consigliabile considerare il posizionamento del carico di lavoro alla luce di questa progettazione di implementazione.

Monitorare lo stato di avanzamento usando lo stato dettagliato del cluster, disponibile tramite il portale di Azure o interfaccia della riga di comando di Azure.

Per visualizzare lo stato di aggiornamento tramite il interfaccia della riga di comando di Azure, usare az networkcloud cluster show.

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

L'output include le informazioni del cluster di destinazione insieme al relativo stato dettagliato e al messaggio di stato dettagliato. Per informazioni più dettagliate sull'avanzamento dell'aggiornamento, è possibile verificare lo stato dei singoli nodi in ogni rack. Un esempio è riportato nella sezione di riferimento alla voce Ruoli delle macchine BareMetal.

Per visualizzare lo stato di aggiornamento tramite il portale di Azure, passare alla risorsa cluster di destinazione. Nella schermata Panoramica del cluster è possibile visualizzare lo stato dettagliato insieme a un messaggio di stato dettagliato.

L'aggiornamento del cluster è in corso quando detailedStatus è impostato su Updating e detailedStatusMessage mostra lo stato di avanzamento dell'aggiornamento. Alcuni esempi di avanzamento dell'aggiornamento illustrati in detailedStatusMessage sono Waiting for control plane upgrade to complete... e Waiting for nodepool "<rack-id>" to finish upgrading....

L'aggiornamento del cluster è completo quando detailedStatus è impostato su Running e detailedStatusMessage mostra Cluster is up and running.

L'aggiornamento del cluster viene sospeso quando detailedStatus è impostato su Updating e detailedStatusMessage mostra il motivo o il componente che ha causato la sospensione dell'aggiornamento.

Aggiornamento del runtime del cluster sospeso

L'aggiornamento viene sospeso quando si verifica una delle operazioni seguenti:

1. Non è possibile aggiornare tutti i computer del piano di controllo e non è stato effettuato il provisioning e non sono pronti.
2. Non è possibile aggiornare più di 50% dei computer in un gruppo del piano di gestione e non è stato effettuato il provisioning e non sono pronti. I server del piano di controllo sono suddivisi in due gruppi su rack con numeri dispari e pari.
3. Le macchine dei nodi di calcolo o di lavoro configurate in base alla soglia non possono essere aggiornate e non sono provisionate né pronte.

Esaminare il messaggio di stato dettagliato del cluster per identificare il componente che ha causato l'aggiornamento in uno stato sospeso. Gli esempi seguenti mostrano messaggi di stato dettagliati per ogni componente.

Messaggio di stato dettagliato dell'errore del piano di controllo (KCP)

• "Il cluster viene distribuito ma l'aggiornamento è stato sospeso. L'aggiornamento del piano di controllo non è riuscito perché capiCluster <clusterName> non è sano. MachineHealthCheck potrebbe scambiare computer KCP non integri con computer del piano di gestione per ripristinare il quorum. Attendere il completamento della correzione, quindi eseguire l'azione continue-update-version per completare l'aggiornamento."

Messaggio di stato dettagliato relativo all'errore del gruppo del piano di calcolo o di gestione

• "Il cluster viene distribuito ma l'aggiornamento è stato sospeso. Le macchine nel rack "<rack-id>" non sono in buono stato. Riparare le macchine ed eseguire l'azione del cluster "continue-update-version" per completare l'upgrade.

Dopo aver identificato il componente interessato (piano di controllo, gestione o calcolo), eseguire le operazioni seguenti:

Passaggio 1: Controllare lo stato delle singole macchine bare metal relative al componente interessato.

Un esempio è riportato nella sezione di riferimento, alla voce Ruoli della macchina BareMetal.

Dopo aver identificato le macchine bare metal per il componente interessato, controllare lo stato di ogni macchina ed eseguire le azioni seguenti in base al suo stato.

Passaggio 2: Controllare i log di stato dell'azione per BMM.

Per controllare i log dello stato delle azioni per un BMM, passare alla risorsa BMM >Operazioni>Log azioni.

Dopo aver risolto il problema e quando la macchina Baremetal è stata sottoposta a provisioning ed è pronta, eseguire l'azione continue-update-version del cluster per riprendere e completare l'aggiornamento.

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

Parametri facoltativi:

• --safeguard-mode: specifica la modalità di applicazione delle misure di sicurezza durante l'operazione continue-update-version. Usare All per eseguire tutti i controlli di convalida della preoperazione. Usare None per ignorare le misure di sicurezza che bloccano l'aggiornamento quando rilevano problemi. Il valore predefinito è All.

Domande frequenti

Identificazione dell'aggiornamento del cluster In stallo/bloccato

Durante un aggiornamento di runtime, il cluster entra in uno stato sospeso dopo che il processo di aggiornamento determina che l'aggiornamento non può continuare senza intervento manuale. Tuttavia, il processo di aggiornamento potrebbe talvolta non riuscire a spostarsi in avanti mentre lo stato dettagliato riflette ancora l'aggiornamento come in corso. Poiché l'aggiornamento del runtime può richiedere molto tempo per completare correttamente, non è attualmente specificata alcuna lunghezza di timeout impostata. Controlla periodicamente lo stato dettagliato e i log del cluster per determinare se l'aggiornamento sta tentando di completarsi all'infinito.

È possibile identificare un aggiornamento bloccato a tempo indeterminato esaminando i log del cluster, un messaggio dettagliato e un messaggio di stato dettagliato. Se questa condizione si verifica, si osserva che il cluster si riconcilia continuamente con lo stesso stato senza procedere. Controllare i log del cluster o l'area di lavoro di Log Analytics (LAW) configurata per vedere se si è verificato un errore o se un passaggio specifico sta causando il mancato avanzamento.

Identificazione dell'aggiornamento della macchina fisica bloccato/in stallo

Una guida per identificare i problemi relativi al provisioning dei nodi di lavoro è disponibile in Risoluzione dei problemi relativi al provisioning dei computer Bare Metal.

L'errore hardware non richiede la riesecuzione dell'aggiornamento

Se si verifica un errore hardware durante un aggiornamento, l'aggiornamento del runtime continua finché vengono soddisfatte le soglie impostate per i nodi di calcolo e gestione/controllo. Una volta corretto o sostituito il computer, viene eseguito il provisioning con il sistema operativo del runtime della piattaforma corrente, che contiene la versione di destinazione del runtime. Se un rack è stato aggiornato prima di un errore, la versione aggiornata del runtime verrà usata quando i nodi verranno sottoposti a provisioning. Se le specifiche del rack non sono state aggiornate alla versione di runtime aggiornata prima dell'errore hardware, il computer si configura con la versione di runtime precedente quando l'hardware viene ripristinato. La macchina viene aggiornata insieme al rack quando il rack avvia l'aggiornamento.

Dopo un aggiornamento di runtime, il cluster visualizza lo stato di provisioning "Non riuscito"

Durante un aggiornamento di runtime, il cluster entra in uno stato di Upgrading. Se l'aggiornamento del runtime non riesce, il cluster passa a uno Failed stato di provisioning. I componenti dell'infrastruttura (ad esempio, l'appliance di archiviazione) potrebbero causare errori durante l'aggiornamento. In alcuni scenari potrebbe essere necessario diagnosticare l'errore con Microsoft supporto.

La macchina Bare Metal mostra uno stato di 'Degradato' dopo l'aggiornamento del runtime.

Alcune situazioni possono far sì che un nodo ritorni nello stato Degraded. Questo stato si verifica se viene soddisfatta una qualsiasi delle condizioni indicate in Risolvere gli errori di stato degradato. Stato danneggiato indica che il nodo viene automaticamente bloccato per impedire la pianificazione di nuovi carichi di lavoro nel nodo fino a quando il problema sottostante non viene risolto.