Configure janelas e exclusões de manutenção.

Use janelas de manutenção e exclusões de manutenção para controlar quando a manutenção automática do cluster, como upgrades automáticos, pode ou não ocorrer nos clusters do Google Kubernetes Engine (GKE).

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

  • Ativar a API Google Kubernetes Engine.
    • Ativar a API Google Kubernetes Engine
  • Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando gcloud components update.

Configurar uma janela de manutenção

Para configurar uma janela de manutenção, especifique quando ela começa, quanto tempo dura e com que frequência ela se repete. Por exemplo, é possível configurar uma janela de manutenção que se repete semanalmente de segunda a sexta-feira, quatro horas por dia.

É possível configurar uma janela de manutenção usando o Console do Google Cloud ou a Google Cloud CLI.

Considerações ao configurar uma janela de manutenção

Ao configurar uma janela de manutenção, siga estas orientações:

  • São necessárias pelo menos 48 horas de disponibilidade de manutenção em um período de 32 dias. Somente períodos de disponibilidade contínuos de pelo menos quatro horas são considerados.
  • Ao usar o console do Google Cloud, os horários são sempre exibidos com o fuso horário local.
  • As recorrências do dia da semana são sempre baseadas em UTC. Como resultado, recomendamos configurar as janelas de manutenção que envolvem essas recorrências totalmente em UTC, pela CLI gcloud. O horário local pode ser usado durante a definição de sinalizações, mas o fuso não será armazenado. Por exemplo, se o fuso horário for UTC+6 e você quiser que uma janela de manutenção comece às 02:00 de quarta-feira no seu fuso horário, especifique um valor UTC de 20:00 às terças-feiras.

  • Se o cluster não puder concluir os upgrades de nós na janela de manutenção programada, isso poderá diminuir a taxa de upgrades. Talvez seja necessário testar sua configuração para encontrar o equilíbrio ideal entre velocidade e interrupção no seu ambiente. Os fatores que podem afetar a taxa de upgrade são:

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

Para criar uma janela de manutenção simples na gcloud CLI, especifique a sinalização --maintenance-window. Essa sinalização permite especificar uma janela de manutenção diária de quatro horas usando um formato simplificado. Para criar um cluster do Autopilot com uma janela de manutenção, use o Console do Google Cloud.

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

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

Substitua:

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

A janela de manutenção é executada todos os dias durante quatro horas no START_TIME especificado.

Criar uma janela de manutenção personalizada

É possível criar uma janela de manutenção que ocorra em determinados horários da semana ou do mês usando outros parâmetros explicados nesta seção.

Por exemplo, o comando a seguir cria um cluster chamado my-cluster com uma janela de manutenção ativada às 2h UTC na quarta-feira, 19 de agosto de 2026. Essa janela de manutenção começa às segundas e sextas-feiras e termina 30 horas depois. A primeira ocorrência da janela de manutenção começa na sexta-feira, 21 de agosto, às 2h, e termina no sábado, 22 de agosto, às 8h. Saiba mais sobre a formatação de datas e horas.

gcloud container clusters create my-cluster \
    --maintenance-window-start 2026-08-19T02:00:00Z \
    --maintenance-window-end 2026-08-20T08:00:00Z \
    --maintenance-window-recurrence 'FREQ=WEEKLY:BYDAY=MO,FR'

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

Criar um cluster com uma janela de manutenção

É possível criar um novo cluster padrão com uma janela de manutenção usando a ferramenta ou o Console do Google Cloud. Para criar um novo cluster do Autopilot com uma janela de manutenção, use o console do Google Cloud.

gcloud

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

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

Substitua:

  • CLUSTER_NAME: o nome do novo cluster.
  • START_TIME: a data e a hora em que a janela de manutenção recorrente é ativada, expressa como um valor RFC-5545 DTSTART. Depois desse tempo, a janela de manutenção é repetida de acordo com RRULE. O START_TIME também informa a hora do dia em que a janela de manutenção começa.
  • END_TIME: o horário de término para calcular a duração da janela de manutenção, conforme expresso pelo período após START_TIME, no mesmo formato. O valor de END_TIME precisa estar no futuro em relação a START_TIME.
  • RRULE: a recorrência da janela de manutenção, como expressa por um RRULE RFC-5545. Esse é um formato flexível com várias maneiras de especificar regras de recorrência, determinando em qual dia a janela de manutenção começa. Por exemplo, é possível especificar uma recorrência de certos momentos por semana ou mês. Quando a data END_TIME é maior que a data START_TIME, a janela de manutenção abrange vários dias. Por exemplo, uma janela de manutenção a partir de domingo continua até segunda-feira.

Console

  1. Acesse a página Google Kubernetes Engine no console do Google Cloud.

    Acessar o Google Kubernetes Engine

  2. Clique em Criar.

  3. Configure o cluster como quiser.

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

  5. Marque a caixa de seleção Ativar janela de manutenção.

  6. Selecione o horário de início e a duração e, em 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.

  7. Clique em Criar.

Configurar uma janela de manutenção de um cluster atual

gcloud

Crie ou atualize uma janela de manutenção para um cluster:

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

Substitua:

  • CLUSTER_NAME: o nome do novo cluster.
  • START_TIME: a data e a hora em que a janela de manutenção recorrente é ativada, expressa como um valor RFC-5545 DTSTART. Depois desse tempo, a janela de manutenção é repetida de acordo com RRULE. O START_TIME também informa a hora do dia em que a janela de manutenção começa.
  • END_TIME: o horário de término para calcular a duração da janela de manutenção, conforme expresso pelo período após START_TIME, no mesmo formato. O valor de END_TIME precisa estar no futuro em relação a START_TIME.
  • RRULE: a recorrência da janela de manutenção, como expressa por um RRULE RFC-5545. Esse é um formato flexível com várias maneiras de especificar regras de recorrência, determinando em qual dia a janela de manutenção começa. Por exemplo, é possível especificar uma recorrência de certos momentos por semana ou mês. Quando a data END_TIME é maior que a data START_TIME, a janela de manutenção abrange vários dias. Por exemplo, uma janela de manutenção a partir de domingo continua até segunda-feira.

Console

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

  1. Acesse a página Google Kubernetes Engine no console do Google Cloud.

    Acessar o Google Kubernetes Engine

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

  3. Em Automação, clique em Editar política de manutenção ao lado do campo Janela de manutenção.

  4. Marque a caixa de seleção Ativar janela de manutenção.

  5. Selecione o horário de início e a duração e, em 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 Save Changes.

Encerrar manutenção incompleta manualmente

Se um upgrade ou outra manutenção automática demorar mais do que a janela de manutenção para ser concluído, o GKE tentará interromper as tarefas de manutenção contínuas para retomá-las durante a próxima ocorrência da janela de manutenção. Se você tiver os upgrades automáticos de nós ativados e um upgrade automático for cancelado, os nós podem ficar em um estado de versão mista, mas o cluster continuará a operar normalmente.

Para fazer upgrade do cluster manualmente, cancelar ou reverter um upgrade parcial, acesse Fazer upgrade manual de um cluster.

Remover uma janela 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 atual.

Console

Para remover uma janela de manutenção:

  1. Acesse a página Google Kubernetes Engine no console do Google Cloud.

    Acessar o Google Kubernetes Engine

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

  3. Em Automação, clique em Editar política de manutenção ao lado do campo Janela de manutenção.

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

  5. Clique em Salvar alterações.

Exemplos de janelas de manutenção

Os exemplos a seguir ilustram algumas das diferentes maneiras de configurar uma janela de manutenção. Somente as sinalizações relevantes são mostradas porque as sinalizações usam a mesma sintaxe para criar um novo cluster ou atualizar um já existente.

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

Neste exemplo, a diferença entre os carimbos de data/hora de início e término é de dois dias inteiros, portanto, a janela de manutenção é executada durante todo o fim de semana, aos sábados e domingos. Se você quiser que a janela tenha uma duração diferente de 48 horas, modifique -start para mudar quando a janela começa, ou -end para mudar a duração total da janela.

--maintenance-window-start 2026-08-22T00:00:00Z \
--maintenance-window-end 2026-08-24T00:00:00Z \
--maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=SA'
Diariamente durante a semana, das 9h às 17h UTC-4

Este exemplo mostra como ter uma janela de manutenção diária, mas pular finais de semana. Este exemplo especifica um fuso horário diferente de 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'
Semanal às 16h, durante 8 horas, UTC-7

Se você não especificar um fuso horário para --maintenance-window-start, será usado o horário local configurado na sua conta do Google Cloud. O Console do Google Cloud sempre usa o horário 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 da semana à noite

Este exemplo mostra uma janela de manutenção diária que é executada durante a noite entre dias de trabalho no fuso horário UTC-7. Neste exemplo, a janela começa às 20h e vai até as 4h 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'

Configurar uma exclusão de manutenção

Para configurar uma exclusão de manutenção para seu cluster, é necessário especificar o seguinte:

  • Nome: é o nome da exclusão (opcional).
  • Horário de início: a data e a hora em que o período de exclusão começará.
  • Horário de término: a data e a hora em que o período de exclusão deve terminar. Consulte a tabela a seguir para ver as restrições de duração de um período de exclusão para cada um dos escopos disponíveis.
  • Escopo: o escopo dos upgrades automáticos a serem restringidos. Consulte a tabela a seguir que lista os escopos de exclusão disponíveis.
Escopo Descrição Tamanho máximo da exclusão
Nenhum upgrade (padrão) Exclui todos os patches e todos os upgrades menores. Evita interrupções de VM para o plano de controle e nós do cluster. Não pode ultrapassar 30 dias.
Nenhuma atualização secundária Exclui todos os upgrades menores. As interrupções da VM podem ocorrer nos nós e no plano de controle do cluster devido a upgrades de patch. Não pode ultrapassar 180 dias ou se estender após a data de fim da vida útil da versão secundária.
Nenhum upgrade secundário ou de nós Exclui todos os upgrades menores e de nó. Evita interrupções nos upgrades de nós do cluster. No entanto, podem ocorrer interrupções no plano de controle. Não pode ultrapassar 180 dias ou se estender após a data de fim da vida útil da versão secundária.

Para definições sobre versões secundárias e de patch, consulte Esquema de controle de versão.

As exclusões de manutenção têm as seguintes limitações:

  • É possível restringir o escopo de upgrades automáticos em uma exclusão de manutenção somente para clusters registrados em um canal de lançamento.
  • É possível adicionar no máximo três exclusões de manutenção que excluem todos os upgrades. Ou seja, um escopo de "sem upgrades".
  • É possível ter até 20 exclusões de manutenção no total.
  • Se você não especificar um escopo na sua exclusão, o escopo padrão será "sem upgrades".

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

Durante a criação de um novo cluster, você pode configurar uma exclusão de manutenção usando o Console do Google Cloud. Não é possível executar esta tarefa na gcloud CLI.

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

  1. Acesse a página Google Kubernetes Engine no console do Google Cloud.

    Acessar o Google Kubernetes Engine

  2. Clique em Criar.

  3. Configure o cluster como quiser.

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

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

  6. Selecione o Escopo, um Horário de início e um Horário de término.

  7. Clique em Criar.

Você pode ver um exemplo de exclusão de manutenção para a Black Friday.

Configurar uma exclusão de manutenção para um cluster atual

Você pode configurar uma exclusão de manutenção em um cluster atual usando o Console do Google Cloud ou a gcloud CLI.

gcloud

Configurar uma exclusão de manutenção para um cluster:

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:

  • CLUSTER_NAME: o nome do cluster.
  • EXCLUSION_NAME: o nome da exclusão de manutenção.
  • START_DATE_TIME: data e hora de início da exclusão.
  • END_DATE_TIME: data e hora de término da exclusão.
  • SCOPE: o escopo do upgrade a ser excluído, que pode ser um dos seguintes valores: no_upgrades, no_minor_upgrades ou no_minor_or_node_upgrades.

Para visualizar os formatos de data e hora compatíveis, execute o gcloud topic datetimes.

Console

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

  1. Acesse a página Google Kubernetes Engine no console do Google Cloud.

    Acessar o Google Kubernetes Engine

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

  3. Em Automação, ao lado do 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 Escopo, um Horário de início e um Horário de término.

  6. Clique em Save Changes.

Remover uma exclusão de manutenção

É possível remover as exclusões de manutenção usando o Console do Google Cloud ou a gcloud CLI.

gcloud

Remova uma exclusão de manutenção:

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

Substitua:

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

Console

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

  1. Acesse a página Google Kubernetes Engine no console do Google Cloud.

    Acessar o Google Kubernetes Engine

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

  3. Em Automação, ao lado do campo Exclusões de manutenção, clique em Editar exclusões de manutenção.

  4. Em Exclusões de manutenção, clique em Excluir item ao lado do campo Horário de término da exclusão que você quer remover.

  5. Clique em Salvar alterações.

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

Exemplo de exclusão de manutenção

O exemplo a seguir evita manutenção durante os quatro dias que abrangem a Black Friday até a Cyber Monday, o período de vendas de maior volume do ano para muitas empresas de varejo. Este exemplo mostra como evitar que uma janela de manutenção ocorra da Black Friday 2021 (26 de novembro de 2021) à Cyber Monday 2021 (29 de novembro de 2021), da meia-noite do leste (UTC-5) às 23:59.:59 do Pacífico (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

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

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

gcloud container clusters describe CLUSTER_NAME

Solução de problemas

Restringir o escopo das exclusões de manutenção só pode ser aplicado a canais de lançamento

Ao restringir o escopo de upgrades automáticos em uma exclusão de manutenção, o cluster precisa estar inscrito em um canal de lançamento, caso contrário, os seguintes erros poderão ocorrer:

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

É possível especificar no máximo três exclusões de manutenção que excluem todos os upgrades (ou seja, um escopo de "sem upgrades"). Caso contrário, você verá o seguinte erro:

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

É possível especificar no máximo 20 exclusões de manutenção no total, caso contrário, você verá o seguinte erro:

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

A seguir