Esta documentação é referente à versão mais recente do GKE no Azure, lançada em novembro de 2021. Consulte as Notas de lançamento para mais informações.

Atualizar os parâmetros do cluster do Azure

Nesta página, descrevemos como atualizar as configurações do cluster do GKE no Azure. Use estas instruções para atualizar qualquer configuração atualizável no cluster, incluindo a versão do Kubernetes. Como o upgrade da versão é uma das operações de atualização de cluster mais comuns, uma página separada de upgrade do cluster aborda como fazer upgrade de uma versão de cluster.

Motivos para atualizar um cluster

Um cluster pode ser atualizado por qualquer um dos motivos a seguir:

Para atualizar a descrição do cluster
Para atualizar as anotações do cluster.
Atualizar a lista de usuários administrativos do cluster.
Atualizar a configuração de geração de registros do cluster.
Para atualizar o tamanho da VM do cluster.
Para atualizar o AzureClient do cluster.
Atualizar a autenticação do cluster do AzureClient para a federação de identidade da carga de trabalho

Também é possível atualizar outros campos nos clusters que não estão listados aqui. Para ver uma lista completa de parâmetros que é possível atualizar, consulte as documentações gcloud container azure clusters update e projects.locations.azureClusters.patch.

Prerequisites

Para atualizar qualquer um dos campos do cluster, você precisa ter a permissão gkemulticloud.googleapis.com/azureClusters.update Identity and Access Management.

O processo de atualização

O processo pelo qual o GKE no Azure atualiza um cluster varia de acordo com o tipo de atualização. Para algumas alterações, o GKE no Azure pode atualizar um cluster sem reiniciar ou recriar nenhum recurso. Por exemplo, atualizar a descrição de um cluster. O GKE no Azure faz essas alterações imediatamente.

Outras alterações exigem a reinicialização dos nós do plano de controle, por exemplo, a atualização do tamanho da VM ou da versão do Kubernetes. Para essas atualizações, o GKE no Azure executa uma "atualização gradual" que consiste nas seguintes etapas:

Escolha uma instância do plano de controle para atualizar. O GKE no Azure atualiza instâncias não íntegras, se houver, antes das íntegras.
Exclua a instância. O GKE no Azure recria a instância e ela é inicializada com a nova configuração.
Faça verificações de integridade na nova instância.
Se as verificações de integridade forem bem-sucedidas, selecione outra instância e execute as mesmas etapas nela. Repita esse ciclo até que todas as instâncias sejam reiniciadas ou recriadas. Se a verificação de integridade falhar, o GKE no Azure colocará o cluster em um estado DEGRADED e interromperá a atualização. Para mais informações, consulte a seção a seguir.

Quando uma atualização falha

Após uma atualização, o GKE no Azure executa uma verificação de integridade no cluster. Se a verificação de integridade falhar, o cluster será marcado como DEGRADED. É possível exibir o status do cluster com o seguinte comando da Google Cloud CLI:

gcloud container azure clusters describe CLUSTER_NAME \
  --location=GOOGLE_CLOUD_LOCATION

Substitua:

CLUSTER_NAME: o nome do cluster.
GOOGLE_CLOUD_LOCATION: a região do Google Cloud que gerencia o cluster

Atualizar o cluster

É possível usar o console do Google Cloud, a CLI do Google Cloud ou a API GKE Multi-cloud para atualizar diversos campos de cluster de uma só vez.

Escolher um método de atualização

É possível atualizar a maioria dos campos por meio do console, da CLI gcloud ou da API GKE Multi-cloud. Alguns campos só podem ser atualizados por meio de um mecanismo ou de outro. Se você quiser usar o console para atualizar um cluster, primeiro precisará escolher e configurar um método de autenticação para fazer login no cluster. Saiba mais em Conectar e autenticar no seu cluster.

Console

No console do Google Cloud, acesse a página Visão geral dos clusters do Google Kubernetes Engine.

Acesse os clusters do GKE
Selecione o projeto do Google Cloud em que o cluster está.
Na lista de clusters, selecione o nome do cluster e, em seguida, Ver detalhes no painel lateral.
Na guia Detalhes, selecione Editar no campo que você quer mudar.

Por exemplo, para conceder privilégios administrativos de cluster a outros usuários, selecione Editar ao lado de Usuários administradores e insira o endereço de e-mail do usuário.
Quando terminar de fazer as mudanças, selecione Concluído.

gcloud

Ao atualizar um cluster usando a CLI gcloud, é necessário sempre incluir os campos CLUSTER_NAME e GOOGLE_CLOUD_LOCATION, que informam ao GKE no Azure qual cluster atualizar. No comando a seguir, inclua apenas os campos que você quer atualizar. Remova os outros campos antes de executar o comando.

gcloud container azure clusters update CLUSTER_NAME \
    --location=GOOGLE_CLOUD_LOCATION \
    --cluster-version=CLUSTER_VERSION \
    --admin-users=USERNAME_LIST \
    --client=CLIENT_NAME \
    --vm-size=VM_SIZE

Substitua:

CLUSTER_NAME: o nome do cluster.
GOOGLE_CLOUD_LOCATION (obrigatório): a região compatível com o Google Cloud que gerencia seu cluster, por exemplo, us-west1
CLUSTER_VERSION: a nova versão de cluster compatível
USERNAME_LIST: uma lista separada por vírgulas de nomes de usuários, por exemplo, "kai@example.com,hao@example.com,kalani@example.com". Esses são os endereços de e-mail dos usuários para quem você está concedendo privilégios de administrador neste cluster. Os nomes nesse campo substituirão qualquer lista anterior de usuários administradores no cluster.
CLIENT_NAME: seu AzureClient
VM_SIZE: o novo tamanho da VM compatível

Para atualizar a autenticação do cluster do AzureClient para a federação de identidade da carga de trabalho, execute o seguinte comando:

gcloud container azure clusters update CLUSTER_NAME \
    --location=GOOGLE_CLOUD_LOCATION \
    --azure-tenant-id="${TENANT_ID}" \
    --azure-application-id="${APPLICATION_ID}" \
    --clear-client

API

Ao atualizar um cluster usando a API GKE Multi-cloud, sempre inclua os campos CLUSTER_NAME e GOOGLE_CLOUD_LOCATION na solicitação HTTP. Esses campos informam ao GKE no Azure qual cluster atualizar. Você também precisa incluir o endpoint da API na solicitação. Crie um arquivo JSON com os campos que você quer atualizar. Inclua apenas os campos que você quer atualizar no arquivo JSON e em UPDATE_MASK.

O exemplo a seguir mostra como atualizar o cluster usando a API. Para mais informações, incluindo a lista de campos que podem ser atualizados, consulte a documentação do método projects.locations.azureClusters.patch.

Crie um arquivo JSON chamado cluster_update.json com os campos que você quer atualizar.
- Ao usar a federação de identidade da carga de trabalho, o arquivo JSON deve ter a seguinte aparência:
```
{
  "description": "CLUSTER_DESCRIPTION",
  "controlPlane": {
    "version": "CLUSTER_VERSION",
    "vm_size": "VM_SIZE
  },
  "azureServicesAuthentication": {
    "tenantId": "TENANT_ID",
    "applicationId": "APPLICATION_ID"
  },
  "authorization": {
      "adminUsers": [
          {
          "username": USERNAME1,
          "username": USERNAME2,
          "username": USERNAME3
          }
      ]
  }
}
```
- Ao usar o cliente do Azure, o arquivo JSON deve ter a seguinte aparência:
```
{
  "description": "CLUSTER_DESCRIPTION",
  "controlPlane": {
    "version": "CLUSTER_VERSION",
    "vm_size": "VM_SIZE
  },
  "azureClient": "CLIENT_NAME",
  "authorization": {
      "adminUsers": [
          {
          "username": USERNAME1,
          "username": USERNAME2,
          "username": USERNAME3
          }
      ]
  }
}
```
Substitua:
- CLUSTER_VERSION: a nova versão de cluster compatível; Observe que você precisa fazer upgrade em todas as versões secundárias ao fazer upgrade do cluster
- CLUSTER_DESCRIPTION: a nova descrição do cluster
- USERNAME1,USERNAME2,USERNAME3 (opcional): os endereços de e-mail dos usuários a que você está concedendo privilégios administrativos neste cluster. Os nomes nesses campos substituirão qualquer lista anterior de usuários administradores no cluster.
- CLIENT_NAME: nome do seu AzureClient
- TENANT_ID: o ID do locatário do Azure
- APPLICATION_ID: o ID do aplicativo do Azure que foi criado em Criar um aplicativo do Azure Active Directory.
- VM_SIZE: o novo tamanho da VM

Atualize essas configurações por meio da API GKE Multi-Cloud com o comando a seguir.

curl -d @cluster_update.json -X PATCH \
   ENDPOINT/projects/PROJECT_ID/locations/GOOGLE_CLOUD_LOCATION/azureClusters/CLUSTER_NAME?update_mask=UPDATE_MASK

Substitua:

ENDPOINT (obrigatório): seu endpoint de serviço do Google Cloud
PROJECT_ID (obrigatório): seu projeto do Google Cloud
GOOGLE_CLOUD_LOCATION (obrigatório): a região compatível com o Google Cloud que gerencia seu cluster, por exemplo, us-west1
CLUSTER_NAME (obrigatório): o nome do cluster
UPDATE_MASK (obrigatório): uma lista separada por vírgulas de uma ou mais das seguintes sinalizações, indicando quais campos você quer atualizar. Neste exemplo, especifique o seguinte:
- controlPlane.version
- description
- authorization.admin_users
- control_plane.vm_size
- azure_client
- azure_services_authentication.tenant_id
- azure_services_authentication.application_id

Para atualizar a autenticação do cluster do AzureClient para a federação de identidade da carga de trabalho, adicione azure_client, azure_services_authentication.tenant_id e azure_services_authentication.application_id no campo update_mask (em inglês).

Atualizar configuração do Logging

É possível atualizar as definições de configuração do Cloud Logging do cluster com a Google Cloud CLI. Para atualizar a configuração da geração de registros, execute o seguinte comando:

gcloud container azure clusters update CLUSTER_NAME \
    --location=GOOGLE_CLOUD_LOCATION \
    --logging=LOGGING_CONFIG \

Substitua:

CLUSTER_NAME: o nome do cluster.
GOOGLE_CLOUD_LOCATION: a região compatível com o Google Cloud que gerencia seu cluster, por exemplo, us-west1
LOGGING_CONFIG: [SYSTEM] ou [SYSTEM,WORKLOAD]

A seguir

Para atualizar as chaves do volume do KMS, consulte Rotação de chaves.
Para mais informações sobre os campos atualizáveis, consulte a documentação de referência gcloud container azure clusters update.
Consulte a documentação da API REST projects.locations.azureClusters.patch.