Atualizar o ambiente de execução do cluster do CLI do Azure

Este artigo explica como realizar a atualização em tempo de execução de um cluster do Operator Nexus.

Pré-requisitos

1. Instale a última versão das extensões apropriadas da CLI.
2. Acesso à assinatura para executar os comandos de extensão NF (Malha de Rede) do Nexus do Operador do Azure e CLI de nuvem de rede (NC).
3. Colete as seguintes informações:
   • ID da assinatura (SUBSCRIPTION)
   • Nome do cluster (CLUSTER)
   • Grupo de recursos (CLUSTER_RG)
4. O status detalhado do cluster deve ser Running.
5. A conectividade do cluster com o Cluster Manager deve ser Connected.
6. Pré-requisitos do Azure (Workspace do Log Analytics, Conta de Armazenamento, Cofre de Chaves) devem ser validados. Esses recursos são verificados antes do início da atualização. Consulte a identidade gerenciada do cluster e os recursos fornecidos pelo usuário.
7. Em Cluster > Carga de trabalho > Servidores de computação
   • Os requisitos de integridade do nó do painel de controle antes da atualização são:
     • Se não houver um nó de plano de controle de reserva, todos os nós do plano de controle devem estar íntegros: estado de energia On, status de isolamento Uncordoned, estado pronto Yes e No degradado.
     • Se existir um nó de plano de controle de reserva, apenas o nó de reserva pode estar no estado de energia Off, estado pronto No e No degradado. Todos os outros nós do plano de controle devem estar íntegros: estado de energia On, status de isolamento Uncordoned, estado pronto Yes e No degradado.

     Observação

     Se a máquina de plano de controle de reserva passou anteriormente por um processo de provisionamento, espera-se que ela esteja com o status de isolamento Cordoned. Caso contrário, deve estar com o status de isolamento Uncordoned.

   • Os servidores do plano de gerenciamento são divididos em dois grupos, distribuídos entre racks de numeração ímpar e par. Em cada grupo, pelo menos mais de 50% dos servidores devem estar íntegros: estado de energia On, status de isolamento Uncordoned, estado pronto Yes e No degradado.
     • Em ambos os grupos de planos de gerenciamento, pelo menos 75% das máquinas de gerenciamento devem estar íntegras.
   • Os números do servidor do plano de cálculo variam de acordo com as configurações de limite de tempo de execução de cada cluster. Os clientes precisam determinar seu número mínimo com base em suas configurações, verificando o estado de energia On, status de isolamento Uncordoned, estado pronto Yes e No degradado.
8. Em Grupo de Recursos Gerenciados do Cluster > , selecione o nome do grupo para ir para a página do grupo de recursos.
   • No grupo de recursos, pesquise Kubernetes - Azure Arc para identificar as informações do Azure Arc e selecioná-las. O status deve ser Connected.
     • Na página Azure Arc, selecione Configurações > Extensões.
       • nc-platform-extension deve estar no status Succeeded.
       • nc-platform-runtime-extension deve estar no status Succeeded.

Verificar a versão atual do runtime

Verifique a versão atual do runtime do cluster antes da atualização: veja como verificar a versão atual do runtime do Cluster.

Localizando versões de runtime disponíveis

Por meio do Portal do Azure

Para encontrar versões de runtime atualizáveis disponíveis, navegue até o Cluster de destino no Azure portal. No painel de visão geral do Cluster, navegue até a guia Versões de atualização disponíveis .

Na guia versões de atualização disponíveis , você pode ver as diferentes versões de cluster disponíveis para atualização. Selecione a versão de runtime de destino na lista e prossiga com a atualização do cluster.

Via CLI do Azure

As atualizações disponíveis são recuperáveis por meio do CLI do Azure:

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

Na saída, você pode encontrar a propriedade availableUpgradeVersions e examinar o 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 não houver atualizações de cluster disponíveis, a lista estará vazia.

Configurar parâmetros de limite de computação para a atualização do Runtime usando o Cluster updateStrategy

O seguinte comando CLI do Azure é usado para configurar os parâmetros de limite de computação para uma atualização de 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>"

Parâmetros requeridos:

• strategy-type: define a estratégia de atualização. As configurações utilizadas são Rack (Rack a Rack) OU PauseAfterRack (Pausa para o usuário antes do início de cada rack). O valor padrão é Rack. Para executar uma atualização do tempo de execução do cluster usando a estratégia PauseAfterRack, siga as etapas descritas em Atualizar o Tempo de Execução do Cluster com a Estratégia PauseAfterRack.
• threshold-type: determina como o limite deve ser avaliado, aplicado nas unidades definidas pela estratégia. As configurações usadas são PercentSuccess OR CountSuccess. O valor padrão é PercentSuccess.
• threshold-value: o valor de limite numérico usado para avaliar uma atualização. O valor padrão é 80.

Parâmetros opcionais:

• max-unavailable: o número máximo de nós de trabalho que podem ser offline, ou seja, rack atualizado por vez. O valor padrão é 32767.
• wait-time-minutes: o período de atraso ou espera antes de atualizar um rack. O valor padrão é 15.

Comportamento de atualização baseado no tipo de limite PercentSuccess

O exemplo a seguir é para um cliente que usa a estratégia Rack-by-Rack com um Percentual 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% dos computadores em um rack são atualizados com êxito, o sistema considera o limite atingido e continua a atualizar o próximo rack, enquanto continua a provisionar todos os computadores restantes no rack atual. Se o limite não for atingido - o que significa que menos de 60% dos computadores no rack foram capazes de atualizar e, em vez disso, falharam, então a atualização do cluster é pausada. Quando uma atualização é pausada, o sistema fornece uma mensagem de status detalhada no cluster explicando o motivo. Nesse ponto, os computadores problemáticos no rack devem ser reparados e uma operação de continuação de atualização de cluster deve ser disparada para retomar e concluir a atualização.

Para exibir o status de atualização por meio do Azure portal, navegue até o recurso de Cluster de destino. Na tela Visão geral do Cluster, o status detalhado é fornecido juntamente com uma mensagem de status detalhada.

A atualização do cluster está em andamento quando detailedStatus está 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 está definido como Running e detailedStatusMessage mostra a mensagem Cluster is up and running

Se a Mensagem de Status Detalhado mostrar que a atualização está pausada, a mensagem terá a seguinte aparência: 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 de runtime, execute o comando az networkcloud cli a seguir.

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 proteções são aplicadas durante a operação de continuação da versão de atualização. Use All para executar todas as verificações de validação de pré-operação. Use None para ignorar as proteções que bloqueiam a atualização quando detectam problemas. O valor padrão é All.

Comportamento de atualização com base no tipo de limite CountSuccess

O exemplo a seguir é para um cliente que usa a estratégia Rack por Rack com um tipo CountSuccess de limite 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 prossegue para o próximo rack, enquanto continua a provisionar quaisquer máquinas restantes no rack atual. Se pelo menos 10 computadores no rack não forem atualizados, a atualização do cluster será pausada. Quando isso acontece, o hardware necessário deve ser reparado antes de executar a ação de continuação da versão de atualização para retomar e concluir a atualização.

Para solucionar problemas com máquinas bare-metal, consulte Solucionar problemas do servidor Nexus do Operador do Azure

Validações que podem bloquear a atualização do runtime do cluster

Ao iniciar uma atualização do runtime do cluster, o processo executa uma série de validações de pré-atualização antes que a atualização do runtime nas máquinas bare-metal do cluster comece. Essas validações confirmam que a atualização de runtime pode ter êxito dado o estado atual do cluster. Para obter mais informações, consulte as validações preliminares da atualização do Cluster Runtime.

Atualizar o runtime do cluster usando a CLI

Para atualizar a versão de runtime do cluster, use 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 requeridos:

• --target-cluster-version: a versão a ser aplicada ao cluster durante a atualização.

Parâmetros opcionais:

• --safeguard-mode: especifica como as proteções são aplicadas durante a operação de versão de atualização. Use All para executar todas as verificações de validação de pré-operação. Use None para ignorar as proteções que bloqueiam a atualização quando detectam problemas. O valor padrão é All.

Esse comando inicia o processo de atualização de runtime para o cluster especificado. O comando em si normalmente é concluído em cerca de cinco minutos, mas ele só inicia o processo de atualização quando as validações são bem-sucedidas. A atualização do runtime propriamente dita continua sendo executada em segundo plano e pode levar várias horas para ser concluída, à medida que atualiza os nós rack a rack e instala a nova versão do sistema operacional.

Informações detalhadas de status 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 término da ação.
• Status atual (SucceededouFailedInProgress).
• Qualquer contexto extra ou mensagem de erro associada ao status atual.
• A ID de Correlação da operação original cluster update-version, conforme mostrado no log de atividades 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.

Saída de exemplo JSON View 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 esse comando for concluído, o processo de atualização de tempo de execução completo será iniciado. 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 atualiza primeiro os nós do plano de controle, depois os nós de gerenciamento e e, em seguida, de forma sequencial, rack por rack, os nós de trabalho.
• Os servidores de gerenciamento são segregados em dois grupos, que são atualizados separadamente. Essa abordagem permite que os componentes em execução nos servidores de gerenciamento garantam resiliência durante a atualização de runtime aplicando regras de afinidade.
• As CSNs (redes de serviço de nuvem) também usam essa funcionalidade colocando uma instância em cada grupo de gerenciamento.
• Não há nenhuma interação do cliente com essa funcionalidade. No entanto, pode haver outros rótulos exibidos nos nós de gerenciamento para identificar os grupos.

A atualização é considerada concluída quando os limiares configurados pelo updateStrategy do cluster para racks de nós de trabalho são atingidos e pelo menos 50% dos nós de gerenciamento em cada grupo tenham sido atualizados com êxito. As cargas de trabalho podem ser afetadas enquanto os nós de trabalho em um rack estão sendo atualizados, mas as cargas de trabalho em todos os outros racks não são afetadas. A consideração do posicionamento da carga de trabalho à luz desse design de implementação é incentivada.

Monitore o progresso usando o status detalhado do cluster, disponível por meio do portal Azure ou CLI do Azure.

Para exibir o status de atualização por meio 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 as informações do Cluster de destino, juntamente com seu status detalhado e uma mensagem de status detalhada. Para obter informações mais detalhadas sobre o progresso da atualização, é possível verificar o status dos nós individuais em cada rack. Um exemplo é fornecido na seção de referências, em Funções de máquinas BareMetal.

Para exibir o status de atualização por meio do portal Azure, vá para o recurso de cluster de destino. Na tela Visão geral do cluster, você pode exibir o status detalhado junto com uma mensagem de status detalhada.

A atualização do cluster está em andamento quando detailedStatus está definida Updating e detailedStatusMessage mostra o progresso da atualização. Alguns exemplos de progresso da atualização 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 é concluída quando detailedStatus é definida Running e detailedStatusMessage mostra Cluster is up and running.

A atualização do cluster é pausada quando detailedStatus está definida Updating e detailedStatusMessage mostra o motivo ou componente que fez com que a atualização fosse pausada.

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

A atualização é pausada quando qualquer um dos seguintes ocorre:

1. Não é possível atualizar com sucesso todas as máquinas do plano de controle, e elas não estão provisionadas nem prontas.
2. Mais de 50% dos computadores em um grupo de planos de gerenciamento não podem ser atualizados e não estão provisionados e prontos. Os servidores do plano de gerenciamento são divididos em dois grupos, distribuídos entre racks de numeração ímpar e par.
3. Máquinas de nó de computação ou de trabalho configuradas de acordo com o limite não podem ser atualizadas e não estão provisionadas nem prontas.

Examine a mensagem de status detalhada do cluster para identificar qual componente fez a atualização entrar em um estado em pausa. Os exemplos abaixo mostram mensagens de status detalhadas para cada componente.

Mensagem detalhada de status de falha do plano de controle (KCP)

• "O cluster foi implantado, mas a atualização foi pausada. A atualização do plano de controle falhou, pois o capiCluster <clusterName> não está saudável. MachineHealthCheck pode estar substituindo máquinas KCP não saudáveis por máquinas do plano de gerenciamento para restaurar o quorum. Aguarde a conclusão da correção e, em seguida, execute a ação continue-update-version para concluir a atualização."

Mensagem detalhada de status da falha do grupo do plano de computação ou de gerenciamento

• "O cluster foi implantado, mas a atualização foi pausada. Máquinas no rack "<rack-id>" não estão íntegras. Corrija as máquinas e execute a ação de continuação da atualização de versão do cluster para concluir a atualização.

Depois que o componente afetado (plano de controle, gerenciamento ou computação) for identificado, faça o seguinte:

Etapa 1: verifique o status das máquinas bare-metal individuais para o componente afetado.

Um exemplo é apresentado na seção de referência, sob funções da máquina BareMetal.

Após identificar as máquinas bare metal do componente afetado, verifique o status de cada máquina e realize as ações a seguir, com base no estado de cada uma.

Etapa 2: Verifique os logs do estado da ação para o BMM.

Para verificar os logs do estado da ação de um BMM, navegue até o recurso BMM >Operations>Action Log.

Depois que o problema for resolvido e o computador Baremetal estiver provisionado e pronto, 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 proteções são aplicadas durante a operação de continuação da versão de atualização. Use All para executar todas as verificações de validação de pré-operação. Use None para ignorar as proteções que bloqueiam a atualização quando detectam problemas. O valor padrão é All.

Perguntas frequentes

Identificando a Atualização de Cluster Travada/Paralisada

Durante uma atualização de runtime, o cluster entra em um estado em pausa depois que o processo de atualização determina que a atualização não pode continuar sem intervenção manual. No entanto, às vezes, o processo de atualização pode não avançar enquanto o status detalhado ainda reflete a atualização como em andamento. Como a atualização de runtime pode levar muito tempo para ser concluída com êxito, não há nenhum tempo limite definido especificado no momento. Verifique periodicamente o status detalhado e os logs do seu cluster para determinar se a atualização está tentando ser realizada indefinidamente.

Você pode identificar uma atualização paralisada indefinidamente examinando os logs do cluster, a mensagem detalhada e a mensagem de status detalhada. Se essa condição ocorrer, você verá o cluster reconciliando continuamente o mesmo estado sem avançar. Verifique os logs do cluster ou o Log Analytics Workspace (LAW) configurado para verificar se há uma falha ou uma etapa específica causando a ausência de progresso.

Identificação de Atualização de Computador Bare-Metal Paralisado

Um guia para identificar problemas com o provisionamento de nós de trabalho é fornecido na Solução de problemas de provisionamento de computador bare-metal.

Falha de hardware não requer a re-execução da atualização

Se ocorrer uma falha de hardware durante uma atualização, a atualização de runtime continuará desde que os limites definidos sejam atendidos para os nós de computação e gerenciamento/controle. Depois que o computador é corrigido ou substituído, ele é provisionado com o sistema operacional do runtime da plataforma atual, que contém a versão de destino do runtime. Se um rack tiver sido atualizado antes de uma falha, a versão de runtime atualizada será usada quando os nós forem reprovisionados. Se a especificação do rack não foi atualizada para a versão de runtime atualizada antes da falha de hardware, o computador provisionará com a versão anterior do runtime quando o hardware for reparado. O computador é atualizado junto com o rack quando o rack inicia sua atualização.

Após uma atualização de runtime, o cluster mostra o estado de provisionamento "Com falha"

Durante uma atualização de runtime, o cluster entra em um estado de Upgrading. Se a atualização do runtime falhar, o Cluster entrará em um Failed estado de provisionamento. Componentes de infraestrutura (por exemplo, o Dispositivo de Armazenamento) podem causar falhas durante a atualização. Em alguns cenários, talvez seja necessário diagnosticar a falha com Microsoft suporte.

Máquina bare metal apresenta status Degradado após atualização de tempo de execução

Determinadas situações podem resultar em um nó retornando a um estado Degraded. Este estado ocorre se alguma das condições descritas em Solução de problemas de erros de status degradado for atendida. O status degradado significa que o nó é automaticamente isolado para impedir que novas cargas de trabalho sejam agendadas nele até que o problema subjacente seja resolvido.