Configure janelas de manutenção e exclusões

Use períodos de manutenção e exclusões de manutenção para controlar quando a manutenção automática do cluster, como as atualizações automáticas, pode e não pode ocorrer nos seus clusters do Google Kubernetes Engine (GKE). Antes de configurar estas políticas de manutenção, certifique-se de que revê as alterações que respeitam e não respeitam as políticas de manutenção do GKE.

Antes de começar

Antes de começar, certifique-se de que realizou as seguintes tarefas:

  • Ative a API Google Kubernetes Engine.
    • Ative a API Google Kubernetes Engine
  • Se quiser usar a CLI gcloud para esta tarefa, instale-a e, em seguida, inicialize-a. Se instalou anteriormente a CLI gcloud, execute gcloud components update para obter a versão mais recente.

Configure um período de manutenção

Para configurar um período de manutenção, especifique quando começa, quanto tempo dura e com que frequência se repete. Por exemplo, pode configurar um período de manutenção que se repete semanalmente de segunda a sexta-feira durante quatro horas por dia.

Pode configurar um período de manutenção através da Google Cloud consola ou da CLI do Google Cloud.

Considerações ao configurar um período de manutenção

Quando configurar um período de manutenção, siga estas orientações:

  • Compreenda que tipos de eventos de manutenção respeitam e não respeitam os períodos de manutenção do GKE. Para saber mais, consulte os artigos Manutenção automática que respeita as políticas de manutenção do GKE e Manutenção automática que não respeita as políticas de manutenção do GKE.
  • Só pode configurar um período de manutenção para um cluster e a configuração de um novo período substitui o anterior.
  • Tem de permitir, pelo menos, 48 horas de disponibilidade de manutenção num período de 32 dias. Só são consideradas janelas de disponibilidade contíguas de, pelo menos, quatro horas.
  • Quando usa a Google Cloud consola, as horas são sempre apresentadas no fuso horário local.
  • As recorrências do dia da semana baseiam-se sempre no UTC. Como tal, recomendamos que defina períodos de manutenção que envolvam essas recorrências totalmente em UTC, através da CLI gcloud. Embora seja possível usar a hora local ao definir flags, o fuso horário não é armazenado. Por exemplo, se o seu fuso horário for UTC+6 e quiser que uma janela de manutenção comece às 02:00 às quartas-feiras no seu fuso horário, especifique um valor UTC de 20:00 às terças-feiras. Para saber mais, consulte o artigo Fusos horários para janelas de manutenção.

O período de manutenção está a impedir a conclusão da atualização do nó

Se o seu cluster não conseguir concluir as atualizações dos nós, como as atualizações da versão dos nós, dentro do período de manutenção agendado, isto pode abrandar a taxa de atualizações ou atrasar a conclusão das alterações aos nós. Pode ter de experimentar a sua configuração para encontrar o equilíbrio ideal entre a velocidade e a interrupção para o seu ambiente. Os fatores que podem afetar a taxa de atualização incluem:

Crie um cluster padrão com uma janela de manutenção simples

Pode criar um período de manutenção simples na CLI gcloud especificando a flag --maintenance-window. Esta flag permite-lhe especificar um período de manutenção diário de 4 horas através de um formato simplificado. Para criar um cluster do Autopilot com uma janela de manutenção, use a Google Cloud consola.

Crie um novo cluster padrão com um período de manutenção simples:

gcloud container clusters create CLUSTER_NAME \
    --maintenance-window START_TIME

Substitua o seguinte:

  • CLUSTER_NAME: o nome do novo cluster.
  • START_TIME: uma data/hora de 24 horas no formato UTC, como 16:00.

O período de manutenção é executado todos os dias na hora especificada START_TIME e dura quatro horas.

Crie uma janela de manutenção personalizada

Pode criar uma janela de manutenção que ocorra em determinadas horas da semana ou do mês através de parâmetros adicionais explicados nesta secção.

Por exemplo, o comando seguinte cria um cluster denominado my-cluster com uma janela de manutenção ativada às 02:00 UTC de sexta-feira, 23 de agosto de 2024. Esta janela de manutenção repete-se semanalmente todas as segundas e sextas-feiras, e termina 30 horas depois. A primeira ocorrência da janela de manutenção começa na sexta-feira, 23 de agosto, às 02:00 e termina no sábado, 24 de agosto, às 08:00. Pode saber mais sobre a formatação de datas e horas.

gcloud container clusters create my-cluster \
    --maintenance-window-start 2024-08-23T02:00:00Z \
    --maintenance-window-end 2024-08-24T08:00:00Z \
    --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=MO,FR'

Para mais cenários, consulte os exemplos de janelas de manutenção.

Crie um cluster com uma janela de manutenção

Pode criar um novo cluster padrão com um período de manutenção através da CLI gcloud ou da Google Cloud consola. Para criar um novo cluster do Autopilot com uma janela de manutenção, use aGoogle Cloud consola.

gcloud

Crie um novo cluster padrão com um período de manutenção:

gcloud container clusters create CLUSTER_NAME \
    --maintenance-window-start START_TIME \
    --maintenance-window-end END_TIME \
    --maintenance-window-recurrence RRULE

Substitua o seguinte:

  • CLUSTER_NAME: o nome do novo cluster.
  • START_TIME: a data e a hora em que o período de manutenção recorrente está ativado, expresso como um valor DTSTART RFC-5545. Após este período, o período de manutenção repete-se de acordo com o RRULE. O START_TIME também indica a que hora do dia começa o período de manutenção.
  • END_TIME: a hora de fim para calcular a duração do período de manutenção, expressa pela quantidade de tempo após START_TIME, no mesmo formato. O valor de END_TIME tem de ser no futuro, em relação a START_TIME. Isto apenas calcula a duração do período e não define quando o período de manutenção deixa de ser recorrente. Os períodos de manutenção só deixam de ser recorrentes quando são removidos.
  • RRULE: A recorrência do período de manutenção, conforme expresso por uma RRULE do RFC-5545. Este é um formato flexível com várias formas de especificar regras de recorrência, que determinam em que dia começa o período de manutenção. Por exemplo, pode especificar uma recorrência de determinadas horas por semana ou por mês. Se a data de END_TIME for posterior à data de START_TIME, o período de manutenção abrange vários dias. Por exemplo, uma janela de manutenção que comece ao domingo continua até segunda-feira.

Consola

  1. Na Google Cloud consola, aceda à página Criar um cluster do Autopilot.

    Aceda a Crie um cluster do Autopilot

    Também pode concluir esta tarefa criando um cluster padrão.

  2. Configure o cluster.

  3. No painel de navegação, em Clusters, clique em Automação.

  4. Selecione a caixa de verificação Ativar janela de manutenção.

  5. Selecione a hora de início e a duração e, de seguida, selecione os dias da semana em que a janela de manutenção ocorre. Para editar diretamente a especificação da regra de recorrência (RRule), selecione Editor personalizado.

  6. Clique em Criar.

Configure um período de manutenção para um cluster existente

gcloud

Crie ou atualize um período de manutenção para um cluster existente:

gcloud container clusters update CLUSTER_NAME \
    --maintenance-window-start START_TIME \
    --maintenance-window-end END_TIME \
    --maintenance-window-recurrence RRULE

Substitua o seguinte:

  • CLUSTER_NAME: o nome do novo cluster.
  • START_TIME: a data e a hora em que o período de manutenção recorrente está ativado, expresso como um valor DTSTART RFC-5545. Após este período, o período de manutenção repete-se de acordo com o RRULE. O START_TIME também indica a que hora do dia começa o período de manutenção.
  • END_TIME: a hora de fim para calcular a duração do período de manutenção, expressa pela quantidade de tempo após START_TIME, no mesmo formato. O valor de END_TIME tem de ser no futuro, em relação a START_TIME. Isto apenas calcula a duração do período e não define quando o período de manutenção deixa de ser recorrente. Os períodos de manutenção só deixam de ser recorrentes quando são removidos.
  • RRULE: A recorrência do período de manutenção, conforme expresso por uma RRULE do RFC-5545. Este é um formato flexível com várias formas de especificar regras de recorrência, que determinam em que dia começa o período de manutenção. Por exemplo, pode especificar uma recorrência de determinadas horas por semana ou por mês. Se a data de END_TIME for posterior à data de START_TIME, o período de manutenção abrange vários dias. Por exemplo, uma janela de manutenção que comece ao domingo continua até segunda-feira.

Consola

Para criar ou modificar uma janela de manutenção para um cluster existente:

  1. Aceda à página do Google Kubernetes Engine na Google Cloud consola.

    Aceda ao Google Kubernetes Engine

  2. Na lista de clusters, clique no nome do cluster que quer modificar.

  3. Em Automatização, clique em Editar política de manutenção junto ao campo Janela de manutenção.

  4. Selecione a caixa de verificação Ativar janela de manutenção.

  5. Selecione a hora de início e a duração e, de seguida, selecione os dias da semana em que a janela de manutenção ocorre. Para editar a RRule diretamente, selecione Editor personalizado.

  6. Clique em Guardar alterações.

Conclua manualmente a manutenção incompleta

Se uma atualização ou outra manutenção automática demorar mais tempo do que o período de manutenção a ser concluída, o GKE tenta parar as tarefas de manutenção em curso e retomá-las durante a ocorrência seguinte do período de manutenção. Se uma atualização automática for cancelada e tiver as atualizações automáticas de nós ativadas, os seus nós podem estar num estado de versão mista, mas o cluster deve funcionar normalmente.

Para atualizar manualmente o cluster ou cancelar ou reverter uma atualização parcial, consulte o artigo Atualizar manualmente um cluster.

Remova um período de manutenção

gcloud

Remova uma janela de manutenção de um cluster:

gcloud container clusters update CLUSTER_NAME --clear-maintenance-window

Substitua CLUSTER_NAME pelo nome do cluster existente.

Consola

Para remover um período de manutenção:

  1. Aceda à página do Google Kubernetes Engine na Google Cloud consola.

    Aceda ao Google Kubernetes Engine

  2. Na lista de clusters, clique no nome do cluster que quer modificar.

  3. Em Automatização, clique em Editar política de manutenção junto ao campo Janela de manutenção.

  4. Desmarque a caixa de verificação Ativar janela de manutenção.

  5. Clique em Guardar alterações.

Exemplos de períodos de manutenção

Os exemplos seguintes ilustram algumas das diferentes formas de configurar um período de manutenção. Apenas são apresentadas as flags relevantes, porque as flags usam a mesma sintaxe para criar um novo cluster ou atualizar um existente.

Fins de semana, a partir de 22 de agosto de 2026

Neste exemplo, a diferença entre as indicações de tempo de início e de fim é de dois dias completos, pelo que o período de manutenção é executado durante todo o fim de semana, aos sábados e domingos. Se quiser que o período tenha uma duração diferente de 48 horas, modifique o -start para alterar o início do período ou o -end para alterar a duração total do período.

  --maintenance-window-start 2026-08-22T00:00:00Z \
  --maintenance-window-end 2026-08-24T00:00:00Z \
  --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=SA'

Diariamente, nos dias úteis, das 09:00 às 17:00 UTC-4

Este exemplo mostra como ter um período de manutenção diário, mas ignorar os fins de semana. Este exemplo especifica um fuso horário que não é o UTC.

   --maintenance-window-start 2026-09-02T09:00:00-04:00 \
   --maintenance-window-end 2026-09-02T17:00:00-04:00 \
   --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR'

Semanalmente às 16:00 durante 8 horas, UTC-7

Se não especificar um fuso horário para --maintenance-window-start, é usada a hora local, conforme configurado na sua conta Google Cloud . A Google Cloud consola usa sempre a hora local.

   --maintenance-window-start 2026-08-13T16:00:00-7:00 \
   --maintenance-window-end 2026-08-14T00:00:00-7:00 \
   --maintenance-window-recurrence 'FREQ=WEEKLY'

Noites de dias úteis

Este exemplo mostra uma janela de manutenção diária que é executada durante a noite entre os dias úteis no fuso horário UTC-7. Neste exemplo, o período decorre das 20:00 da noite até às 04:00 da manhã seguinte.

   --maintenance-window-start 2026-08-15T20:00:00-7:00 \
   --maintenance-window-end 2026-08-16T04:00:00-7:00 \
   --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH'

Configure uma exclusão de manutenção

Para configurar uma exclusão de manutenção para o seu cluster, tem de especificar o seguinte:

  • Nome: o nome da exclusão (opcional).
  • Hora de início: a data e a hora em que o período de exclusão deve começar. A hora de início tem de ser agora ou no futuro.
  • Hora de fim: a data e a hora em que o período de exclusão deve terminar. Consulte a tabela seguinte para ver as restrições relativas à duração de um período de exclusão para cada um dos âmbitos disponíveis.
  • Âmbito: o âmbito das atualizações automáticas a restringir. Consulte a tabela seguinte que lista os âmbitos de exclusão disponíveis.
Âmbito Descrição Duração máxima da exclusão
Sem upgrades (predefinição) Exclui todas as atualizações de patches e secundárias. Evita interrupções de VMs no painel de controlo e nos nós do cluster devido a atualizações. Não pode exceder 30 dias.
Sem atualizações secundárias Exclui todas as atualizações menores. As interrupções da VM podem ocorrer no painel de controlo e nos nós do cluster devido a atualizações de patches. Para clusters inscritos nos canais Rápido, Regular ou Estável, não é possível prolongar o período para além do fim do apoio técnico padrão. Para clusters inscritos no canal alargado, não é possível prolongar o período após o fim do apoio técnico alargado da versão secundária.
Sem atualizações menores ou de nós Exclui todas as atualizações secundárias e atualizações de nós. Evita interrupções de VMs nos nós do cluster devido a atualizações. No entanto, podem ocorrer interrupções no plano de controlo. Para clusters inscritos nos canais Rápido, Regular ou Estável, não é possível prolongar o período para além do fim do apoio técnico padrão. Para clusters inscritos no canal alargado, não é possível prolongar o período após o fim do apoio técnico alargado da versão secundária.

Crie um cluster com uma exclusão de manutenção

Pode configurar uma exclusão de manutenção quando cria um novo cluster através da consola. Google Cloud Não é possível realizar esta tarefa na CLI gcloud.

Para criar um novo cluster com uma exclusão de manutenção:

  1. Na Google Cloud consola, aceda à página Criar um cluster do Autopilot.

    Aceda a Crie um cluster do Autopilot

    Também pode concluir esta tarefa criando um cluster padrão.

  2. Configure o cluster.

  3. No painel de navegação, em Cluster, clique em Automação.

  4. Em Exclusões de manutenção, clique em Adicionar exclusão de manutenção.

  5. Selecione o Âmbito, uma Hora de início e uma Hora de fim.

  6. Clique em Criar.

Pode ver um exemplo de exclusão de manutenção para a Black Friday.

Configure uma exclusão de manutenção para um cluster existente

Pode configurar uma exclusão de manutenção num cluster existente através da Google Cloud consola ou da CLI gcloud.

gcloud

Configure uma exclusão de manutenção para um cluster existente:

gcloud container clusters update CLUSTER_NAME \
    --add-maintenance-exclusion-name EXCLUSION_NAME \
    --add-maintenance-exclusion-start START_DATE_TIME \
    --add-maintenance-exclusion-end END_DATE_TIME \
    --add-maintenance-exclusion-scope SCOPE

Substitua o seguinte:

  • CLUSTER_NAME: o nome do cluster.
  • EXCLUSION_NAME: o nome da exclusão de manutenção.
  • START_DATE_TIME: a data e a hora de início da exclusão.
  • END_DATE_TIME: a data e a hora de fim da exclusão.
  • SCOPE: o âmbito da atualização a excluir, que pode ser um dos seguintes valores: no_upgrades, no_minor_upgrades ou no_minor_or_node_upgrades.

Para ver os formatos de data e hora suportados, execute gcloud topic datetimes.

Consola

Para configurar uma exclusão de manutenção para um cluster existente:

  1. Aceda à página do Google Kubernetes Engine na Google Cloud consola.

    Aceda ao Google Kubernetes Engine

  2. Na lista de clusters, clique no nome do cluster que quer modificar.

  3. Em Automatização, junto ao campo Exclusões de manutenção, clique em Editar exclusões de manutenção.

  4. Em Exclusões de manutenção, clique em Adicionar exclusão de manutenção.

  5. Selecione o Âmbito, uma Hora de início e uma Hora de fim.

  6. Clique em Guardar alterações.

Remova uma exclusão de manutenção

Pode remover exclusões de manutenção através da Google Cloud consola ou da CLI gcloud.

gcloud

Remova uma exclusão de manutenção existente:

gcloud container clusters update CLUSTER_NAME \
    --remove-maintenance-exclusion EXCLUSION_NAME

Substitua o seguinte:

  • CLUSTER_NAME: o nome do cluster existente.
  • EXCLUSION_NAME: o nome da exclusão de manutenção a remover.

Consola

Para remover uma exclusão de manutenção de um cluster existente:

  1. Aceda à página do Google Kubernetes Engine na Google Cloud consola.

    Aceda ao Google Kubernetes Engine

  2. Na lista de clusters, clique no nome do cluster que quer modificar.

  3. Em Automatização, junto ao campo Exclusões de manutenção, clique em Editar exclusões de manutenção.

  4. Em Exclusões de manutenção, clique em Eliminar item junto ao campo Hora de fim da exclusão que quer remover.

  5. Clique em Guardar alterações.

Para ver todas as exclusões de manutenção num cluster, pode ver a política de manutenção do cluster.

Exemplo de exclusão de manutenção

O exemplo seguinte impede a manutenção durante os quatro dias que abrangem a Black Friday até à Cyber Monday, o período de vendas com o volume mais elevado do ano para muitas empresas de retalho. Este exemplo mostra como impedir que ocorra uma janela de manutenção desde a Black Friday de 2021 (26 de novembro de 2021) até à Cyber Monday de 2021 (29 de novembro de 2021), desde a meia-noite (UTC-5) até às 23:59:59 (UTC-8).

gcloud container clusters update sample-cluster \
    --add-maintenance-exclusion-name black-friday \
    --add-maintenance-exclusion-start 2021-11-26T00:00:00-05:00 \
    --add-maintenance-exclusion-end 2021-11-29T23:59:59-08:00 \
    --add-maintenance-exclusion-scope no_upgrades

Veja a política de manutenção de um cluster

Para ver a política de manutenção de um cluster, incluindo se tem uma janela de manutenção e todas as respetivas exclusões de manutenção, use o seguinte comando:

gcloud container clusters describe CLUSTER_NAME

Identifique clusters sem um período de manutenção configurado

O GKE identifica clusters para os quais não configurou um período de manutenção para que possa escolher um período recorrente no qual o GKE pode realizar a manutenção do cluster. Recomendamos que configure um período de manutenção para garantir que o GKE faz atualizações automáticas e outra manutenção do cluster que respeite as políticas de manutenção quando for mais conveniente para o seu ambiente de cluster.

O GKE fornece estas orientações com uma estatística e uma recomendação através do serviço Recommender. Para saber mais sobre como gerir estatísticas e recomendações do Recomendador, consulte o artigo Otimize a sua utilização do GKE com estatísticas e recomendações.

Para encontrar clusters sem uma janela de manutenção configurada, pode usar uma das seguintes formas:

  • Use a Google Cloud consola.
  • Use a CLI gcloud ou a API Recommender, especificando o CLUSTER_MAINTENANCE_WINDOW_AND_EXCLUSIONS subtipo de recomendador.

Para ver instruções, saiba como ver estatísticas e recomendações.

Para implementar esta recomendação, configure uma janela de manutenção.

Resolução de problemas

A restrição do âmbito das exclusões de manutenção só pode aplicar-se a canais de lançamento

Quando restringe o âmbito das atualizações automáticas numa exclusão de manutenção, o cluster tem de estar inscrito num canal de lançamento, caso contrário, pode ocorrerem os seguintes erros:

ERROR: (gcloud.container.clusters.update) INVALID_ARGUMENT: Cannot update to
STATIC channel since following maintenancePolicy.maintenanceExclusions can only
apply to release channels. Please remove those maintenance exclusions.

ERROR: (gcloud.container.clusters.update) ResponseError: code=400,
message=MaintenancePolicy.maintenanceExclusions["no"] could not apply to cluster
in STATIC channel, only no_upgrades exclusions are allowed in STATIC channel.

As exclusões de manutenção excedem o limite

Só pode especificar um máximo de 3 exclusões de manutenção que excluam todas as atualizações (ou seja, um âmbito de "sem atualizações"). Caso contrário, recebe o seguinte erro:

ERROR: (gcloud.container.clusters.update) ResponseError: code=400,
message=Number of active maintenance exclusions exceeds limit (3).

Só pode especificar um máximo de 20 exclusões de manutenção no total. Caso contrário, recebe o seguinte erro:

ERROR: (gcloud.container.clusters.update) ResponseError: code=400,
message=Number of total maintenance exclusions exceeds limit (20).

O que se segue?