Sequência do lançamento de upgrades de cluster

Neste documento, mostramos como gerenciar upgrades de cluster do GKE com o sequenciamento de lançamentos. Para saber mais sobre como esse recurso funciona, consulte Sobre upgrades de cluster com sequenciamento de lançamento.

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.
  • Verifique se você ativou as APIs necessárias para as frotas. Essas APIs precisam ser ativadas nos projetos de host da frota para criar qualquer tipo de sequência de implantação.
  • Para instruções do Terraform, use a versão 5.13.0 ou posterior do provedor google.

Funções exigidas

Para criar ou modificar uma sequência de implantação, você precisa receber o papel do IAM roles/gkehub.editor em cada projeto na sequência de implantação. O papel Editor da frota (antigo Editor do GKE Hub) fornece as permissões gkehub.features.create e gkehub.fleet.update, que são necessárias para acessar e modificar recursos relacionados à frota entre projetos. Esse papel fornece as permissões necessárias para definir a estratégia de upgrade, acessar e modificar recursos relevantes e iniciar e gerenciar o processo de implantação.

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 menos privilégios necessários para diferentes tarefas, consulte Receber sugestões de papéis predefinidos com a ajuda do Gemini.

Configurar uma sequência de lançamento

Neste documento, explicamos como criar uma sequência de lançamento usando grupos de clusters organizados por frotas.

É possível criar uma sequência de até cinco grupos de clusters e escolher o tempo de teste de permanência que 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 criar uma sequência de lançamento, os clusters precisam ser organizados em grupos de frotas. Para orientações sobre como organizar os clusters, consulte o exemplo do banco comunitário. Depois de organizar os clusters em grupos, crie uma sequência de lançamento definindo as relações de grupo upstream e o tempo de permanência de cada grupo. Upstream, na sequência de lançamento, refere-se ao grupo anterior e downstream, ao próximo.

Organizar os clusters em grupos

Em uma sequência de lançamento, todos os clusters em todos os grupos precisam estar registrados no mesmo canal de lançamento e na mesma versão secundária. Se esses requisitos não forem atendidos e houver discrepâncias de versão entre clusters, isso poderá causar problemas com o lançamento da versão. Para mais informações, consulte Qualificação para o lançamento com base na frota.

Se você já tiver organizado os clusters em frotas, pule as etapas a seguir e continue para Criar uma sequência de lançamento.

  1. Agrupe os clusters em frotas. É possível organizar os clusters por ambientes de implantação, como teste, preparo e produção, conforme mostrado no exemplo de sequência de lançamento com base em frota.

  2. Registre cada cluster com uma frota com base no agrupamento escolhido.

Criar uma sequência de lançamento

Uma sequência de lançamento é organizada como uma lista vinculada com até cinco elementos.

Ao criar uma sequência de lançamento, você define as seguintes propriedades para cada frota de clusters:

  • Grupo upstream:a frota upstream, que qualifica novas versões para o grupo downstream. Não defina um grupo upstream para o primeiro grupo em uma sequência.

  • Tempo de imersão: o tempo de imersão de um grupo é o momento entre o momento em que os upgrades foram concluídos (ou o lançamento levou 30 dias) e o momento em que eles podem começar no grupo downstream. Para saber mais, consulte Como funciona a qualificação de versões em uma sequência de lançamento.

Console

  1. Acesse a página Sequência de lançamento no console do Google Cloud .

    Acessar o sequenciamento de lançamento

  2. Clique em Criar sequência de lançamento.

  3. No painel Criar uma sequência de lançamento, selecione as duas primeiras frotas na sequência:

    1. Na seção Frota 1, selecione a primeira frota na sequência.
    2. Na seção Tempo de permanência da frota upstream, defina o tempo de permanência da primeira frota usando os campos Dias, Horas e Minutos.
    3. Na seção Frota 2, selecione a segunda frota na sequência.
    4. Clique em Criar.

  4. Opcional: se você quiser ter três ou mais frotas nessa sequência de lançamento, siga estas etapas adicionais:

    1. No Gráfico de lançamento, clique no elemento da segunda frota.
    2. Clique em Adicionar frota downstream.
    3. Na seção Tempo de permanência da frota upstream, defina o tempo de permanência da segunda frota usando os campos Dias, Horas e Minutos.
    4. Na seção Próxima frota na sequência, selecione a terceira frota na sequência.
    5. Clique em Salvar.
    6. Repita as etapas anteriores se quiser adicionar uma quarta ou quinta frota.

gcloud

As instruções a seguir usam o comando gcloud container fleet clusterupgrade update, mas é possível definir as mesmas propriedades com o comando gcloud container fleet clusterupgrade create.

Para cada um dos comandos a seguir, substitua SOAK_TIME pelo tempo de imersão da frota que você está atualizando.

Criar uma sequência de lançamento

  1. Defina o tempo de imersão da primeira frota na sequência:

    gcloud container fleet clusterupgrade update \
    --default-upgrade-soaking=SOAK_TIME \
    --project=FIRST_FLEET_PROJECT_ID

    Substitua FIRST_FLEET_PROJECT_ID pelo ID do projeto host da frota.

  2. Defina a frota upstream e o tempo de permanência da segunda frota na sequência:

    gcloud container fleet clusterupgrade update \
    --upstream-fleet=FIRST_FLEET_PROJECT_ID \
    --default-upgrade-soaking=SOAK_TIME \
    --project=SECOND_FLEET_PROJECT_ID

    Substitua FIRST_FLEET_PROJECT_ID pelo ID do primeiro projeto host da frota e SECOND_FLEET_PROJECT_ID pelo ID do projeto host da frota.

  3. Opcional: se você quiser ter mais de duas frotas em uma sequência de lançamento, defina a frota upstream para as próximas frotas na sequência.

    O comando a seguir define a frota upstream para a terceira frota na sequência. Se quiser adicionar uma quarta ou quinta frota, repita esta etapa, seguindo o mesmo padrão para substituir as variáveis pelos IDs dos projetos dos respectivos hosts de frota (frota anterior e próxima frota).

    Defina a frota upstream para a próxima frota na sequência:

    gcloud container fleet clusterupgrade update \
    --upstream-fleet=SECOND_FLEET_PROJECT_ID \
    --default-upgrade-soaking=SOAK_TIME \
    --project=THIRD_FLEET_PROJECT_ID

    Substitua SECOND_FLEET_PROJECT_ID pelo ID do projeto host da segunda frota e THIRD_FLEET_PROJECT_ID pelo ID do projeto host da frota.

Terraform

Nesta seção, mostramos como criar uma sequência baseada em frota usando o Terraform. Também é possível usar esse recurso para atualizar a sequência. Para saber mais, consulte a documentação de referência para google_gke_hub_feature.

Para cada um dos comandos a seguir, substitua SOAK_TIME pelo tempo de imersão da frota que você está atualizando.

Criar uma sequência de lançamento

  1. Adicione o seguinte bloco à sua configuração do Terraform para definir o tempo de imersão para a primeira frota na sequência:

    resource "google_gke_hub_feature" "feature" {
  name = "clusterupgrade"
  location = "global"
  spec {
    clusterupgrade {
      upstream_fleets = []
      post_conditions {
        soaking = "SOAK_TIME"
      }
    }
  }
  project = "FIRST_FLEET_PROJECT_ID"
}

    Substitua FIRST_FLEET_PROJECT_ID pelo ID do projeto host da frota.

  2. Adicione o seguinte bloco à sua configuração do Terraform para definir a frota upstream e o tempo de imersão para a segunda frota na sequência:

    resource "google_gke_hub_feature" "feature" {
  name = "clusterupgrade"
  location = "global"
  spec {
    clusterupgrade {
      upstream_fleets = ["FIRST_FLEET_PROJECT_ID"]
      post_conditions {
        soaking = "SOAK_TIME"
      }
    }
  }
  project = "SECOND_FLEET_PROJECT_ID"
}

    Substitua FIRST_FLEET_PROJECT_ID pelo ID do primeiro projeto host da frota e SECOND_FLEET_PROJECT_ID pelo ID do projeto host da frota.

  3. Opcional: se você quiser ter três frotas em uma sequência de lançamento, adicione o bloco a seguir à configuração do Terraform para definir a frota upstream na sequência:

    resource "google_gke_hub_feature" "feature" {
  name = "clusterupgrade"
  location = "global"
  spec {
    clusterupgrade {
      upstream_fleets = ["SECOND_FLEET_PROJECT_ID"]
      post_conditions {
        soaking = "SOAK_TIME"
      }
    }
  }
  project = "THIRD_FLEET_PROJECT_ID"
}

    Substitua SECOND_FLEET_PROJECT_ID pelo ID do projeto host da segunda frota e THIRD_FLEET_PROJECT_ID pelo ID do projeto host da frota.

    Repita essa etapa se quiser adicionar uma quarta ou quinta frota.

Verificar o status de uma sequência de lançamento

É possível verificar o status de uma sequência de lançamento com um dos seguintes métodos:

  • Monitorar uma representação visual de uma sequência de lançamento no console do Google Cloud (prévia).
  • Use a gcloud CLI ou a API GKE Hub para verificar o status de uma sequência de lançamento.

Para conferir uma sequência de lançamento com qualquer um dos métodos anteriores, verifique se você tem o papel do IAM roles/gkehub.viewer para cada projeto host da frota, principalmente se a sequência incluir frotas em projetos diferentes. Se você não tiver as permissões necessárias para um projeto, vai receber um erro ao verificar o status da sequência.

Monitorar uma sequência de lançamento no console do Google Cloud

  1. Acesse a página Sequência de lançamento no console do Google Cloud .

    Acessar o sequenciamento de lançamento

  2. Confira a sequência na seção Monitorar a sequência de lançamento. Se você não encontrar uma sequência de lançamento, mude para uma sequência de lançamento diferente ou crie uma, se ainda não tiver feito isso.

Como usar o console para monitorar uma sequência de lançamento

Nela, você pode conferir a sequência de lançamento associada à frota do seu projeto. Para conferir o progresso de uma sequência de lançamento, faça o seguinte:

  • Confira toda a sequência de lançamento ou os status de frotas e clusters individuais nessas frotas, além do tempo de imersão entre as frotas. Você também pode conferir a sequência em que não há upgrade ativo para verificar a configuração dela.
  • Filtre por tipo de upgrade (plano de controle ou upgrade de nó) e versão específica (por exemplo, 1.31.6-gke.500).

É possível monitorar visualmente toda a sequência de lançamento enquanto o GKE faz upgrade de todos os clusters na sequência, qualificando uma nova versão em ambientes antes de fazer upgrade dos clusters do ambiente de produção. Durante o monitoramento, é possível gerenciar uma sequência de lançamento com a gcloud CLI, fazendo as mudanças necessárias.

Mudar para outra sequência de lançamento

Esta página mostra a sequência de lançamento se o projeto ativo no console doGoogle Cloud for um projeto de host da frota para uma frota registrada em uma sequência de lançamento.

Para conferir uma sequência de lançamento diferente, selecione um projeto host da frota associado a uma sequência de lançamento diferente no seletor de projetos na parte de cima da página.

Usar a CLI gcloud

É possível verificar o status de uma sequência de lançamento, uma frota na sequência ou clusters individuais em uma frota.

  • Para verificar o status de uma sequência de lançamento com base em frota, execute o seguinte comando:

    gcloud container fleet clusterupgrade describe \
    --show-linked-cluster-upgrade --project=FLEET_PROJECT_ID

    Substitua FLEET_PROJECT_ID pelo ID do projeto host de qualquer frota na sequência. Consulte a referência de gcloud container fleet clusterupgrade describe para ver uma lista completa de flags.

  • Para verificar o status de apenas uma frota na sequência, no comando anterior, substitua a flag --show-linked-cluster-upgrade pela flag --show-cluster-upgrade.

  • Para verificar o status de clusters individuais em uma frota, execute o seguinte comando no projeto host da frota e consulte a seção membershipStates:

    gcloud container fleet features describe clusterupgrade

A seção a seguir descreve as informações de status na saída resultante.

Informações de status para uma sequência de lançamento

Ao verificar o status do lançamento de uma versão, é possível ver o progresso de cada grupo e cluster dentro desse grupo.

Consulte a tabela a seguir para ver os status possíveis de um cluster ou grupo:

Status Para um único cluster Para uma frota
Não qualificado Este cluster não está qualificado para este upgrade Um ou mais clusters neste grupo não estão qualificados para este upgrade.
PENDENTE O upgrade está pendente no cluster ou em alguns dos pools de nós padrão ou grupos de nós em um cluster do Autopilot. O upgrade não foi iniciado em nenhum dos clusters no grupo.
IN_PROGRESS O upgrade está em andamento no cluster. O upgrade foi iniciado em pelo menos um cluster, mas não foi concluído em todos.
INICIANDO O upgrade foi concluído no cluster e não foi concluído. O upgrade foi concluído em todos os clusters e não foi concluído.
FORCED_SOAKING O upgrade levou mais que o tempo máximo (30 dias) e, portanto, o forçamos a entrar na fase de imersão. O upgrade ainda pode continuar no cluster. O upgrade levou mais que o tempo máximo (30 dias) e, portanto, o forçamos a entrar na fase de imersão. O upgrade ainda pode continuar nos clusters.
CONCLUIR O upgrade é tratado como "concluído", o que significa que ele foi concluído no cluster. O upgrade é tratado como "concluído" e pronto para ser consumido pelo grupo downstream, o que significa que ele foi concluído.

Na saída desses comandos, os atributos clusterUpgrade(s).spec e clusterUpgrade(s).state contêm outras informações sobre o upgrade de cluster, como tempo de imersão, modificações de upgrade de cluster e status do upgrade.

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.

Alterar o tempo de permanência em um grupo

É possível alterar o tempo de imersão padrão de um grupo ou de tempo para esse upgrade em uma versão específica. O máximo é de 30 dias.

Atualizar o tempo de imersão padrão

É possível atualizar o tempo de teste padrão no console Google Cloud (prévia) ou com a CLI gcloud.

Console

  1. Acesse a página Sequência de lançamento no console do Google Cloud .

    Acessar o sequenciamento de lançamento

  2. Confira a sequência na seção Monitorar a sequência de lançamento. Se você não encontrar uma sequência de lançamento, mude para uma sequência de lançamento diferente ou crie uma, se ainda não tiver feito isso.

  3. No Gráfico de lançamento, clique no elemento Tempo de espera depois do elemento da frota em que você quer atualizar o tempo de espera.

  4. Clique em Editar tempo de imersão.

  5. Na seção Definir um novo período de teste, insira um novo período usando os campos Dias, Horas e Minutos.

  6. Para salvar as configurações, clique em Salvar.

gcloud

Para mudar o tempo de permanência padrão de um grupo, use os comandos da CLI gcloud das instruções para Criar uma sequência de lançamento, omitindo as flags para definir o grupo upstream.

Modificar o tempo de imersão padrão

É possível alterar o tempo de imersão de um lançamento de versão específico para que seja diferente do tempo de imersão padrão para o grupo. Por exemplo, se você já tiver qualificado uma nova versão e estiver pronto para upgrades para o próximo grupo, defina o tempo de imersão como zero. Também é possível usá-lo se quiser mais tempo do que o padrão de imersão para qualificar uma versão específica.

Como o tempo de permanência é definido por grupo, se você quiser modificar o tempo de permanência para outros grupos nesta sequência, use o mesmo comando com o nome da frota substituído.

Para as instruções nesta seção, substitua as seguintes variáveis:

  • SOAK_TIME: o tempo de imersão a ser usado além do padrão. Por exemplo, "0d" se você quiser pular o tempo de imersão para um lançamento de versão.
  • UPGRADE_NAME: o tipo de upgrade, sendo k8s_control_plane para upgrades de plano de controle ou k8s_node para upgrades de nó.

  • VERSION: a versão do GKE em que você quer modificar o tempo de imersão padrão após a versão (por exemplo, 1.25.2-gke.400) ter sido implementada nesse grupo.

gcloud

Execute o comando a seguir no projeto host da frota em que você quer modificar o tempo de permanência usado para o lançamento de uma versão específica.

gcloud container fleet clusterupgrade update
    --add-upgrade-soaking-override=SOAK_TIME \
    --upgrade-selector=name=UPGRADE_NAME,version=VERSION

Terraform

Adicione o seguinte bloco gke_upgrades_overrides à configuração do Terraform no bloco clusterupgrade para substituir o tempo de imersão usado para o lançamento de uma versão específica:

gke_upgrade_overrides {
    upgrade {
      name = "UPGRADE_NAME"
      version = "VERSION"
    }
    post_conditions {
      soaking = "SOAK_TIME"
    }
  }

Atualizar os grupos em uma sequência de lançamento

É possível atualizar uma sequência de lançamento para adicionar, remover ou mudar a ordem dos grupos na sequência. Para fazer essas mudanças, atualize as associações entre grupos.

É possível realizar essas etapas no console do Google Cloud (prévia) ou com a CLI gcloud.

Console

  1. Acesse a página Sequência de lançamento no console do Google Cloud .

    Acessar o sequenciamento de lançamento

  2. Confira a sequência na seção Monitorar a sequência de lançamento. Se você não encontrar uma sequência de lançamento, mude para uma sequência de lançamento diferente ou crie uma, se ainda não tiver feito isso.

  3. No Gráfico de lançamento, clique nos elementos das frotas atuais na sequência. Depois de clicar nesses elementos, você pode realizar algumas das seguintes ações para fazer as mudanças:

    • Clique em Adicionar frota downstream.
    • Clique em Adicionar frota upstream.
    • Clique em Remover frota.

Você pode realizar ações como:

  • Adicione outra frota ao final da sequência de lançamento adicionando uma frota downstream à última frota da sequência.
  • Adicione outra frota ao início da sequência de lançamento adicionando uma frota upstream à primeira frota na sequência.
  • Mude a ordem das frotas na sequência de lançamento removendo e adicionando novamente com uma frota upstream ou downstream diferente.
  • Remova a primeira frota na sequência de lançamento.
  • Remova a última frota na sequência de lançamento.
  • Remova a frota do meio na sequência de lançamento depois de remover a primeira ou a última frota.

gcloud

Para adicionar ou mudar frotas upstream, use o comando gcloud container fleet clusterupgrade update com a sinalização --upstream-fleet. Para remover uma frota upstream, use a flag --reset-upstream-fleet .

Você pode realizar ações como:

  • Adicione outra frota ao início da sequência de lançamento adicionando uma frota upstream à primeira frota na sequência.
  • Mude a ordem das frotas na sequência de lançamento alterando as associações de frota upstream.
  • Remova a primeira frota na sequência de lançamento removendo a frota upstream da segunda frota.

Atrasar a conclusão do lançamento da versão do grupo

Se você precisar impedir temporariamente que um grupo conclua o lançamento de uma nova versão para os clusters, adicione uma exclusão de manutenção a qualquer um dos clusters que não foi feito o upgrade para a versão de destino. Isso pode pausar um grupo de prosseguir para o tempo de imersão ou grupo downstream por até 30 dias. Depois de 30 dias, o grupo começa a imersão.

É possível também alterar o tempo de imersão desse grupo para 30 dias a fim de maximizar o tempo que a sequência de lançamento aguarda antes de prosseguir para o próximo grupo.

Se você precisar atrasar ainda mais os upgrades a partir do próximo grupo, use exclusões de manutenção para os clusters do próximo grupo.

Excluir uma sequência

Para excluir uma sequência, remova as associações upstream de cada um dos grupos, exceto o primeiro. O primeiro grupo não tem um grupo upstream.

É possível realizar essas etapas no console do Google Cloud (prévia) ou com a CLI gcloud.

Console

  1. Acesse a página Sequência de lançamento no console do Google Cloud .

    Acessar o sequenciamento de lançamento

  2. Confira a sequência na seção Monitorar a sequência de lançamento. Se você não encontrar uma sequência de lançamento, mude para uma sequência de lançamento diferente ou crie uma, se ainda não tiver feito isso.

  3. No Gráfico de lançamento, clique no elemento da última frota.

  4. Clique em Remover frota.

  5. Para remover a frota, clique em Remover.

  6. Repita as três etapas anteriores até que apenas a primeira frota permaneça.

gcloud

Execute o comando a seguir no projeto host da frota de cada uma das frotas na sequência de lançamento, exceto a primeira:

gcloud container fleet clusterupgrade update --reset-upstream-fleet

Solução de problemas

Resolver problemas de qualificação para o lançamento

Se todos os clusters em uma sequência de lançamento não tiverem o mesmo destino de upgrade, talvez o GKE não consiga continuar com os upgrades do cluster. Os upgrades automáticos não poderão continuar se um grupo upstream não qualificar um destino de upgrade para transmitir ao grupo downstream. Os upgrades automáticos também não poderão continuar se os clusters no grupo upstream qualificarem um destino de upgrade inválido para clusters no grupo downstream.

Para verificar se a sequência de lançamento tem problemas de qualificação, confira o status da sequência de lançamento. Se um grupo não estiver qualificado, siga as instruções para ver o status de clusters individuais em um grupo.

Para avançar imediatamente os upgrades de cluster, remova todos os clusters com status INELIGIBLE seguindo as instruções para Promover lançamentos parcialmente qualificados.

Corrigir a qualificação em um grupo

Em um grupo, se um cluster não estiver qualificado porque está em uma versão anterior (por exemplo, a maioria dos clusters no grupo está sendo atualizada de 1.23 para 1.24 e um cluster está na versão 1.22), é possível fazer upgrade manual da a versão 1.24 para resolver a discrepância.

Em um grupo, o GKE ignora clusters em versões mais recentes do que o destino do upgrade automático. Esses clusters não impedem que os upgrades sejam feitos no grupo downstream.

Corrigir a qualificação entre grupos

Entre os grupos, se houver uma incompatibilidade nos destinos de upgrade em que o grupo downstream está em uma versão mais recente (por exemplo, o grupo upstream fez upgrade de 1.23 para 1.24 e os clusters no grupo downstream estão em 1.25), é possível fazer upgrade manual dos clusters no grupo upstream para 1.25 para garantir que eles prossigam.

Entre grupos, se houver uma incompatibilidade nos destinos de upgrade em que o grupo downstream está em uma versão anterior (por exemplo, o grupo upstream fez upgrade de 1.24 para 1.25 e os clusters no grupo downstream estão em 1.23), é possível fazer upgrade manual dos clusters no grupo downstream para 1.24 ou 1.25, a fim de garantir que os upgrades continuem. Se o GKE fizer upgrade do grupo upstream para qualquer versão em que o grupo downstream esteja qualificado, o GKE fará upgrade dos clusters no grupo downstream para esse destino de upgrade. Nesse caso, não é necessário fazer upgrade manual dos clusters para desbloquear a sequência. Para mais informações, consulte O grupo upstream qualificou vários destinos de upgrade para o grupo downstream.

Destacar lançamentos parcialmente qualificados

Se os upgrades de cluster em um grupo não forem concluídos devido a problemas com a qualificação para o lançamento (por exemplo, discrepâncias de versão em um grupo), remova os clusters que não estão qualificados para o destino de upgrade do grupo para concluir o lançamento da versão e iniciar o período de teste ou passar para o próximo grupo na sequência de lançamento. Também é possível remover um cluster de um grupo por outros motivos, por exemplo, se o uso dele não estiver mais relacionado aos outros clusters no grupo.

Siga as instruções para cancelar o registro de um cluster em uma frota.

Depois que você remover todos os clusters que estão impedindo a conclusão da implantação da versão de um grupo, o lançamento da versão do grupo será concluído. Confirme seguindo as instruções para verificar o status do lançamento de uma versão.

A seguir