Atualizar o tempo de execução do cluster da CLI do Azure

Este guia de instruções explica as etapas para instalar a CLI do Azure necessária e as extensões necessárias para interagir com o Nexus do Operador.

Pré-requisitos

1. Instale a última versão das extensões apropriadas da CLI.
2. A extensão mais recente networkcloud da CLI é necessária. Ele pode ser instalado seguindo as etapas listadas aqui.
3. Acesso à assinatura para executar os comandos de extensão NF (Malha de Rede) do Operador nexus do Azure e CLI de nuvem de rede (NC).
4. Colete as seguintes informações:
   • ID da assinatura (SUBSCRIPTION)
   • Nome do cluster (CLUSTER)
   • Grupo de recursos (CLUSTER_RG)
5. O status detalhado do cluster deve ser Running.
6. A conectividade do cluster com o Gerenciador de Clusters deve ser Connected.
7. Nos Servidores de Computação de Carga de Trabalho do Cluster >>
   • Três dos quatro nós do plano de controle devem estar no estado de energia On, estado de isolamento Uncordoned, estado pronto Yes e degradado No.
     • O nó sobressalente do plano de controle deve estar no estado de energia Off, estado pronto No e estado degradado No.
   • Os servidores do plano de gerenciamento são divididos em dois grupos em racks de números ímpares e de números pares. Para cada grupo, pelo menos metade dos servidores deve estar no Power State On, no status cordon Uncordoned, no estado pronto Yes e no estado degradado No.
     • É recomendável ter mais de 50% dos servidores do plano de gerenciamento disponíveis para atenuar qualquer risco.
   • 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 o seu número mínimo com base em suas configurações, verificando o estado de energia On, o status de isolamento Uncordoned, o estado preparado Yes e o estado degradado No.
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 do 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: como verificar a versão atual do runtime do Cluster.

Localizando versões de runtime disponíveis

Via Portal do Azure

Para encontrar versões de runtime atualizáveis disponíveis, navegue até o Cluster de destino no portal do Azure. 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 , podemos ver as diferentes versões do Cluster que estão disponíveis para atualização no momento. O operador pode selecionar entre as versões de runtime de destino listadas. Depois de selecionado, prossiga para atualizar o cluster.

Via CLI do Azure

As atualizações disponíveis são recuperáveis por meio da 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 atualização de runtime usando o Cluster updateStrategy

O seguinte comando da 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>" \
--update-strategy strategy-type="<strategyType>" threshold-type="<thresholdType>" \
threshold-value="<thresholdValue>" max-unavailable="<maxNodesOffline>" \
wait-time-minutes="<waitTimeBetweenRacks>" \
--subscription "<SUBSCRIPTION>"

Parâmetros requeridos:

• strategy-type: define a estratégia de atualização. As configurações usadas são Rack (Rack por Rack) OU PauseAfterRack (Pausar para o usuário antes de cada Rack ser iniciado). 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.

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, se menos de 60% dos nós de computação que estão sendo provisionados em um rack não forem provisionados (em uma base Rack por Rack), a atualização do cluster aguardará indefinidamente até que a condição seja atendida. Se 60% ou mais dos nós de computação forem provisionados com sucesso, a implantação do cluster passará para o próximo rack de nós de computação. Se houver muitas falhas no rack, o hardware deverá ser reparado antes que a atualização possa continuar.

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 menos de 10 nós de computação estão sendo provisionados em um rack e falharem no provisionamento (considerando cada rack individualmente), a atualização do cluster esperará indefinidamente até que a condição seja atendida. Se 10 ou mais dos nós de computação forem provisionados com êxito, a implantação do cluster passará para o próximo rack de nós de computação. Se houver muitas falhas no rack, o hardware deverá ser reparado antes que a atualização possa continuar.

Atualizar o runtime do cluster usando a CLI

Para executar uma atualização do runtime, use o seguinte comando da CLI do Azure:

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

Esse comando inicia o processo de atualização de runtime para o Cluster especificado. O comando em si normalmente é concluído em cerca de 5 minutos, mas esse comando só inicia o processo de atualização. A atualização real do runtime continua a ser executada em segundo plano e pode levar várias horas para ser concluída, pois atualiza o rack de nós por 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 no portal do JSON View Azure no 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.
• O ID de Correlação para a operação original cluster update-version , conforme também 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": "b66643b7-2e1d-4a5c-a954-ca0e38368984",
        "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"
          }
        ]
      }
    ]
  }
}

Depois que 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 primeiro atualiza os nós de gerenciamento e, em seguida, sequencialmente rack por rack para 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.
• Os CSNs também aproveitam 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 rótulos adicionais vistos em nós de gerenciamento para identificar os grupos.

A atualização é considerada concluída quando 80% de nós de trabalho por rack e 50% de nós de gerenciamento em cada grupo são atualizados com sucesso. As cargas de trabalho podem ser afetadas enquanto os nós de trabalho em um rack estão em processo de atualização, no entanto, 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.

A atualização de todos os nós leva várias horas, dependendo de quantos racks existem para o cluster. Devido à duração do processo de atualização, o status de detalhes do cluster deve ser verificado periodicamente quanto ao estado atual da atualização. Para verificar o status da atualização, observe o status detalhado do cluster. Essa verificação pode ser feita por meio do portal ou da CLI az.

Para exibir o status de atualização por meio do portal do Azure, 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

Para exibir o status de atualização por meio da CLI do Azure, use az networkcloud cluster show.

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

A saída deve ser as informações do cluster de destino e a mensagem detalhada de status e status de detalhes do cluster deve estar presente. Para obter informações mais detalhadas sobre o progresso da atualização, o nó individual em cada rack pode ser verificado quanto ao status. Um exemplo de verificação do status é fornecido na seção de referência em Funções do computador BareMetal.

Perguntas frequentes

Identificando a Atualização de Cluster Travada/Paralisada

Durante uma atualização de runtime, é possível que a atualização não avance, mas o status de detalhes reflete que a atualização ainda está 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. Portanto, é aconselhável também verificar periodicamente o status e os logs de detalhes do cluster para determinar se a atualização está tentando atualizar indefinidamente.

Podemos identificar a situação indefinitely attempting to upgrade examinando os logs do cluster, a mensagem detalhada e a mensagem de status detalhada. Se ocorrer um tempo limite, observaremos que o cluster está se reconciliando continuamente sobre o mesmo indefinidamente e não está avançando. A partir daqui, recomendamos verificar os logs de cluster ou o LAW configurado para ver se há uma falha ou uma atualização específica que esteja causando a falta 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. Os componentes de infraestrutura (por exemplo, o dispositivo 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.