Atualizar o runtime do Cluster usando o CLI do Azure

Este artigo explica como efetuar uma atualização durante o tempo de execução de um cluster do Operator Nexus.

Pré-requisitos

1. Instale a versão mais recente das extensões CLI apropriadas.
2. Acesso por subscrição para executar os comandos de extensão CLI do Nexus do Operador Azure Network Fabric (NF) e Network Cloud (NC).
3. Colete as seguintes informações:
   • ID da subscrição (SUBSCRIPTION)
   • Nome do cluster (CLUSTER)
   • Grupo de recursos (CLUSTER_RG)
4. O estado detalhado do cluster deve ser Running.
5. A conectividade entre gestores de clusters deve ser Connected.
6. Os pré-requisitos do Azure (Log Analytics Workspace, Storage Account, Key Vault) devem ser validados. Estes recursos são verificados antes do início da atualização. Consulte Identidade gerida por cluster e Recursos fornecidos pelo utilizador.
7. Em Clusters > de Servidores de Computação > para Carga de Trabalho
   • Os requisitos de saúde dos nós do plano de controlo antes da atualização são:
     • Se não existir um nó de plano de controlo livre, todos os nós do plano de controlo devem estar saudáveis: estado Onde energia, estado de cordão Uncordoned, estado de pronto Yes, e degradado No.
     • Se existir um nó de plano de controlo de reserva, apenas o nó de reserva pode estar no estado de Energia Off, no estado Pronto No e no estado Degradado No. Todos os outros nós do plano de controlo devem estar em bom estado: estado de energia On, estado de isolamento Uncordoned, estado de prontidão Yes e estado degradado No.

     Observação

     Se a máquina de reserva do plano de controlo foi anteriormente submetida a um processo de aprovisionamento, espera-se que esteja no estado Cordon Cordoned. Se não, deve estar em estado Uncordonedde Cordon.

   • Os servidores do plano de gestão estão divididos em dois grupos em racks ímpares e pares. Em cada grupo, pelo menos mais de 50% dos servidores devem estar saudáveis: Estado Onde Energia, Estado de Cordon Uncordoned, Estado de Pronto Yes, e Degradado No.
     • Em ambos os grupos de planos de gestão, pelo menos 75% das máquinas de gestão devem estar saudáveis.
   • O número de servidores do plano de cálculo varia consoante os limites de execução individuais do cluster. Os clientes precisam determinar o seu número mínimo com base nas definições, verificando o estado de energia elétrica On, o estado de isolamento Uncordoned, o estado de pronto Yes e o estado degradado No.
8. Em Grupo de Recursos Geridos por Cluster > , selecione o nome do grupo para ir à página do grupo de recursos.
   • No grupo de recursos, pesquise por Kubernetes - Azure Arc para identificar a informação Azure Arc e selecione-a. O estado deve ser Connected.
     • Dentro da página Azure Arc, selecione Definições > Extensões.
       • nc-platform-extension deve estar em estado Succeeded.
       • nc-platform-runtime-extension deve estar em estado Succeeded.

Verificando a versão atual do tempo de execução

Verifique a versão atual do tempo de execução do cluster antes da atualização: Veja Como verificar a versão atual do tempo de execução do Cluster.

Localizando versões de tempo de execução disponíveis

Através do portal do Azure

Para encontrar versões de runtime atualizáveis disponíveis, navegue até ao Cluster alvo no Azure portal. No painel Visão geral do Cluster, navegue até ao separador Versões de atualização disponíveis.

No separador de versões de atualização disponíveis , pode ver as diferentes versões do cluster disponíveis para atualizar. Selecione a versão de runtime alvo da lista e depois prossiga com a atualização do cluster.

Através da CLI do Azure

As atualizações disponíveis podem ser recuperadas através da CLI do Azure:

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

Na saída, pode-se encontrar a availableUpgradeVersions propriedade e ver o targetClusterVersion campo:

  "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 não houver atualizações de cluster disponíveis, a lista estará vazia.

Configurar parâmetros de limite de cálculo para atualização de tempo de execução usando o Cluster updateStrategy

O seguinte comando CLI do Azure é utilizado para configurar os parâmetros do limiar de cálculo para uma atualização de tempo de execução.

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

Parâmetros necessários:

• strategy-type: Define a estratégia de atualização. As definições utilizadas são Rack (Rack por Rack) ou PauseAfterRack (Pausa para o utilizador antes do início de cada Rack). O valor predefinido é Rack. Para executar uma atualização de tempo de execução do Cluster usando a estratégia PauseAfterRack, siga as etapas descritas em Upgrade Cluster Runtime with PauseAfterRack Strategy.
• tipo de limiar: Determina como o limiar deve ser avaliado, aplicado nas unidades definidas pela estratégia. As configurações usadas são PercentSuccess OU CountSuccess. O valor predefinido é PercentSuccess.
• valor-limite: o valor do limite numérico usado para avaliar uma atualização. O valor predefinido é 80.

Parâmetros opcionais:

• max-unavailable: o número máximo de nós de trabalho que podem estar offline, isto é, racks a serem atualizados ao mesmo tempo. O valor predefinido é 32767.
• wait-time-minutes: O atraso ou período de espera antes de atualizar um rack. O valor predefinido é 15.

Comportamento de Upgrade baseado no tipo de limiar de Percentual Sucesso

O exemplo a seguir é para um cliente que usa a estratégia Rack-by-Rack com uma porcentagem de sucesso de 60% e uma pausa de 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>"

Verifique a atualização:

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

Neste exemplo, uma vez que 60% das máquinas de um rack sejam atualizadas com sucesso, o sistema considera o limiar atingido e procede à atualização do próximo rack, continuando a provisionar quaisquer máquinas restantes no rack atual. Se o limiar não for atingido – ou seja, menos de 60% das máquinas no rack conseguiram atualizar e falharam – então a atualização do cluster fica pausada. Quando uma atualização é pausada, o sistema fornece uma mensagem de estado detalhada no cluster explicando a razão. Nesse ponto, as máquinas problemáticas no rack têm de ser reparadas, e uma operação de atualização contínua de cluster deve ser acionada para retomar e concluir a atualização.

Para ver o estado da atualização através do Azure portal, navegue até ao recurso do Cluster alvo. Na tela de Visão geral do Cluster , o status detalhado é fornecido juntamente com uma mensagem de status detalhada.

A atualização de cluster está em andamento quando detailedStatus é definido como Updating e detailedStatusMessage mostra o progresso da atualização. Alguns exemplos de progresso de atualização mostrados em detailedStatusMessage são Waiting for control plane upgrade to complete..., Waiting for nodepool "<rack-id>" to finish upgrading..., etc.

A atualização do cluster é concluída quando detailedStatus é definido como Running e detailedStatusMessage mostra a mensagem Cluster is up and running

Se a Mensagem de Estado Detalhado indicar que a atualização está pausada, a mensagem fica abaixo: 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

Para retomar a atualização em tempo de execução, execute o seguinte comando aznetworkcloud cli.

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

Parâmetros opcionais:

• --safeguard-mode: Especifica como as salvaguardas são aplicadas durante a operação de atualização contínua da versão. Use All para executar todas as verificações de validação pré-operação. Use None para contornar salvaguardas que bloqueiam a atualização quando detetam problemas. O valor predefinido é All.

Comportamento de Atualização Baseado no Tipo de Limiar de Contagem de Sucesso

O exemplo a seguir é para um cliente que usa a estratégia Rack-by-Rack com um tipo de limite CountSuccess de 10 nós por rack e uma pausa de 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>"

Verifique a atualização:

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

Neste exemplo, se pelo menos 10 nós forem atualizados com sucesso, a atualização avança para o próximo rack, continuando a provisionar quaisquer máquinas restantes no rack atual. Se pelo menos 10 máquinas no rack falharem em atualizar, a atualização do cluster pausa. Quando isto acontece, o hardware necessário deve ser reparado antes de executar a ação continuar-atualizar-versão para retomar e concluir a atualização.

Para resolver problemas com máquinas bare metal, consulte Resolver Problemas do Servidor Nexus do Operador Azure

Validações que podem bloquear a atualização do ambiente de execução do cluster

Quando se desencadeia uma atualização do runtime do cluster, o processo executa uma série de validações prévias à atualização antes de se iniciar a atualização do runtime nas máquinas bare metal do cluster. Estas validações confirmam que a atualização em tempo de execução pode ter sucesso, dado o estado atual do cluster. Para mais informações, consulte verificações prévias da atualização do runtime do cluster.

Atualizar o tempo de execução do cluster usando a CLI

Para atualizar a versão de execução do cluster, utilize o seguinte comando CLI do Azure:

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

Parâmetros necessários:

• --target-cluster-version: A versão a aplicar ao cluster durante a atualização.

Parâmetros opcionais:

• --safeguard-mode: Especifica como as salvaguardas são aplicadas durante a operação de atualização da versão. Use All para executar todas as verificações de validação pré-operação. Use None para contornar salvaguardas que bloqueiam a atualização quando detetam problemas. O valor predefinido é All.

Este comando inicia o processo de atualização em tempo de execução para o cluster especificado. O comando em si normalmente termina em cerca de cinco minutos, mas só inicia o processo de atualização quando as validações têm sucesso. A atualização do tempo de execução real continua a ser executada em segundo plano e pode levar várias horas para ser concluída, pois atualiza os nós rack por rack e instala a nova versão do sistema operacional.

Informações detalhadas de estado e diagnóstico para a etapa de iniciação estão disponíveis em Azure portal no JSON View do recurso Cluster (Operator Nexus). As informações a seguir são incluídas na updateVersion entrada do campo, ao usar a properties.actionStates versão 2025-07-01-preview da API ou superior.

• Hora de início e fim da ação.
• Situação atual (Succeeded, Failed, ou InProgress).
• Qualquer contexto extra ou mensagem de erro associada ao status atual.
• O ID de correlação para a operação original cluster update-version, como também mostrado no registo de atividade do Azure.
• Uma lista ordenada de etapas individuais e seu status - por exemplo Validate Cluster conditions and upgrade versions, e Initiate Platform Runtime Extension update.

Exemplo JSON View de resultado para o recurso 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"
          }
        ]
      }
    ]
  }
}

Quando este comando termina, inicia-se o processo completo de atualização em tempo de execução. Esse processo pode levar várias horas para ser concluído, dependendo do número de racks no cluster e do número de nós de trabalho em cada rack.

• A atualização começa por atualizar os nós do plano de controlo, depois os nós de gestão e, em seguida, os nós de trabalho, sequencialmente, de rack em rack.
• Os servidores de gerenciamento são segregados em dois grupos, que são atualizados separadamente. Essa abordagem permite que os componentes executados nos servidores de gerenciamento garantam resiliência durante a atualização de tempo de execução aplicando regras de afinidade.
• As redes de serviços cloud (CSNs) também utilizam esta funcionalidade ao colocar uma instância em cada grupo de gestão.
• Não há interação do cliente com essa funcionalidade. No entanto, podem existir outros rótulos nos nós de gestão para identificar os grupos.

A atualização é considerada concluída quando são atingidos os limiares configurados pelo updateStrategy do cluster para os racks de nós worker e pelo menos 50% dos nós de gestão de cada grupo tenham sido atualizados com sucesso. As cargas de trabalho podem ser afetadas enquanto os nós de trabalhadores num rack estão a ser atualizados, mas as cargas de trabalho em todos os outros racks não são afetadas. É encorajada a consideração da colocação da carga de trabalho à luz desta conceção de implementação.

Monitorize o progresso usando o estado detalhado do cluster, disponível através do portal Azure ou da CLI do Azure.

Para ver o estado da atualização através do CLI do Azure, use az networkcloud cluster show.

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

A saída inclui a informação do Cluster alvo juntamente com o seu estado detalhado e a mensagem de estado detalhada. Para obter informações mais pormenorizadas sobre o progresso da atualização, pode verificar-se o estado dos nós individuais de cada rack. Um exemplo é fornecido na secção de referência sob funções de BareMetal Machine.

Para ver o estado da atualização através do portal do Azure, aceda ao recurso do cluster alvo. No ecrã de Visão Geral do cluster, pode ver o estado detalhado juntamente com uma mensagem de estado detalhada.

A atualização do cluster está em curso quando detailedStatus está definida para Updating e detailedStatusMessage mostra o progresso da atualização. Alguns exemplos de progresso de melhoria mostrados em detailedStatusMessage são Waiting for control plane upgrade to complete... e Waiting for nodepool "<rack-id>" to finish upgrading....

A atualização do cluster está completa quando detailedStatus está definida para Running e detailedStatusMessage mostra Cluster is up and running.

A atualização do Cluster é pausada quando detailedStatus está definida para Updating e detailedStatusMessage mostra a razão ou componente que causou a pausa da atualização.

Atualização pausada do tempo de execução do cluster

A atualização pausa quando ocorre qualquer uma das seguintes situações:

1. Todas as máquinas do plano de controlo não podem ser atualizadas com sucesso e não estão aprovisionadas nem prontas.
2. Mais de 50% das máquinas num grupo de planos de gestão não podem ser atualizadas e não estão provisionadas e prontas. Os servidores do plano de gestão estão divididos em dois grupos em racks ímpares e pares.
3. As máquinas de computação ou de nós de trabalho configuradas com base num limiar não podem ser atualizadas e não estão aprovisionadas nem prontas.

Revise a mensagem detalhada de estado do cluster para identificar qual o componente que causou o estado de pausa da atualização. Os exemplos abaixo mostram mensagens de estado detalhadas para cada componente.

Mensagem detalhada de estado de falha do plano de controlo (KCP)

• "O Cluster está ativado, mas a atualização foi pausada. A atualização do plano de controlo falhou porque o capiCluster <clusterName> não está em bom estado. O MachineHealthCheck pode estar a trocar máquinas KCP insalubres por máquinas do Plano de Gestão para restaurar o quórum. Espere que a remediação seja concluída, depois execute a ação continue-update-version para completar a atualização."

Mensagem detalhada de estado de falha do grupo de cálculo ou plano de gestão

• "O Cluster está ativado, mas a atualização foi pausada. As máquinas no rack "<rack-id>" estão em mau estado. Corrija as máquinas e execute a ação cluster continue-update-version para concluir a atualização.

Uma vez identificado o componente afetado (plano de controlo, gestão ou computação), faça o seguinte:

Passo 1: Verifique o estado de cada máquina bare metal relativamente ao componente afetado.

Um exemplo é fornecido na secção de referência sob funções de BareMetal Machine.

Depois de identificar as máquinas de metal nu para o componente afetado, verifique o estado de cada máquina e tome as seguintes ações com base no seu estado.

Passo 2: Verifique os registos de estado de ação do BMM.

Para verificar os registos do estado das ações de um BMM, navegue até ao recurso BMM >Operações>Registo de ações.

Quando o problema está resolvido e a máquina Baremetal está provisionada e pronta, execute a ação do cluster continue-update-version para retomar e concluir a atualização.

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

Parâmetros opcionais:

• --safeguard-mode: Especifica como as salvaguardas são aplicadas durante a operação de atualização contínua da versão. Use All para executar todas as verificações de validação pré-operação. Use None para contornar salvaguardas que bloqueiam a atualização quando detetam problemas. O valor predefinido é All.

Perguntas Frequentes

Identificação da atualização de cluster paralisada/bloqueada

Durante uma atualização em tempo de execução, o cluster entra num estado de pausa assim que o processo de atualização determina que a atualização não pode avançar sem intervenção manual. No entanto, o processo de atualização pode, por vezes, não avançar enquanto o estado detalhado ainda reflete a atualização como em curso. Como a atualização do runtime pode demorar bastante tempo a ser concluída com sucesso, não está atualmente definido qualquer limite de tempo. Verifique periodicamente o estado detalhado e os registos do seu cluster para determinar se a sua atualização está a tentar ser atualizada indefinidamente.

Pode identificar uma atualização bloqueada indefinidamente olhando para os registos do cluster, a mensagem detalhada e a mensagem de estado detalhada. Se esta condição ocorrer, observa que o cluster reconcilia continuamente o mesmo estado sem progredir. Verifique os registos do cluster ou o Log Analytics Workspace (LAW) configurado para ver se há alguma falha ou uma etapa específica a causar a falta de progresso.

Identificando a atualização da máquina bare metal paralisada/presa

Um guia para identificar problemas com o provisionamento de nós de trabalho está disponível em "Solução de problemas de provisionamento de máquinas 'bare metal'".

Falha de hardware não requer reexecução de atualização

Se ocorrer uma falha de hardware durante uma atualização, a atualização em tempo de execução continuará desde que os limites definidos sejam atingidos para os nós de computação e gerenciamento/controle. Assim que a máquina é reparada ou substituída, ela é provisionada com o sistema operativo da plataforma de runtime atual, que contém a versão alvo do runtime. Se um rack foi atualizado antes de uma falha, a versão de tempo de execução atualizada será usada quando os nós forem reprovisionados. Se a especificação do rack não foi atualizada para a versão de tempo de execução atualizada antes da falha de hardware, a máquina será provisionada com a versão de tempo de execução anterior quando o hardware for reparado. A máquina é atualizada junto com o rack quando o rack inicia sua atualização.

Após uma atualização do ambiente de execução, o cluster mostra o estado de provisionamento "Com Falha"

Durante uma atualização de tempo de execução, o Cluster entra num estado de Upgrading. Se a atualização de tempo de execução falhar, o Cluster entrará em um estado de provisionamento Failed. Componentes da infraestrutura (por exemplo, o Appliance de Armazenamento) podem causar falhas durante a atualização. Em alguns cenários, pode ser necessário diagnosticar a falha com o suporte da Microsoft.

Máquina Bare Metal indica Degradado após Atualização de Runtime

Certas situações podem fazer com que um nó fique num estado Degraded. Este estado ocorre se alguma das condições descritas em Resolução de erros de estado degradado for cumprida. O estado degradado significa que o nó é automaticamente acordonado para evitar que novas cargas de trabalho sejam agendadas no nó até que o problema subjacente seja resolvido.