Atualizar o Kubernetes e as imagens de nós em vários clusters usando o Gerenciador de Frota de Kubernetes do Azure

2025-06-18

Os administradores de plataforma que gerenciam um grande número de clusters geralmente têm problemas para preparar as atualizações de vários clusters (por exemplo, atualizar a imagem do sistema operacional do nó ou as versões do Kubernetes) de forma segura e previsível. Para resolver esse desafio, o Gerenciador de Frota de Kubernetes do Azure (Fleet) permite orquestrar atualizações em vários clusters usando execuções de atualização.

As execuções de atualização consistem em estágios, grupos e estratégias e podem ser aplicadas manualmente para atualizações únicas ou automaticamente para atualizações regulares contínuas usando perfis de atualização automática. Todas as execuções de atualização (manuais ou automatizadas) respeitam as janelas de manutenção do cluster de membros.

Este guia aborda como configurar e executar manualmente as atualizações.

Pré-requisitos

Leia a visão geral conceitual desse recurso, que fornece uma explicação das estratégias de atualização, execuções, estágios e grupos mencionados neste guia.
Você tem um recurso de frota com um ou mais clusters membros. Caso contrário, siga o início rápido para criar um recurso de frota e adicionar clusters do AKS (Serviço de Kubernetes do Azure) como membros.

Defina as seguintes variáveis de ambiente:

export GROUP=<resource-group>
export FLEET=<fleet-name>

Se estiver seguindo as instruções da CLI do Azure neste artigo, você precisará da versão 2.58.0 ou posterior da CLI do Azure instalada. Para instalar ou atualizar, confira Instalar a CLI do Azure.
Você também precisará da extensão fleet da CLI do Azure, que pode ser instalada executando o seguinte comando:
```
az extension add --name fleet
```
Execute o comando az extension update para atualizar para a versão mais recente da extensão lançada:
```
az extension update --name fleet
```

Definindo a sequência de atualização do cluster

A execução de atualização oferece suporte a duas opções para a sequência de atualização do cluster:

Um por um: Se você não se importa em controlar a sequência de atualização do cluster, o one-by-one oferece uma abordagem simples para atualizar todos os clusters membros da frota em sequência, um de cada vez.
Controle a sequência de clusters usando grupos e estágios de atualização: Se quiser controlar a sequência de atualização do cluster, você pode estruturar os clusters membros em grupos de atualização e estágios de atualização. Você pode armazenar essa sequência como um modelo na forma de uma estratégia de atualização. Você pode criar execuções de atualização posteriormente usando as estratégias de atualização em vez de definir a sequência sempre que precisar criar uma execução de atualização.

Observação

As execuções de atualização respeitam as janelas de manutenção planejada que você definiu no nível do cluster do AKS. Para obter mais informações, consulte manutenção planejada em vários clusters membros, que explica como as execuções de atualização lidam com clusters membros configurados com janelas de manutenção planejada.

Atualizar todos os clusters individualmente

Portal do Azure
CLI do Azure

No portal do Azure, navegue até o recurso do Gerenciador de Frota de Kubernetes do Azure.
No menu de serviço, em Configurações, selecione Atualização de vários clusters>Criar uma execução.
Insira um nome para a execução da atualização e selecione Um por um para o tipo de atualização.
Selecione uma das seguintes opções para o Escopo de atualização:
- Versão do Kubernetes tanto para o plano de controle quanto para os pools de nós
- Versão do Kubernetes somente para o plano de controle do cluster
- Somente versão da imagem do nó
Selecione uma das seguintes opções para a Imagem do nó:
- Imagem mais recente: Atualiza cada cluster AKS na execução de atualização para a imagem mais recente disponível para esse cluster em sua região.
- Imagem Consistente: Como é possível para uma execução de atualização ter clusters AKS em várias regiões em que as imagens de nó disponíveis mais recentes podem ser diferentes (confira o rastreador de versões para obter mais informações). A execução de atualização escolhe a imagem comum mais recente em todas essas regiões para obter consistência.
Selecione Criar para criar a execução de atualização.

Crie uma execução de atualização usando o comando az fleet updaterun create com os valores escolhidos para os sinalizadores --upgrade-type e --node-image-selection. O comando a seguir cria uma execução de atualização que atualiza a versão do Kubernetes para o plano de controle e os pools de nós e usa a imagem de nó mais recente disponível para cada cluster em sua região.

O sinalizador --upgrade-type dá suporte aos seguintes valores:
- Full atualiza a versão do Kubernetes para o plano de controle e os pools de nós, juntamente com as imagens do nó.
- ControlPlaneOnly atualiza somente a versão do Kubernetes para o plano de controle do cluster.
- NodeImageOnly atualiza apenas as imagens do nó.
O sinalizador --node-image-selection dá suporte aos seguintes valores:
- Latest: Atualiza cada cluster AKS na execução de atualização para a imagem mais recente disponível para esse cluster em sua região.
- Consistent: Como é possível que uma atualização seja executada para ter clusters AKS em várias regiões onde as imagens de nó mais recentes disponíveis podem ser diferentes (verifique o rastreador de versão para obter mais informações). A execução de atualização escolhe a imagem comum mais recente em todas essas regiões para obter consistência.
```
az fleet updaterun create \
 --resource-group $GROUP \
 --fleet-name $FLEET \
 --name run-1 \
 --upgrade-type Full \
 --kubernetes-version 1.26.0 \
 --node-image-selection Latest
```

Inicie a execução da atualização usando o comando az fleet updaterun start.

az fleet updaterun start \
 --resource-group $GROUP \
 --fleet-name $FLEET \
 --name run-1

Ao criar uma execução de atualização, você pode controlar o escopo da execução da atualização. O sinalizador --upgrade-type dá suporte aos seguintes valores:

ControlPlaneOnly atualiza somente a versão do Kubernetes para o plano de controle do cluster.
Full atualiza a versão do Kubernetes para o plano de controle e os pools de nós, juntamente com as imagens do nó.
NodeImageOnly atualiza apenas as imagens do nó.

Além disso, o sinalizador --node-image-selection dá suporte aos seguintes valores:

Última: atualiza todos os clusters do AKS na execução da atualização para a imagem mais recente disponível para esse cluster em sua região.
Consistente: como é possível para uma execução de atualização ter clusters AKS em várias regiões em que as imagens de nó disponíveis mais recentes podem ser diferentes (confira o rastreador de versões para obter mais informações). A execução de atualização escolhe a imagem comum mais recente em todas essas regiões para obter consistência.

Como iniciar uma execução de atualização:

Para iniciar as execuções de atualização, execute o seguinte comando:

az fleet updaterun start \
 --resource-group $GROUP \
 --fleet-name $FLEET \
 --name <run-name>

Atualizar clusters usando grupos e estágios

Você pode definir uma execução de atualização usando estágios de atualização para ordenar sequencialmente a aplicação de atualizações a diferentes grupos de atualização. Por exemplo, um primeiro estágio de atualização poderá atualizar os clusters membros do ambiente de teste e, a seguir, um segundo estágio de atualização irá atualizar os clusters membros do ambiente de produção. Você também pode especificar quais aprovações são necessárias antes ou depois de cada estágio e um tempo de espera entre os estágios de atualização. Você pode armazenar essa sequência como um modelo na forma de uma estratégia de atualização.

Portal do Azure
CLI do Azure

No portal do Azure, navegue até o recurso do Gerenciador de Frota de Kubernetes do Azure.
No menu de serviço, em Configurações, selecione Atualização de vários clusters>Criar uma execução.
Insira um nome para a execução da atualização e selecione Estágios para o tipo de sequência de atualização.
Selecione Criar estágio e, em seguida, insira um nome para o estágio e defina aprovações e um tempo de espera entre os estágios, se desejado.
Selecione os grupos de atualização que você deseja incluir neste estágio. Também é possível especificar a ordem dos grupos de atualização se quiser atualizá-los em uma sequência específica. Quando terminar, selecione Criar.
Selecione uma das seguintes opções para o Escopo de atualização:
- Versão do Kubernetes tanto para o plano de controle quanto para os pools de nós
- Versão do Kubernetes somente para o plano de controle do cluster
- Somente versão da imagem do nó
Selecione uma das seguintes opções para a Imagem do nó:
- Imagem mais recente: Atualiza cada cluster AKS na execução de atualização para a imagem mais recente disponível para esse cluster em sua região.
- Imagem Consistente: Como é possível para uma execução de atualização ter clusters AKS em várias regiões em que as imagens de nó disponíveis mais recentes podem ser diferentes (confira o rastreador de versões para obter mais informações). A execução de atualização escolhe a imagem comum mais recente em todas essas regiões para obter consistência.
Selecione Criar para criar a execução de atualização.

Especificar os estágios e sua ordem sempre que for preciso criar uma execução de atualização pode se tornar repetitivo e trabalhoso. As estratégias de atualização simplificam essa tarefa permitindo que você armazene modelos para as execuções da atualização. Para obter mais informações, confira criação e uso de estratégias de atualização.
No menu Atualização de vários clusters, selecione a execução de atualização e, em seguida, Iniciar.

Crie um arquivo JSON para definir os estágios e grupos para a execução da atualização. Aqui está um exemplo de entrada do arquivo de estágios (example-stages.json):

{
    "stages": [
        {
            "name": "stage1",
            "groups": [
                {
                    "name": "group-1a"
                },
                {
                    "name": "group-1b"
                },
                {
                    "name": "group-1c"
                }
            ],
            "afterStageWaitInSeconds": 3600
        },
        {
            "name": "stage2",
            "groups": [
                {
                    "name": "group-2a"
                },
                {
                    "name": "group-2b"
                },
                {
                    "name": "group-2c"
                }
            ]
        }
    ]
}

Crie uma execução de atualização usando o comando az fleet updaterun create com o sinalizador --stages definido como o nome do arquivo JSON e os valores escolhidos para os sinalizadores --upgrade-type e --node-image-selection. O comando a seguir cria uma execução de atualização que atualiza a versão do Kubernetes para o plano de controle e os pools de nós e usa a imagem de nó mais recente disponível para cada cluster em sua região.

O sinalizador --upgrade-type dá suporte aos seguintes valores:
- Full atualiza a versão do Kubernetes para o plano de controle e os pools de nós, juntamente com as imagens do nó.
- ControlPlaneOnly atualiza somente a versão do Kubernetes para o plano de controle do cluster.
- NodeImageOnly atualiza apenas as imagens do nó.
O sinalizador --node-image-selection dá suporte aos seguintes valores:
- Latest: Atualiza cada cluster AKS na execução de atualização para a imagem mais recente disponível para esse cluster em sua região.
- Consistent: Como é possível que uma atualização seja executada para ter clusters AKS em várias regiões onde as imagens de nó mais recentes disponíveis podem ser diferentes (verifique o rastreador de versão para obter mais informações). A execução de atualização escolhe a imagem comum mais recente em todas essas regiões para obter consistência.
```
az fleet updaterun create \
 --resource-group $GROUP \
 --fleet-name $FLEET \
 --name run-1 \
 --upgrade-type Full \
 --kubernetes-version 1.26.0 \
 --node-image-selection Latest \
 --stages example-stages.json
```

Inicie a execução da atualização usando o comando az fleet updaterun start.

az fleet updaterun start \
 --resource-group $GROUP \
 --fleet-name $FLEET \
 --name run-1

Criar uma execução da atualização usando estratégias de atualização

A criação de uma execução de atualização exige que você especifique os estágios, os grupos, a ordem a cada vez. As estratégias de atualização simplificam essa tarefa permitindo que você armazene modelos para as execuções da atualização.

Observação

É possível criar várias execuções da atualização com nomes exclusivos da mesma estratégia de atualização.

Você pode criar uma estratégia de atualização usando um dos seguintes métodos:

Salvar uma estratégia de atualização ao criar uma execução da atualização

Salve uma estratégia de atualização ao criar uma execução de atualização no portal do Azure:

Gerenciar uma execução de atualização

As seções a seguir explicam como gerenciar uma execução de atualização usando o portal do Azure e a CLI do Azure.

Portal do Azure
CLI do Azure

Na página Atualização de vários clusters do recurso de frota, você pode Iniciar uma execução de atualização que esteja no estado Não iniciada ou Com falha:
Na página Atualização de vários clusters do recurso de frota, você pode Parar uma execução de atualização atualmente Em execução ou Pendente:
Em qualquer execução de atualização nos estados Não iniciada, Com falha ou Em execução, você pode selecionar qualquer Estágio e Ignorar a atualização:

Da mesma forma, você também pode ignorar a atualização no nível de grupo de atualizações ou de cluster de membros.

Você pode Iniciar uma execução de atualização que esteja no estado Não iniciado ou Com falha usando o comando az fleet updaterun start:
```
az fleet updaterun start \
 --resource-group $GROUP \
 --fleet-name $FLEET \
 --name <run-name>
```
Você pode Interromper uma atualização em execução Em execução usando o comando az fleet updaterun stop:
```
az fleet updaterun stop \
 --resource-group $GROUP \
 --fleet-name $FLEET \
 --name <run-name>
```
Você pode ignorar estágios ou grupos de atualização especificando-os no sinalizador --targets usando o comando az fleet updaterun skip:
```
az fleet updaterun skip \
 --resource-group $GROUP \
 --fleet-name $FLEET \
 --name <run-name> \
 --targets Group:my-group-name Stage:my-stage-name
```
Para obter mais informações, confira o artigo visão geral conceitual dos estados de execução de atualizações e o comportamento ignorar em execuções/estágios/grupos.

Automatizar execuções de atualização usando perfis de atualização automática

Os perfis de atualização automática são usados para executar automaticamente as atualizações nos clusters membros quando novas versões do Kubernetes ou da imagem do nó são disponibilizadas.

Para obter mais informações sobre a configuração de perfis de atualização automática, consulte automatizar atualizações do Kubernetes e imagens de nó usando o Gerenciador de Frota de Kubernetes do Azure.

Gerar uma execução de atualização por meio de um perfil de atualização automática

Quando você cria um perfil de atualização automática, seus clusters podem estar em várias versões do Kubernetes ou da imagem do nó. Dependendo do canal de atualização automática selecionado, pode levar algum tempo até que uma nova versão dispare a atualização automática para criar e executar uma execução de atualização.

A atualização automática permite que você gere uma nova execução de atualização a qualquer momento usando o az fleet autoupgradeprofile generate-update-run comando. A execução de atualização resultante baseia-se na versão atual da imagem do Kubernetes ou do nó publicada pelo AKS.

az fleet autoupgradeprofile generate-update-run \ 
    --resource-group $GROUP \ 
    --fleet-name $FLEET \ 
    --name $AUTOUPGRADEPROFILE

A execução de atualização gerada não é iniciada automaticamente, permitindo que você a examine. Se você estiver satisfeito com a execução de atualização gerada, poderá iniciá-la e gerenciá-la seguindo as etapas para gerenciar uma execução de atualização.