Sequenciar o lançamento de upgrades de cluster com etapas personalizadas

Neste documento, mostramos como gerenciar upgrades de cluster do Google Kubernetes Engine (GKE) que usam o sequenciamento de lançamentos com etapas personalizadas. Você cria uma sequência de lançamento usando grupos de clusters organizados em frotas e opcionalmente, subconjuntos de clusters dessas frotas. É possível escolher quanto tempo de teste de permanência você quer quando os upgrades de cluster forem concluídos em um grupo (máximo de 30 dias). É possível incluir clusters do Autopilot e Standard. Para mais informações sobre como esse recurso funciona, consulte Sobre o sequenciamento de lançamento com etapas personalizadas.

Se você gerenciar rollouts em várias frotas, recomendamos usar um projeto dedicado para hospedar seus objetos RolloutSequence. Esse projeto atua como pai e coordenador dos rollouts em toda a sequência. Normalmente, esse projeto não faz parte da sequência. Ou seja, ele não contém frotas nem clusters que fazem parte da sequência.

Antes de começar

  • Instale a CLI do Google Cloud. Após a instalação, inicialize a CLI do Google Cloud executando o seguinte comando: 

    gcloud init

    Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

  • Verifique se você tem clusters do Autopilot ou do Standard. Para criar um novo cluster, consulte Criar um cluster do Autopilot.

  • (Opcional) Se você ainda não tiver um projeto Google Cloud dedicado para hospedar sua configuração do RolloutSequence, crie um usando o console do Google Cloud ou outro método.

  • Verifique se você ativou as APIs necessárias para as frotas. Essas APIs precisam ser ativadas nos projetos host da frota para criar qualquer tipo de sequência de lançamento. No projeto host da sequência de lançamento, ative a API gkehub.googleapis.com.

Funções exigidas

Para criar um projeto, é preciso ter o papel Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder benefícios.

Para criar ou modificar uma sequência de lançamento, você precisa ter o papel de editor da frota do IAM (roles/gkehub.editor) em cada projeto host da frota na sequência de lançamento e no projeto host da sequência de lançamento. Esse papel fornece as seguintes permissões:

  • gkehub.rolloutsequences.create
  • gkehub.rolloutsequences.get
  • gkehub.rolloutsequences.list
  • gkehub.rolloutsequences.update
  • gkehub.rolloutsequences.delete
  • gkehub.fleet.get

Com essas permissões, é possível criar, acessar e modificar objetos RolloutSequence e usar frotas na sequência de lançamento.

Se você precisar registrar ou cancelar o registro de clusters em uma frota, precisará de todas as permissões a seguir:

Para mais informações sobre os papéis do IAM com privilégios mínimos necessários para diferentes tarefas, consulte Receber sugestões de papéis predefinidos com a assistência do Gemini.

Configurar uma sequência de lançamento

Para criar uma sequência de lançamento, os clusters precisam ser organizados em grupos de frotas. Também é possível criar etapas granulares que segmentam subconjuntos específicos de clusters em uma frota usando rótulos do Kubernetes. Para orientações sobre como organizar os clusters, consulte o exemplo do banco comunitário. Depois de organizar os clusters em grupos e, opcionalmente, rotulá-los, crie uma sequência de lançamento definindo a lista ordenada de estágios e o tempo de espera para cada grupo.

Organizar clusters em frotas

Em uma sequência de lançamento, recomendamos registrar todos os clusters no mesmo canal de lançamento. Se os clusters não estiverem registrados no mesmo canal, o GKE vai selecionar uma versão do canal mais conservador na sequência. Por exemplo, se os clusters estiverem registrados nos canais Estável e Normal, o GKE vai escolher a versão do canal Estável. Também recomendamos que todos os clusters executem a mesma versão secundária para serem qualificados para a mesma versão de destino do upgrade automático.

Se você já tiver organizado os clusters em frotas, pule as etapas a seguir e continue para a seção Criar subconjuntos de clusters.

  1. Agrupe os clusters em frotas. É possível organizar os clusters por ambientes de implantação, como teste, preparo e Production (recomendado).
  2. Registre cada cluster com uma frota com base no agrupamento escolhido.

Criar subconjuntos de clusters (opcional)

Para que uma etapa na sua sequência de lançamento tenha como destino clusters específicos, é preciso rotular esses clusters.

Por exemplo, para testar uma nova versão em um pequeno subconjunto de clusters antes de um lançamento completo, aplique um rótulo canary a esses clusters. Para adicionar o rótulo canary com o valor true a um cluster usando a CLI do Google Cloud, execute o seguinte comando:

gcloud container clusters update CLUSTER_NAME \
    --location=CLUSTER_LOCATION\
    --update-labels=canary=true

Substitua:

A flag --update-labels=canary=true instrui o GKE a aplicar o rótulo canary ao cluster .

Para mais informações sobre como adicionar um rótulo a um cluster, consulte Adicionar ou atualizar rótulos em clusters atuais.

Criar uma sequência de lançamento com etapas personalizadas

Uma sequência de lançamento define a ordem dos upgrades usando estágios. Para criar uma sequência de lançamento, primeiro crie um arquivo YAML que defina as etapas e, em seguida, crie um RolloutSequence.

Para garantir que a sequência capture todos os clusters, cada frota precisa incluir uma etapa de captura de tudo (uma etapa sem um seletor de rótulo). Essa etapa de captura abrange todos os clusters restantes que o GKE não selecionou nas etapas anteriores. Se você atribuir um único cluster a várias etapas em um RolloutSequence, para resolver conflitos, o GKE vai atribuir o cluster apenas à primeira etapa.

A configuração de exemplo a seguir cria três estágios:

  • A primeira etapa tem como destino todos os clusters na frota dev. Após a conclusão do upgrade, há um tempo de imersão de sete dias (um valor de 604800 segundos).
  • A segunda etapa segmenta clusters na frota prod que têm o rótulo canary=true. Após a conclusão do upgrade, há um tempo de imersão de sete dias.
  • A terceira etapa tem como destino os clusters restantes na frota prod. Após a conclusão do upgrade, há um tempo de imersão de sete dias.

  1. Salve o seguinte manifesto como rollout-sequence.yaml:

    - stage:
  fleet-projects:
  - projects/dev
  soak-duration: 604800s
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s
  label-selector: resource.labels.canary=='true'
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s

    Observe o seguinte:

    • stage: inclui uma frota ou um subconjunto de clusters em uma frota. Os clusters em estágios anteriores precisam ser totalmente atualizados e testados antes que a sequência prossiga para a próxima etapa. No entanto, se um cluster não concluir o upgrade 30 dias após o início do processo, o GKE iniciará o período de imersão.
    • fleet-projects: uma lista de frotas de onde selecionar clusters para esta etapa. É possível referenciar no máximo uma frota por etapa. Uma frota é identificada pelo projeto em que ela está hospedada. Esse projeto pode ser diferente daquele em que os clusters estão, se a frota tiver associações entre projetos. O formato para especificar um projeto da frota é projects/PROJECT_ID.
    • label-selector (opcional): seleciona um subconjunto de clusters das frotas especificadas. Esse campo usa a sintaxe da Common Expression Language (CEL) e precisa começar com resource.labels.
    • soak-duration: o tempo de espera após o upgrade de todos os clusters em uma etapa anterior antes de prosseguir para a próxima etapa. Expresso em segundos.

  2. Para criar a sequência de lançamento definida no manifesto rollout-sequence.yaml, execute o seguinte comando:

    gcloud beta container fleet rolloutsequences create ROLLOUT_SEQUENCE_NAME \
    --display-name=DISPLAY_NAME \
    --stage-config=rollout-sequence.yaml

    Substitua:

    • ROLLOUT_SEQUENCE_NAME: um identificador imutável que está em conformidade com as especificações RFC-1034, por exemplo, test-rollout-sequence.
    • DISPLAY_NAME: uma string legível para humanos para sua sequência de lançamento.

Verificar o status de um lançamento

Depois de configurar uma sequência de lançamento, o sistema cria automaticamente objetos Rollout para gerenciar upgrades. É possível observar e acompanhar o progresso desses objetos usando comandos da CLI do Google Cloud.

Listar lançamentos

Para listar todos os lançamentos ativos e históricos no projeto de host da sequência de lançamento, execute o comando a seguir:

gcloud beta container fleet rollouts list --project=HOST_PROJECT_ID

Substitua HOST_PROJECT_ID pelo ID do projeto host da sequência de lançamento.

É possível omitir a flag --project=HOST_PROJECT_ID se você já estiver no projeto em que a sequência de lançamento está hospedada.

O resultado será o seguinte:

NAME                                              STATE      CREATE_TIME
05eb251e4f19269e23-node-1-33-5-gke-1201000-t7mqd  COMPLETED  2025-10-30T20:07:46
05eb251e4f19269e23-kcp-1-33-5-gke-1201000-djwst   COMPLETED  2025-10-30T18:07:06
05eb251e4f19269e23-node-1-33-5-gke-1125000-6bxvu  COMPLETED  2025-10-23T17:46:54
05eb251e4f19269e23-kcp-1-33-5-gke-1125000-2f6ct   RUNNING    2025-10-23T16:41:33

Na saída anterior, os nomes de lançamento que contêm kcp se referem a upgrades do plano de controle, e os nomes que contêm node se referem a upgrades de nós. O segmento do nome do lançamento após kcp ou node é derivado da versão do GKE.

Descrever um lançamento

Para informações detalhadas sobre um lançamento específico, incluindo a versão de destino, o estado e quais clusters foram atualizados, use o comando describe com o ID do lançamento obtido no comando anterior:

gcloud beta container fleet rollouts describe ROLLOUT_ID \
  --project=HOST_PROJECT_ID

Substitua:

  • ROLLOUT_ID: o ID do lançamento que você recebeu ao listar os lançamentos.
  • HOST_PROJECT_ID: o ID do projeto em que sua sequência de lançamento é hospedada.

Exemplo:

gcloud beta container fleet rollouts describe 927e9a989930cf3b55-kcp-1-32-4-gke-1106006 \
  --project=my-hostfleet

O resultado será o seguinte:

createTime: '2025-05-26T11:47:29.909959672Z'
membershipStates:
  projects/dev-project-id/locations/us-central1/memberships/c-1:
    lastUpdateTime: '2025-05-26T12:20:55.601542481Z'
    targets:
    - cluster:   projects/dev-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-1234567890-abcdefg-hijklm-nopqrst
      state: SUCCEEDED
    stageAssignment: 1
  projects/dev-project-id/locations/us-central1/memberships/c-2:
    lastUpdateTime: '2025-05-26T12:22:57.151203493Z'
    targets:
    - cluster:   projects/dev-project-id/locations/us-central1/clusters/c-2
      operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-987654321-ghijkl-mno-pqr-stu-vwxyz
      state: SUCCEEDED
    stageAssignment: 1
  projects/prod-project-id/locations/us-central1/memberships/c-1:
    lastUpdateTime: '2025-05-26T13:03:34.134308942Z'
    targets:
    - cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-567891234-efghij-klm-nopq-rstu-vwxyz
      state: SUCCEEDED
    stageAssignment: 2
  projects/prod-project-id/locations/us-central1/memberships/c-2:
    lastUpdateTime: '2025-05-26T13:06:34.025261641Z'
    targets:
    - cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-765432198-01a7b896-67c2-523-6fjjh4-icmdydh
      state: SUCCEEDED
    stageAssignment: 2
name: projects/user-hostfleet/locations/global/rollouts/05eb251e4f19269e23-kcp-1-32-4-gke-1106006
rolloutSequence: projects/project-id/locations/global/rolloutSequences/my-sequence
state: COMPLETED
updateTime: '2025-07-22T07:36:51.052691989Z'
versionUpgrade:
  desiredVersion: 1.32.4-gke.1106006
  type: TYPE_CONTROL_PLANE
stages:
- state: COMPLETED
  endTime: '2025-05-26T12:22:28.828506491Z'
  stageNumber: 1
  startTime: '2025-05-26T11:48:28.772658427Z'
  soakDuration: 600s
- state: COMPLETED
  endTime: '2025-05-26T13:06:20.026390832Z'
  stageNumber: 2
  startTime: '2025-05-26T12:32:38.419372153Z'
  soakDuration: 600s

Informações de status para um lançamento

Ao descrever um lançamento, os campos stages e membershipStates da saída fornecem o status de progresso de cada estágio e cluster dentro desse estágio, respectivamente.

A tabela a seguir lista os possíveis status de uma etapa:

Status Descrição
PENDING O upgrade ainda não começou para esta etapa.
RUNNING O upgrade está em andamento para esta etapa. Se você tiver configurado uma janela de manutenção para os clusters na etapa, o GKE vai esperar que ela seja aberta antes de fazer upgrade dos clusters.
SOAKING Todos os clusters nesta etapa concluíram os upgrades, e a etapa está no período de espera configurado.
FORCED_SOAKING O upgrade levou mais que o tempo máximo (30 dias) e, portanto, o GKE iniciou a fase de imersão. O upgrade ainda continua nos clusters restantes.
COMPLETED A fase de absorção terminou, e o lançamento prossegue para a próxima etapa.

A tabela a seguir lista os possíveis status de um cluster em uma sequência:

Status Descrição
PENDING O upgrade está pendente neste cluster.
INELIGIBLE Este cluster não está qualificado para o upgrade, possivelmente devido a uma discrepância de versão. O motivo da desqualificação é fornecido na saída.
RUNNING O upgrade está em andamento neste cluster.
SUCCEEDED O upgrade foi concluído neste cluster.
FAILED O upgrade falhou neste cluster. Os destinos com falha são repetidos indefinidamente enquanto a etapa está ativa (no estado RUNNING ou FORCED_SOAKING).

Gerenciar uma sequência de lançamento

É possível controlar os upgrades automáticos de cluster com o sequenciamento de lançamento de várias maneiras, conforme explicado nas seções a seguir.

Listar suas sequências de lançamento

Para listar todas as sequências de lançamento no projeto host, execute o seguinte comando:

gcloud beta container fleet rolloutsequences list --project=HOST_PROJECT_ID

Substitua HOST_PROJECT_ID pelo ID do projeto host da sequência de lançamento.

Descrever uma sequência de lançamento

Para conferir os detalhes de uma sequência de lançamento específica, execute o seguinte comando:

gcloud beta container fleet rolloutsequences describe ROLLOUT_SEQUENCE_NAME \
  --project=HOST_PROJECT_ID

Substitua:

  • ROLLOUT_SEQUENCE_NAME: o nome da sequência de lançamento.
  • HOST_PROJECT_ID: o ID do projeto host da sua sequência de lançamento.

O resultado será o seguinte:

createTime: '2025-10-23T16:40:16.403871189Z'
displayName: my-display-name
name: projects/HOST_PROJECT_ID/locations/global/rolloutSequences/ROLLOUT_SEQUENCE_NAME
stages:
- clusterSelector:
    labelSelector: resource.labels.canary=='true'
  fleetProjects:
  - projects/FLEET_PROJECT_ID
  soakDuration: 600s
- fleetProjects:
  - projects/FLEET_PROJECT_ID
  soakDuration: 300s
uid: 5c5b2ac8-9d76-45f9-92ca-5e6bd3fbcaef
updateTime: '2025-10-23T17:11:57.285678399Z'

Modificar uma sequência de lançamento

É possível modificar uma sequência de lançamento editando o arquivo de configuração YAML em que você definiu a sequência. Por exemplo, é possível atualizar o tempo de imersão de um estágio ou atualizar o estágio para mudar a ordem dos upgrades. Depois de editar o arquivo, aplique as mudanças.

Por exemplo, se você definiu a sequência de lançamento original em um arquivo chamado rollout-sequence.yaml, edite o arquivo conforme necessário. Em seguida, execute o seguinte comando:

gcloud beta container fleet rolloutsequences update test-rollout-sequence \
  --display-name="My Updated Rollout Sequence" \
  --stage-config=rollout-sequence.yaml

Excluir uma sequência de lançamento

Para excluir uma sequência de lançamento, execute o seguinte comando:

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME \
  --project=HOST_PROJECT_ID

Substitua:

  • ROLLOUT_SEQUENCE_NAME pelo nome da sequência de lançamento.
  • HOST_PROJECT_ID com o ID do projeto host da sequência de lançamento.

Quando você exclui uma sequência de lançamento, todos os lançamentos em andamento dessa sequência são cancelados. Os clusters que faziam parte da sequência revertem ao comportamento padrão de upgrade automático do canal de lançamento inscrito.

Migrar uma sequência de lançamento para usar etapas personalizadas

Se você usa a versão de disponibilidade geral da sequência de lançamento baseada em frota, é possível migrar para uma sequência que usa estágios personalizados criando um novo RolloutSequence que faz referência às suas frotas atuais.

Antes de migrar a sequência, recomendamos que você faça uma cópia da configuração atual de sequência de lançamento.

Para migrar sua sequência de lançamento, siga estas etapas:

  1. Crie um projeto Google Cloud dedicado para hospedar sua sequência de lançamento. Esse projeto normalmente não faz parte da sequência. Ou seja, ele não contém frotas ou clusters que fazem parte da sequência.
  2. Se você quiser que a sequência de lançamento inclua clusters específicos em uma frota, adicione rótulos a esses clusters. Esta etapa é opcional.

  3. Siga as instruções em Criar uma sequência de lançamento com etapas personalizadas.

    Por exemplo, o manifesto a seguir, chamado rollout-sequence-migrate.yaml, faz referência às frotas atuais em uma sequência de lançamento anterior. Esse manifesto descreve três estágios, incluindo um estágio de canary na frota prod:

    - stage:
  fleet-projects:
  - projects/dev
  soak-duration: 604800s
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s
  label-selector: canary=true
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s

Imediatamente após definir um novo RolloutSequence para suas frotas, o GKE começa a fazer upgrade das frotas de acordo com a nova sequência e remove a configuração anterior.

Migrar uma sequência de lançamento com estágios personalizados para a sequência de lançamento anterior

Esta seção descreve como reverter da sequenciamento de lançamento com etapas personalizadas para o modelo de sequenciamento baseado em frota disponível de maneira geral. Esse processo envolve excluir o novo RolloutSequence e restaurar a configuração original baseada em frota.

Evitar upgrade fora de ordem durante a migração

Para evitar upgrades não intencionais ou fora de ordem enquanto você reconfigura sua sequência, aplique uma exclusão de manutenção aos seus clusters de produção. Essa etapa pausa temporariamente todos os upgrades automáticos nesses clusters. Por exemplo, é possível configurar uma exclusão de manutenção do tipo no upgrades nos clusters de produção.

Excluir a sequência de lançamento

Exclua o objeto RolloutSequence que gerencia seus clusters. Essa exclusão desativa o recurso de etapas personalizadas.

Para excluir o RolloutSequence, execute o seguinte comando:

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME

Substitua ROLLOUT_SEQUENCE_NAME pelo nome da sequência de lançamento.

Restaurar a configuração anterior da sequência de lançamento (sem etapas personalizadas)

Depois de excluir o RolloutSequence, é possível restaurar a configuração original baseada em frota. Esse processo envolve recriar os recursos clusterupgrade com os parâmetros originais, incluindo os links upstreamFleet e os tempos de imersão para cada frota na sua sequência. Para mais informações, consulte Criar uma sequência de lançamento.

Remover as exclusões de manutenção

Depois de restaurar a configuração original de sequenciamento de lançamento com base em frota, remova a exclusão de manutenção aplicada na primeira etapa desta seção. O GKE retoma os upgrades automáticos, agora regidos pela sequência restaurada com base na frota.

A seguir