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 CLI gcloud. Se instalou anteriormente a CLI gcloud, execute o comando gcloud components update para obter a versão mais recente. As versões anteriores da CLI gcloud podem não suportar a execução dos comandos neste documento.

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.

Configure um período de manutenção

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

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 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 RFC-5545. Este é um formato flexível com várias formas de especificar regras de recorrência, que determinam o dia em que a janela de manutenção começa. Por exemplo, pode especificar uma recorrência de determinadas horas por semana ou por mês. Se a END_TIME data for posterior à START_TIME data, 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.

Por exemplo, o seguinte comando edita um cluster denominado my-cluster com um período de manutenção ativado à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 update 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 ver mais cenários, consulte os exemplos de janelas de manutenção.

Consola

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

  1. Aceda à página 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 diretamente a RRule, 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 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 a janela de manutenção é executada durante todo o fim de semana, ao longo dos 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'

Dias de semana à noite

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, a janela 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. Para determinados âmbitos de exclusão de manutenção, pode definir a hora de fim para acompanhar a data de fim do apoio técnico para a versão secundária do cluster.
  • Âmbito: o âmbito das atualizações automáticas a restringir. Consulte a tabela seguinte que lista os âmbitos de exclusão disponíveis.
Âmbito Plano de controlo Nós Duração máxima da exclusão
Atualização secundária automática Atualização automática de patches Atualização secundária automática Atualização automática de patches
Sem atualizações (predefinição) Não permitido Não permitido Não permitido Não permitido Não pode exceder 30 dias.
Sem atualizações secundárias Não permitido Permitido Não permitido Permitido 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. Pode configurar a hora de fim para acompanhar o fim do apoio técnico da versão secundária do seu cluster. A exclusão de manutenção termina quando a versão secundária do cluster atinge o fim do apoio técnico. Para mais informações, consulte o artigo Como uma exclusão de manutenção monitoriza o fim do apoio técnico.
Sem atualizações menores ou de nós Não permitido Permitido Não permitido Não permitido 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. Pode configurar a hora de fim para acompanhar o fim do apoio técnico da versão secundária do seu cluster. A exclusão de manutenção termina quando a versão secundária do cluster atinge o fim do apoio técnico. Para mais informações, consulte o artigo Como uma exclusão de manutenção monitoriza o fim do apoio técnico.

Como configurar uma exclusão de manutenção

Pode criar um cluster com uma exclusão de manutenção com a Google Cloud consola ou configurar uma exclusão de manutenção para um cluster existente com a Google Cloud consola ou a CLI gcloud.

Com a CLI gcloud, pode configurar opcionalmente a hora de fim de uma exclusão de manutenção para acompanhar a data de fim do apoio técnico da versão secundária do cluster.

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. Com a CLI gcloud, pode configurar opcionalmente a hora de fim de uma exclusão de manutenção para acompanhar a data de fim do suporte técnico da versão secundária do cluster.

gcloud

  • Hora de fim fixa: configure uma exclusão de manutenção para um cluster existente com uma hora de fim fixa:

    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 seu cluster.
    • EXCLUSION_NAME: o nome da exclusão de manutenção.
    • START_DATE_TIME: opcionalmente, defina a data e a hora de início da exclusão para um momento no futuro. Se omitir esta flag, a exclusão de manutenção começa imediatamente.
    • 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.

  • Termina no fim do suporte: configure uma exclusão de manutenção que monitorize a data de fim do suporte da versão secundária do cluster:

    gcloud container clusters update CLUSTER_NAME \
    --add-maintenance-exclusion-name EXCLUSION_NAME \
    [--add-maintenance-exclusion-start START_DATE_TIME \]
    --add-maintenance-exclusion-until-end-of-support \
    --add-maintenance-exclusion-scope SCOPE

Consola

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

  1. Aceda à página 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 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 Automaçã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) à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 ambiente do 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 Recommender, 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

Use as seguintes informações para resolver problemas comuns sobre janelas de manutenção e exclusões.

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:

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?