Atualizar um cluster do Kubernetes usando o mecanismo do AKS no Azure Stack Hub

Artigo
12/01/2023

O mecanismo do AKS permite atualizar o cluster do Kubernetes que foi originalmente implantado usando a ferramenta no Azure Stack Hub. Você pode manter os clusters usando o mecanismo do AKS. Suas tarefas de manutenção são semelhantes a qualquer sistema IaaS. Você deve estar ciente da disponibilidade de novas atualizações e usar o mecanismo do AKS para aplicá-las.

Atualizar um cluster

O comando de atualização atualiza a versão do Kubernetes e a imagem base do sistema operacional. Sempre que você executa o comando de atualização, para cada nó do cluster, o mecanismo do AKS cria uma nova VM usando a imagem base do AKS associada à versão do aks-engine usada.

Para as versões 0.73.0 e inferiores do Mecanismo do AKS, você pode usar o aks-engine upgrade comando para manter a moeda de cada master e nó do agente no cluster.

Para as versões 0.75.3 e superiores do Mecanismo do AKS, você pode usar o aks-engine-azurestack upgrade comando para manter a moeda de cada master e nó do agente no cluster.

A Microsoft não gerencia seu cluster. Mas a Microsoft fornece a ferramenta e a imagem da VM que você pode usar para gerenciar seu cluster.

Para um cluster implantado, as atualizações abrangem:

Kubernetes
Provedor de Kubernetes do Azure Stack Hub
Sistema operacional base

Ao atualizar um cluster de produção, considere:

Você está usando a especificação de cluster (apimodel.json) e o grupo de recursos corretos para o cluster de destino?
Você está usando um computador confiável para o computador cliente executar o mecanismo do AKS e do qual está executando operações de atualização?
Verifique se você tem um cluster de backup e se ele está operacional.
Se possível, execute o comando de uma VM dentro do ambiente do Azure Stack Hub para diminuir os saltos de rede e possíveis falhas de conectividade.
Verifique se sua assinatura tem espaço suficiente para todo o processo. O processo aloca novas VMs durante o processo.
Nenhuma atualização do sistema ou tarefas agendadas estão planejadas.
Configurar uma atualização em estágios em um cluster configurado exatamente como o cluster de produção e testar a atualização lá antes de fazer isso no cluster de produção

Etapas para atualizar para uma versão mais recente do Kubernetes

Observação

A imagem base do AKS também será atualizada se você estiver usando uma versão mais recente do aks-engine e a imagem estiver disponível no marketplace.

As instruções a seguir usam as etapas mínimas para executar a atualização. Se você quiser obter mais detalhes, consulte o artigo Atualizando clusters do Kubernetes.

Primeiro, você precisa determinar as versões que podem ser direcionadas para a atualização. Essa versão depende da versão que você tem no momento e, em seguida, usa esse valor de versão para executar a atualização. As versões do Kubernetes compatíveis com o Mecanismo do AKS podem ser listadas executando o seguinte comando:

Observação

Para o AKSe versão 0.75.3 e superior, o comando para obter as versões do mecanismo do AKS é aks-engine-azurestack get-versions.
```
aks-engine get-versions --azure-env AzureStackCloud
```
Para obter um mapeamento completo do mecanismo do AKS, da imagem base do AKS e das versões do Kubernetes, confira Versões do mecanismo do AKS com suporte.

Colete as informações necessárias para executar o upgrade comando. O upgrade comando usa os seguintes parâmetros:

Parâmetro	Exemplo	Descrição
azure-env	AzureStackCloud	Para indicar ao mecanismo do AKS que sua plataforma de destino é o Azure Stack Hub, use `AzureStackCloud`.
local	local	O nome da região do Azure Stack Hub. Para o ASDK, a região é definida como `local`.
resource-group	kube-rg	Insira o nome de um novo grupo de recursos ou selecione um grupo de recursos existente. O nome do recurso precisa ser alfanumérico e minúsculo.
id da assinatura	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	Insira sua ID da Assinatura. Para obter mais informações, consulte Assinar uma oferta
api-model	./kubernetes-azurestack.json	Caminho para o arquivo de configuração de cluster ou modelo de API.
client-id	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	Insira o GUID da entidade de serviço. A ID do cliente identificada como a ID do Aplicativo quando o administrador do Azure Stack Hub criou a entidade de serviço.
client-secret	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	Insira o segredo da entidade de serviço. Esse é o segredo do cliente que você configurou ao criar seu serviço.
identity-system	adfs	Opcional. Especifique sua solução de gerenciamento de identidades se você estiver usando o AD FS (Serviços Federados do Active Directory).

Com seus valores em vigor, execute o seguinte comando:

Observação

Para o AKSe versão 0.75.3 e superior, o comando para atualizar o mecanismo do AKS é aks-engine-azurestack upgrade.

aks-engine upgrade \
--azure-env AzureStackCloud \
--location <for an ASDK is local> \
--resource-group kube-rg \
--subscription-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--api-model kube-rg/apimodel.json \
--upgrade-version 1.18.15 \
--client-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--client-secret xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--identity-system adfs # required if using AD FS

Se, por algum motivo, a operação de atualização encontrar uma falha, você poderá executar novamente o upgrade comando depois de resolver o problema. O mecanismo do AKS retomará a operação em que falhou na hora anterior.

Etapas para atualizar apenas a imagem do sistema operacional

Examine a tabela supported-kubernetes-versions e determine se você tem a versão do aks-engine e da imagem base do AKS que planeja para a atualização. Se você estiver no Mecanismo do AKS versão 0.73.0 ou inferior, para exibir a versão do aks-engine, execute: aks-engine version. Se você estiver no Mecanismo do AKS versão 0.75.3 ou superior, para exibir a versão do aks-engine, execute: aks-engine-azurestack version.
Atualize o mecanismo do AKS adequadamente, no computador em que você instalou a execução do aks-engine: ./get-akse.sh --version vx.xx.x substituindo x.xx.x pela versão de destino.
Peça ao operador do Azure Stack Hub para adicionar a versão da Imagem Base do AKS necessária no Azure Stack Hub Marketplace que você planeja usar.
Execute o aks-engine upgrade comando usando a mesma versão do Kubernetes que você já está usando, mas adicione o --force. Você pode ver um exemplo em Forçar uma atualização.

Etapas para atualizar o cluster para a versão do sistema operacional Ubuntu 20.04

Com o mecanismo aks versão 0.75.3 e superior, você pode atualizar suas VMs de cluster do Ubuntu 18.04 para 20.04. Siga estas etapas:

Localize e edite o api-model.json arquivo que foi gerado durante a implantação. Esse deve ser o mesmo arquivo usado para qualquer operação de atualização ou escala com aks-engine. No Mecanismo do AKS versão 0.75.3 e superior, use aks-engine-azurestack.
Localize as seções para masterProfile e agentPoolProfiles, dentro dessas seções, altere o valor de distro para aks-ubuntu-20.04.
Salve o api-model.json arquivo e use o api-model.json arquivo em seu aks-engin upgrade comando como faria nas Etapas para atualizar para uma versão mais recente do Kubernetes

Etapas para atualizar o cluster se você estiver usando volumes de armazenamento com o Mecanismo do AKS v0.70.0 e posterior

O projeto Provedor de Nuvem para Azure (também conhecido como cloud-controller-manager, provedor de nuvem fora de árvore ou provedor de nuvem externo) implementa a interface do provedor de nuvem do Kubernetes para nuvens do Azure. A implementação fora da árvore é a substituição da implementação na árvore preterida.

No Azure Stack Hub, a partir do Kubernetes v1.21, os clusters baseados no Mecanismo do AKS usarão cloud-controller-managerexclusivamente . Portanto, para implantar um cluster do Kubernetes v1.21+, é necessário definir orchestratorProfile.kubernetesConfig.useCloudControllerManager como true no Modelo de API (exemplo). O processo de atualização do Mecanismo do AKS atualizará automaticamente o useCloudControllerManager sinalizador.

Observação

Considerações de atualização: o processo de atualização de um cluster kubernetes da v1.20 (ou versão inferior) para v1.21 (ou versão maior) causará tempo de inatividade para cargas de trabalho que dependem do kubernetes.io/azure-disk provisionador de volume na árvore. Antes de atualizar para o Kubernetes v1.21+, é altamente recomendável executar um backup completo dos dados do aplicativo e validar em um ambiente de pré-produção que os recursos de armazenamento de cluster (PV e PVC) podem ser migrados para um novo provisionador de volume. Saiba como migrar para o driver CSI do Disco do Azure aqui.

Provisionadores de volume

O provisionador de volume na árvore só é compatível com o provedor de nuvem na árvore. Portanto, um cluster v1.21+ precisará incluir um Driver da CSI (Interface de Armazenamento de Contêiner) se as cargas de trabalho do usuário dependerem do armazenamento persistente. Algumas soluções disponíveis no Azure Stack Hub estão listadas aqui.

O Mecanismo do AKS não habilitará nenhum driver CSI por padrão no Azure Stack Hub. Para cargas de trabalho que exigem um driver CSI, é possível habilitar explicitamente o azuredisk-csi-drivercomplemento (clusters somente Linux) ou usar Helm para instalar o azuredisk-csi-driver gráfico (clusters Linux e/ou Windows).

Migrar o armazenamento persistente para o driver CSI do Disco do Azure

O processo de atualização de um cluster baseado no Mecanismo do AKS da v1.20 (ou versão inferior) para a v1.21 (ou versão maior) causará tempo de inatividade para cargas de trabalho que dependem do kubernetes.io/azure-disk provisionador de volume na árvore, pois esse provisionador não faz parte do Provedor de Nuvem para Azure.

Se os dados persistidos nos discos subjacentes do Azure devem ser preservados, as seguintes etapas extras serão necessárias depois que o processo de atualização do cluster for concluído:

1. Instalar o driver CSI do Disco do Azure manualmente

O script a seguir usa Helm para instalar o Driver CSI de Disco do Azure:

DRIVER_VERSION=v1.10.0
helm repo add azuredisk-csi-driver https://raw.githubusercontent.com/kubernetes-sigs/azuredisk-csi-driver/master/charts
helm install azuredisk-csi-driver azuredisk-csi-driver/azuredisk-csi-driver \
  --namespace kube-system \
  --set cloud=AzureStackCloud \
  --set controller.runOnMaster=true \
  --version ${DRIVER_VERSION}

2. Substituir classes de armazenamento

O kube-addon-manager criará automaticamente as classes de armazenamento do driver CSI do Azure Disk (disk.csi.azure.com) depois que as classes de armazenamento na árvore (kubernetes.io/azure-disk) forem excluídas manualmente:

IN_TREE_SC="default managed-premium managed-standard"

# Delete deprecated "kubernetes.io/azure-disk" storage classes
kubectl delete storageclasses ${IN_TREE_SC}

# Wait for addon manager to create the "disk.csi.azure.com" storage class resources
kubectl get --watch storageclasses

3. Recriar volumes persistentes

Depois que o Driver CSI de Disco do Azure for instalado e as classes de armazenamento forem substituídas, a próxima etapa será recriar os volumes persistentes (PV) e as declarações de volumes persistentes (PVC) usando o driver CSI do Disco do Azure (ou a solução CSI alternativa).

Esse é um processo de várias etapas que pode ser diferente dependendo de como esses recursos foram implantados inicialmente. As etapas de alto níveis são:

Exclua a implantação ou o conjunto com estado que faz referência aos pares PV + PVC a serem migrados (definição de recurso de backup, se necessário).
Verifique se a propriedade de persistentVolumeReclaimPolicy PVs está definida como valor Retain (exemplo).
Exclua os pares PV + PVC para migrar (definições de recurso de backup, se necessário).
Para migrar, atualize a definição de recurso dos PVs removendo o azureDisk objeto e adicionando um csi objeto com referência ao AzureDisk original (exemplo).
Recrie, na ordem a seguir, os recursos/s de PV, os recursos/s do PVC (se necessário) e, por fim, a implantação ou o conjunto com estado.

O script de migração a seguir é fornecido como um modelo.

Depois de executar o script de migração, se o pod estiver travado com o erro "Não é possível anexar ou montar volumes", verifique se o Driver CSI do Disco do Azure foi instalado e as classes de armazenamento foram recriadas.

Forçando uma atualização

Pode haver condições em que talvez você queira forçar uma atualização do cluster. Por exemplo, no primeiro dia, você implanta um cluster em um ambiente desconectado usando a versão mais recente do Kubernetes. No dia seguinte, o Ubuntu lança um patch para uma vulnerabilidade para a qual a Microsoft gera uma nova Imagem Base do AKS. Você pode aplicar a nova imagem forçando uma atualização usando a mesma versão do Kubernetes que você já implantou.

Observação

Para o AKSe versão 0.75.3 e superior, o comando para atualizar o mecanismo do AKS é aks-engine-azurestack upgrade.

aks-engine upgrade \
--azure-env AzureStackCloud   
--location <for an ASDK is local> \
--resource-group kube-rg \
--subscription-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--api-model kube-rg/apimodel.json \
--upgrade-version 1.18.15 \
--client-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--client-secret xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--force

Para obter instruções, consulte Forçar atualização.

Atualizar um cluster do Kubernetes usando o mecanismo do AKS no Azure Stack Hub