Sequencie a implementação de atualizações de clusters com fases personalizadas

Este documento mostra como gerir as atualizações de clusters do Google Kubernetes Engine (GKE) que usam a implementação faseada com etapas personalizadas. Cria uma sequência de implementação usando grupos de clusters organizados em frotas e, opcionalmente, subconjuntos de clusters dessas frotas. Pode escolher o tempo de teste de resistência que quer após as atualizações do cluster estarem concluídas num grupo (máximo de 30 dias). Pode incluir clusters do Autopilot e padrão. Para mais informações sobre o funcionamento desta funcionalidade, consulte o artigo Acerca da implementação sequencial com etapas personalizadas.

Se gerir implementações em várias frotas, recomendamos que use um projeto dedicado para alojar os seus objetos RolloutSequence. Este projeto funciona como o principal e o coordenador das implementações na sequência. Normalmente, este projeto não faz parte da sequência, ou seja, não contém frotas nem clusters que façam parte da sequência.

Antes de começar

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

    gcloud init

    Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

  • Certifique-se de que tem clusters do Autopilot ou Standard existentes. Para criar um novo cluster, consulte o artigo Crie um cluster do Autopilot.

  • (Opcional) Se ainda não tiver um projeto Google Cloud dedicadoRolloutSequence para alojar a sua configuração, crie um através da Google Cloud consola ou de outro método.

  • Certifique-se de que ativou as APIs necessárias para frotas. Estas APIs têm de estar ativadas nos projetos de anfitriões da frota para criar qualquer tipo de sequência de implementação. Para o projeto anfitrião da sequência de implementação, ative a API gkehub.googleapis.com.

Funções necessárias

Para criar um projeto, precisa da função de criador de projetos (roles/resourcemanager.projectCreator), que contém a autorização resourcemanager.projects.create. Saiba como conceder funções.

Para criar ou modificar uma sequência de implementação, tem de ter a função do IAM de editor de frotas (roles/gkehub.editor) em cada projeto de anfitrião da frota na sequência de implementação e no projeto de anfitrião da sequência de implementação. Esta função oferece as seguintes autorizações:

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

Estas autorizações permitem-lhe criar, aceder e modificar objetos RolloutSequence e usar frotas na sequência de implementação.

Se precisar de registar ou anular o registo de clusters numa frota, precisa de todas as seguintes autorizações:

Para mais informações sobre as funções de IAM com menos privilégios necessárias para diferentes tarefas, consulte o artigo Receba sugestões de funções predefinidas com a ajuda do Gemini.

Configure uma sequência de implementação

Para criar uma sequência de implementação, os seus clusters têm de estar organizados em grupos de frotas. Também pode criar fases detalhadas que podem segmentar subconjuntos específicos de clusters numa frota através de etiquetas do Kubernetes. Para orientações sobre como organizar os seus clusters, consulte o exemplo do banco da comunidade. Depois de organizar os clusters em grupos e, opcionalmente, etiquetá-los, pode criar uma sequência de implementação definindo a lista ordenada de fases e o tempo de teste para cada grupo.

Organize clusters em frotas

Numa sequência de implementação, recomendamos que inscreva todos os clusters no mesmo canal de lançamento. Se os clusters não estiverem inscritos no mesmo canal, o GKE seleciona uma versão do canal mais conservador na sequência. Por exemplo, se os clusters estiverem inscritos nos canais Estável e Regular, o GKE escolhe a versão do canal Estável. Também recomendamos que todos os clusters executem a mesma versão secundária para serem elegíveis para a mesma versão de destino de atualização automática.

Se já tiver organizado os seus clusters em frotas, pode ignorar os passos seguintes e avançar para a secção Crie subconjuntos de clusters.

  1. Agrupe os seus clusters em frotas. Pode organizar os seus clusters por ambientes de implementação, como Teste, Preparação e Produção (recomendado).
  2. Registe cada cluster numa frota com base no agrupamento escolhido.

Crie subconjuntos de clusters (opcional)

Para que uma fase na sua sequência de implementação segmente clusters específicos, tem de etiquetar esses clusters.

Por exemplo, para testar uma nova versão num pequeno subconjunto de clusters antes de uma implementação completa, pode aplicar uma etiqueta canary a esses clusters. Para adicionar a etiqueta canarytrue com o valor true a um cluster através da CLI do Google Cloud, execute o seguinte comando:

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

Substitua o seguinte:

O comando --update-labels=canary=true indica ao GKE que aplique a etiqueta canary ao cluster .

Para mais informações sobre como adicionar uma etiqueta a um cluster, consulte o artigo Adicione ou atualize etiquetas para clusters existentes.

Crie uma sequência de implementação com fases personalizadas

Uma sequência de implementação define a ordem das atualizações através de fases. Para criar uma sequência de implementação, primeiro tem de criar um ficheiro YAML que defina as fases e, em seguida, criar um RolloutSequence.

Para garantir que a sequência capta todos os clusters, cada frota tem de incluir uma fase geral (uma fase sem um seletor de etiquetas). Esta fase geral captura todos os restantes clusters que o GKE não selecionou nas fases anteriores. Se atribuir um único cluster a várias fases num único RolloutSequence, para resolver conflitos, o GKE atribui implicitamente o cluster apenas à fase mais antiga.

A configuração de exemplo seguinte cria três fases:

  • A primeira fase segmenta todos os clusters na frota dev. Após a conclusão da atualização, existe um período de estabilização de 7 dias (um valor de 604800 segundos).
  • A segunda fase segmenta os clusters na frota prod que têm a etiqueta canary=true. Após a conclusão da atualização, existe um período de estabilização de 7 dias.
  • A terceira fase segmenta os restantes clusters na frota prod. Após a conclusão da atualização, existe um período de teste de 7 dias.

  1. Guarde 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

    Tenha em conta o seguinte:

    • stage: inclui uma frota ou um subconjunto de clusters numa frota. Os clusters nas fases anteriores têm de ser totalmente atualizados e testados antes de a sequência avançar para a fase seguinte. No entanto, se um cluster não tiver terminado a atualização 30 dias após o início do processo de atualização, o GKE inicia o período de saturação.
    • fleet-projects: uma lista de frotas a partir da qual pode selecionar clusters para esta fase. Pode referenciar, no máximo, uma frota por fase. Uma frota é identificada pelo projeto onde está alojada. Este projeto pode ser um projeto diferente do projeto onde os clusters estão localizados, se a frota contiver associações entre projetos. O formato para especificar um projeto de frota é projects/PROJECT_ID.
    • label-selector (opcional): seleciona um subconjunto de clusters das frotas especificadas. Este campo usa a sintaxe do Idioma de expressão comum (IEC) e tem de começar com resource.labels.
    • soak-duration: o tempo de espera após a atualização de todos os clusters numa fase anterior antes de avançar para a fase seguinte. Expresso em segundos.

  2. Para criar a sequência de implementação que definiu no rollout-sequence.yamlmanifesto, execute o seguinte comando:

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

    Substitua o seguinte:

    • ROLLOUT_SEQUENCE_NAME: um identificador imutável em conformidade com as especificações do RFC-1034, por exemplo, test-rollout-sequence.
    • DISPLAY_NAME: uma string legível para a sua sequência de implementação.

Verifique o estado de uma implementação

Depois de configurar uma sequência de implementação, o sistema cria automaticamente Rollout objetos para gerir as atualizações. Pode observar e acompanhar o progresso destes objetos através de comandos da Google Cloud CLI.

Liste implementações

Para apresentar uma lista de todas as implementações ativas e do histórico no projeto anfitrião da sequência de implementação, execute o seguinte comando:

gcloud beta container fleet rollouts list --project=HOST_PROJECT_ID

Substitua HOST_PROJECT_ID pelo ID do projeto anfitrião da sequência de implementação.

Pode omitir a flag --project=HOST_PROJECT_ID se já estiver no projeto onde a sequência de implementação está alojada.

O resultado é semelhante ao 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 implementação que contêm kcp referem-se a atualizações do plano de controlo e os nomes que contêm node referem-se a atualizações de nós. O segmento do nome da implementação após kcp ou node é derivado da versão do GKE.

Descreva uma implementação

Para obter informações detalhadas sobre uma implementação específica, incluindo a versão de destino, o estado e os clusters que foram atualizados, use o comando describe com o ID de implementação que obteve no comando anterior:

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

Substitua o seguinte:

  • ROLLOUT_ID: o ID de implementação que obteve quando listou as implementações.
  • HOST_PROJECT_ID: o ID do projeto onde a sequência de implementação está alojada.

Por exemplo:

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

O resultado é semelhante ao 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 estado de uma implementação

Quando descreve uma implementação, os campos stages e membershipStates do resultado fornecem o estado de progresso de cada fase e cluster nessa fase, respetivamente.

A tabela seguinte indica os potenciais estados de uma fase:

Estado Descrição
PENDING A atualização ainda não começou para esta fase.
RUNNING A atualização está em curso para esta fase. Se configurou um período de manutenção para os clusters na fase, o GKE aguarda que o período seja aberto antes de atualizar os clusters.
SOAKING Todos os clusters nesta fase concluíram as respetivas atualizações e a fase está no respetivo período de saturação configurado.
FORCED_SOAKING A atualização demorou mais do que o tempo máximo de atualização (30 dias) e, por isso, o GKE iniciou a fase de saturação à força. A atualização continua nos restantes clusters.
COMPLETED A fase de teste de estabilidade foi concluída e a implementação avança para a fase seguinte.

A tabela seguinte apresenta os potenciais estados de um cluster numa sequência:

Estado Descrição
PENDING A atualização está pendente neste cluster.
INELIGIBLE Este cluster não é elegível para a atualização, possivelmente devido a uma discrepância de versão. O motivo da inelegibilidade é fornecido no resultado.
RUNNING A atualização está em curso neste cluster.
SUCCEEDED A atualização foi concluída com êxito neste cluster.
FAILED A atualização falhou neste cluster. As segmentações com falhas são repetidas indefinidamente enquanto a respetiva fase estiver ativa (num estado RUNNING ou FORCED_SOAKING).

Faça a gestão de uma sequência de implementação

Pode controlar as atualizações automáticas de clusters com a sequenciação da implementação de várias formas, conforme explicado nas secções seguintes.

Apresente uma lista das suas sequências de implementação

Para apresentar uma lista de todas as sequências de implementação no seu projeto anfitrião, execute o seguinte comando:

gcloud beta container fleet rolloutsequences list --project=HOST_PROJECT_ID

Substitua HOST_PROJECT_ID pelo ID do projeto anfitrião da sequência de implementação.

Descreva uma sequência de implementação

Para ver os detalhes de uma sequência de implementação específica, execute o seguinte comando:

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

Substitua o seguinte:

  • ROLLOUT_SEQUENCE_NAME: o nome da sequência de implementação.
  • HOST_PROJECT_ID: o ID do projeto anfitrião da sequência de implementação.

O resultado é semelhante ao 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'

Modifique uma sequência de implementação

Pode modificar uma sequência de implementação existente editando o ficheiro de configuração YAML onde definiu a sequência. Por exemplo, pode atualizar o tempo de imersão de um palco ou atualizar o palco para alterar a ordem das atualizações. Depois de editar o ficheiro, aplique as alterações.

Por exemplo, se definiu a sequência de implementação original num ficheiro denominado rollout-sequence.yaml, edite o ficheiro 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

Elimine uma sequência de implementação

Para eliminar uma sequência de implementação, execute o seguinte comando:

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

Substitua o seguinte:

  • ROLLOUT_SEQUENCE_NAME com o nome da sequência de implementação.
  • HOST_PROJECT_ID com o ID do projeto anfitrião da sua sequência de implementação.

Quando elimina uma sequência de implementação, todas as implementações em curso dessa sequência são canceladas. Os clusters que faziam parte da sequência revertem para o comportamento de atualização automática predefinido do respetivo canal de lançamento inscrito.

Migre uma sequência de implementação existente para usar fases personalizadas

Se usar a versão de implementação baseada na frota geralmente disponível da sequenciação, pode migrar para uma sequência que use fases personalizadas criando um novo RolloutSequence que faça referência às suas frotas existentes.

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

Para migrar a sequência de implementação, conclua os seguintes passos:

  1. Crie um projeto Google Cloud dedicado para alojar a sua sequência de implementação. Normalmente, este projeto não faz parte da sequência, ou seja, o projeto não contém frotas nem clusters que façam parte da sequência.
  2. Se quiser que a sequência de implementação inclua clusters específicos numa frota, adicione etiquetas a esses clusters. Este passo é opcional.

  3. Siga as instruções em Crie uma sequência de implementação com fases personalizadas.

    Por exemplo, o seguinte manifesto, com o nome rollout-sequence-migrate.yaml, faz referência às implementações existentes numa sequência de implementação anterior. Este manifesto descreve três fases, incluindo uma fase 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 as suas frotas, o GKE começa a atualizar as frotas de acordo com a nova sequência e remove a configuração anterior.

Migre uma sequência de implementação com fases personalizadas para a sequência de implementação anterior

Esta secção descreve como reverter a sequenciação de implementação com fases personalizadas para o modelo de sequenciação baseado na frota geralmente disponível. Este processo envolve a eliminação do novo RolloutSequence e o restauro da configuração original baseada na frota.

Impeça a atualização fora de ordem durante a migração

Para evitar atualizações não intencionais ou desordenadas enquanto reconfigura a sequência, aplique uma exclusão de manutenção aos clusters de produção. Este passo pausa temporariamente todas as atualizações automáticas nesses clusters. Por exemplo, pode configurar uma exclusão de manutenção do tipo no upgrades nos seus clusters de produção.

Elimine a sequência de implementação

Elimine o objeto RolloutSequence que gere os seus clusters. Esta eliminação desativa a funcionalidade de etapas personalizadas.

Para eliminar o RolloutSequence, execute o seguinte comando:

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME

Substitua ROLLOUT_SEQUENCE_NAME pelo nome da sua sequência de implementação.

Restaure a configuração da sequência de implementação anterior (sem fases personalizadas)

Depois de eliminar o RolloutSequence, pode restaurar a configuração original baseada na frota. Este processo envolve a recriação das funcionalidades clusterupgrade com os respetivos 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 o artigo Crie uma sequência de implementação.

Remova as exclusões de manutenção

Depois de restaurar a configuração de sequenciação de implementação baseada na frota original, remova a exclusão de manutenção que aplicou no primeiro passo desta secção. O GKE retoma as atualizações automáticas, agora regidas pela sequência baseada na frota restaurada.

O que se segue