Configura períodos de mantenimiento y exclusiones

Autopilot Estándar

Usa períodos de mantenimiento y exclusiones de mantenimiento para controlar cuándo puede o no puede ocurrir el mantenimiento automático del clúster, como las actualizaciones automáticas, en tus clústeres de Google Kubernetes Engine (GKE). Antes de configurar estas políticas de mantenimiento, asegúrate de revisar qué cambios respetan y no respetan las políticas de mantenimiento de GKE.

Antes de comenzar

Antes de comenzar, asegúrate de haber realizado las siguientes tareas:

Habilita la API de Google Kubernetes Engine.

Habilitar la API de Google Kubernetes Engine

Si deseas usar Google Cloud CLI para esta tarea, instala y, luego, inicializa gcloud CLI. Si ya instalaste gcloud CLI, ejecuta gcloud components update para obtener la versión más reciente.
Nota: Para las instalaciones de gcloud CLI existentes, asegúrate de configurar las propiedades compute/region y compute/zone. Cuando configuras las ubicaciones predeterminadas, puedes evitar errores en la CLI de gcloud como el siguiente: One of [--zone, --region] must be supplied: Please specify location.

Configura un período de mantenimiento

Para configurar un período de mantenimiento, especifica cuándo se inicia, cuánto dura y con qué frecuencia se repite. Por ejemplo, puedes configurar un período de mantenimiento que se repita cada semana de lunes a viernes durante cuatro horas al día.

Puedes configurar un período de mantenimiento con la consola de Google Cloud o Google Cloud CLI.

Consideraciones para configurar un período de mantenimiento

Cuando configures un período de mantenimiento, sigue estas instrucciones:

Comprende qué tipos de eventos de mantenimiento respetan y no respetan los períodos de mantenimiento de GKE. Para obtener más información, consulta Mantenimiento automático que respeta las políticas de mantenimiento de GKE y Mantenimiento automático que no respeta las políticas de mantenimiento de GKE.
Solo puedes configurar un período de mantenimiento para un clúster, y si configuras un período nuevo, se reemplaza el anterior.
Debes permitir al menos 48 horas de disponibilidad de mantenimiento en un período móvil de 32 días. Solo se consideran los períodos de disponibilidad contiguos de cuatro horas como mínimo.
Cuando usas la consola de Google Cloud, las horas siempre se muestran con la zona horaria local.
Las repeticiones del día de la semana siempre se basan en UTC. Como resultado, recomendamos configurar períodos de mantenimiento que involucren estas recurrencias completamente en UTC a través de la CLI de gcloud. Si bien la hora local se puede usar para configurar marcas, la zona horaria no se almacenará. Por ejemplo, si tu zona horaria es UTC+6 y quieres que un período de mantenimiento comience a las 2:00 a.m. de los miércoles en tu zona horaria, especifica un valor UTC de 8:00 p.m. los martes. A fin de obtener más información, consulta Zonas horarias para períodos de mantenimiento.
Si tu clúster no puede finalizar las actualizaciones de nodos dentro del período de mantenimiento programado, esto puede ralentizar la frecuencia de actualizaciones. Es posible que debas experimentar con la configuración para encontrar el equilibrio óptimo entre velocidad e interrupción del entorno. Entre los factores que pueden afectar la frecuencia de actualización, se incluyen los siguientes:
- Baja disponibilidad de mantenimiento (por ejemplo, períodos de mantenimiento cortos).
- Grupos de nodos de Standard grandes
- Estrategia de actualización de nodos que prioriza la interrupción mínima en comparación con la velocidad.
- Algunas opciones de configuración de Pods. Consulta Consideraciones para la duración de actualización de nodos a fin de obtener más información.

Crea un clúster de Standard con un período de mantenimiento simple

Puedes crear un período de mantenimiento simple en la CLI de gcloud si especificas la marca --maintenance-window. Esta marca te permite especificar un período de mantenimiento diario de 4 horas con un formato simplificado. Para crear un clúster de Autopilot con un período de mantenimiento, usa la consola de Google Cloud.

Crea un clúster estándar nuevo con un período de mantenimiento simple:

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

Reemplaza lo siguiente:

CLUSTER_NAME: Es el nombre del clúster nuevo.
START_TIME: una marca de tiempo de 24 horas en UTC, como 16:00

El período de mantenimiento se ejecuta todos los días en el START_TIME especificado y durante cuatro horas.

Crea un período de mantenimiento personalizado

Puedes crear un período de mantenimiento que ocurra en ciertos momentos de la semana o del mes con los parámetros adicionales que se explican en esta sección.

Por ejemplo, con el siguiente comando, se crea un clúster llamado my-cluster con un período de mantenimiento habilitado a las 2:00 a.m. UTC del miércoles 19 de agosto de 2026. Este período de mantenimiento comienza los lunes y viernes y finaliza 30 horas más tarde. La primera instancia del período de mantenimiento comienza el viernes 21 de agosto a las 2:00 a.m. y finaliza el sábado 22 de agosto a las 8:00 a.m. Puedes obtener más información sobre el formato de fechas y 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 obtener más información, consulta los ejemplos de períodos de mantenimiento.

Crea un clúster con un período de mantenimiento

Puedes crear un clúster de Standard nuevo con un período de mantenimiento usando la CLI de gcloud o la consola de Google Cloud. Para crear un clúster de Autopilot nuevo con un período de mantenimiento, usa la consola de Google Cloud.

gcloud

Crea un clúster de Standard nuevo con un período de mantenimiento:

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

Reemplaza lo siguiente:

CLUSTER_NAME el nombre del clúster nuevo.
START_TIME: La fecha y la hora en que el período de mantenimiento recurrente está habilitado. Expresado como un valor DTSTART RFC-5545. Después de este período, el período de mantenimiento se repite según el RRULE. El START_TIME también proporciona a qué hora del día comienza el período de mantenimiento.
END_TIME: Es la hora de finalización para calcular la duración del período de mantenimiento, como se expresa en la cantidad de tiempo después del START_TIME, en el mismo formato. El valor de END_TIME debe ser posterior en relación con START_TIME.
RRULE: La recurrencia del período de mantenimiento, como lo expresa una RRULE RFC-5545. Este es un formato flexible con varias formas de especificar reglas de recurrencia, para determinar qué día comienza el período de mantenimiento. Por ejemplo, puedes especificar una recurrencia de ciertos momentos de una semana o un mes. Si la fecha END_TIME es mayor que la fecha START_TIME, el período de mantenimiento abarca varios días. Por ejemplo, un período de mantenimiento que comienza el domingo continuará hasta el lunes.

Console

Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

Ir a Google Kubernetes Engine
Haz clic en Crear.
Configura tu clúster.
En el panel de navegación, en Clústeres, haz clic en Automatización.
Selecciona la casilla de verificación Habilitar período de mantenimiento.
Selecciona la hora de inicio y la duración y, a continuación, selecciona los días de la semana en los que se activa el período de mantenimiento. Para editar directamente la especificación de la regla de recurrencia (RRule), selecciona RRule.
Haz clic en Crear.

Configura un período de mantenimiento para un clúster existente

gcloud

Crea o actualiza un período de mantenimiento para un clúster existente:

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

Reemplaza lo siguiente:

CLUSTER_NAME el nombre del clúster nuevo.
START_TIME: La fecha y la hora en que el período de mantenimiento recurrente está habilitado. Expresado como un valor DTSTART RFC-5545. Después de este período, el período de mantenimiento se repite según el RRULE. El START_TIME también proporciona a qué hora del día comienza el período de mantenimiento.
END_TIME: Es la hora de finalización para calcular la duración del período de mantenimiento, como se expresa en la cantidad de tiempo después del START_TIME, en el mismo formato. El valor de END_TIME debe ser posterior en relación con START_TIME.
RRULE: La recurrencia del período de mantenimiento, como lo expresa una RRULE RFC-5545. Este es un formato flexible con varias formas de especificar reglas de recurrencia, para determinar qué día comienza el período de mantenimiento. Por ejemplo, puedes especificar una recurrencia de ciertos momentos de una semana o un mes. Si la fecha END_TIME es mayor que la fecha START_TIME, el período de mantenimiento abarca varios días. Por ejemplo, un período de mantenimiento que comienza el domingo continuará hasta el lunes.

Console

Para crear o modificar un período de mantenimiento de un clúster existente, sigue estos pasos:

Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

Ir a Google Kubernetes Engine
En la lista de clústeres, haz clic en el nombre del clúster que deseas modificar.
En Automatización, haz clic en Editar política de mantenimiento junto al campo Período de mantenimiento.
Selecciona la casilla de verificación Habilitar período de mantenimiento.
Selecciona la hora de inicio y la duración y, a continuación, selecciona los días de la semana en los que se activa el período de mantenimiento. Para editar directamente la RRule, selecciona RRule.
Haz clic en Save Changes.

Finaliza de forma manual el mantenimiento incompleto

Si una actualización o algún otro mantenimiento automático demoran más en completar el período de mantenimiento, GKE intenta detener las tareas de mantenimiento en curso y las reanuda cuando se vuelva a realizar el período de mantenimiento. Si se cancela una actualización automática, y tienes habilitadas las actualizaciones automáticas de nodos, es posible que tus nodos presenten un estado de versión mixta, pero tu clúster debería funcionar con normalidad.

Para actualizar tu clúster de forma manual, o cancelar o revertir una actualización parcial, visita Actualiza un clúster.

Quita un período de mantenimiento

gcloud

Quita un período de mantenimiento de un clúster:

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

Reemplaza CLUSTER_NAME por el nombre del clúster existente.

Console

Para quitar un período de mantenimiento, sigue estos pasos:

Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

Ir a Google Kubernetes Engine
En la lista de clústeres, haz clic en el nombre del clúster que deseas modificar.
En Automatización, haz clic en Editar política de mantenimiento junto al campo Período de mantenimiento.
Desmarca la casilla de verificación Habilitar período de mantenimiento.
Haz clic en Save Changes.

Ejemplos de períodos de mantenimiento

En los siguientes ejemplos, se ilustran algunas de las diferentes maneras en que puedes configurar un período de mantenimiento. Solo se muestran las marcas relevantes, porque las marcas usan la misma sintaxis para crear un clúster nuevo o actualizar uno existente.

Fin de semana, a partir del 22 de agosto de 2026

En este ejemplo, la diferencia entre las marcas de tiempo de inicio y de finalización es de dos días completos, por lo que el período de mantenimiento se ejecuta durante todo el fin de semana, los sábados y domingos. Si deseas que la ventana tenga una duración diferente de exactamente 48 horas, modifica -start para que cambie cuando se inicie la ventana o -end para cambiar la duración total de la ventana.

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

Todos los días de lunes a viernes desde las 9:00 hasta las 17:00 UTC-4

En este ejemplo, se muestra cómo llevar a cabo un período de mantenimiento diario, pero se omiten los fines de semana. En este ejemplo, se especifica una zona horaria distinta a 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'

Cada semana a las 4:00 p.m. durante 8 horas, UTC-7

Si no especificas una zona horaria para --maintenance-window-start, se usa la hora local, como se configuró en tu cuenta de Google Cloud. La consola de Google Cloud siempre usa la 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'

Días de semana por la noche

En este ejemplo, se muestra un período de mantenimiento diario que se ejecuta durante la noche entre los días hábiles en la zona horaria UTC-7. En este ejemplo, la ventana se ejecuta desde las 20:00 de la noche hasta las 4:00 de la mañana.

 --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'

Configura una exclusión de mantenimiento

A fin de configurar una exclusión de mantenimiento para el clúster, debes especificar lo siguiente:

Nombre: es el nombre de la exclusión (opcional).
Hora de inicio: es la fecha y hora en que se debe comenzar el período de exclusión.
Hora de finalización: Es la fecha y hora de finalización del período de exclusión. Consulta la siguiente tabla para obtener información sobre las restricciones de duración de un período de exclusión para cada uno de los permisos disponibles.
Permiso: es el permiso de las actualizaciones automáticas que se restringirán. Consulta la siguiente tabla que enumera los permisos de exclusión disponibles.

Alcance	Descripción	Longitud máxima de la exclusión
Sin actualizaciones (predeterminado)	Excluye todos los parches y las actualizaciones menores. Evita las interrupciones de VM en el plano de control y los nodos del clúster debido a las actualizaciones.	No puede superar los 30 días
Sin actualizaciones secundarias	Excluye todas las actualizaciones menores. Las interrupciones de VM pueden ocurrir en el plano de control y en los nodos del clúster debido a las actualizaciones de parches.	No puede finalizar más de 180 días después de la fecha de creación de la exclusión. Además, en el caso de los clústeres inscritos en los canales rápidos, regulares o estables, no se puede extender más allá del fin de la asistencia estándar. En el caso de los clústeres inscritos en el canal extendido, no se puede extender más allá del fin de la asistencia extendida de la versión secundaria.
Sin actualizaciones secundarias ni de nodos	Excluye todas las actualizaciones secundarias y las actualizaciones de nodos. Evita las interrupciones de VM en los nodos del clúster debido a las actualizaciones. Sin embargo, pueden ocurrir interrupciones en el plano de control.	No puede finalizar más de 180 días después de la fecha de creación de la exclusión. Además, en el caso de los clústeres inscritos en los canales rápidos, regulares o estables, no se puede extender más allá del fin de la asistencia estándar. En el caso de los clústeres inscritos en el canal extendido, no se puede extender más allá del fin de la asistencia extendida de la versión secundaria.

Si deseas ver las definiciones de las versiones secundarias y de parche, consulta el Esquema del control de versiones.

Crea un clúster con una exclusión de mantenimiento

Puedes configurar una exclusión de mantenimiento cuando creas un clúster nuevo mediante la consola de Google Cloud. No se puede realizar esta tarea en la CLI de gcloud.

Para crear un clúster con una exclusión de mantenimiento, sigue estos pasos:

Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

Ir a Google Kubernetes Engine
Haz clic en Crear.
Configura tu clúster.
En el panel de navegación, en Clúster, haz clic en Automatización.
En Exclusiones de mantenimiento, haz clic en Agregar exclusión de mantenimiento.
Selecciona el Alcance, una Hora de inicio y una Hora de finalización.
Haz clic en Crear.

Puedes ver un ejemplo de la exclusión de mantenimiento para el Black Friday.

A fin de configurar una exclusión de mantenimiento para un clúster existente, haz lo siguiente:

Puedes configurar una exclusión de mantenimiento en un clúster existente con la consola de Google Cloud o la CLI de gcloud.

gcloud

Configura una exclusión de mantenimiento para un clúster 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

Reemplaza lo siguiente:

CLUSTER_NAME: El nombre de tu clúster.
EXCLUSION_NAME: Es el nombre de la exclusión de mantenimiento.
START_DATE_TIME: Es la fecha y la hora de inicio de la exclusión.
END_DATE_TIME: Es la fecha y hora de finalización de la exclusión.
SCOPE: Es el permiso de la actualización que se excluirá, que puede ser uno de los siguientes valores: no_upgrades, no_minor_upgrades o no_minor_or_node_upgrades.

Para ver los formatos de fecha y hora compatibles, ejecuta gcloud topic datetimes.

Console

A fin de configurar una exclusión de mantenimiento para un clúster existente, haz lo siguiente:

Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

Ir a Google Kubernetes Engine
En la lista de clústeres, haz clic en el nombre del clúster que deseas modificar.
En Automatización, junto al campo Exclusiones de mantenimiento, haz clic en Editar exclusiones de mantenimiento.
En Exclusiones de mantenimiento, haz clic en Agregar exclusión de mantenimiento.
Selecciona el Alcance, una Hora de inicio y una Hora de finalización.
Haz clic en Save Changes.

Quita una exclusión de mantenimiento

Puedes quitar las exclusiones de mantenimiento mediante la consola de Google Cloud o la CLI de gcloud.

gcloud

Quita una exclusión de mantenimiento existente:

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

Reemplaza lo siguiente:

CLUSTER_NAME: es el nombre del clúster existente.
EXCLUSION_NAME: es el nombre de la exclusión de mantenimiento que se quitará.

Console

Para quitar una exclusión de mantenimiento de un clúster existente, haz lo siguiente:

Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

Ir a Google Kubernetes Engine
En la lista de clústeres, haz clic en el nombre del clúster que deseas modificar.
En Automatización, junto al campo Exclusiones de mantenimiento, haz clic en Editar exclusiones de mantenimiento.
En Exclusiones de mantenimiento, haz clic en Borrar elemento junto al campo Hora de finalización de la exclusión que quieres quitar.
Haz clic en Save Changes.

Para ver todas las exclusiones de mantenimiento en un clúster, puedes ver la política de mantenimiento del clúster.

Ejemplo de exclusión de mantenimiento

En el siguiente ejemplo, se evita el mantenimiento durante los cuatro días que abarcan desde el Black Friday hasta el Cyber Monday, el período de ventas de mayor volumen del año para muchas empresas minoristas. En este ejemplo, se muestra cómo evitar que tenga lugar un período de mantenimiento desde el Black Friday 2021 (26 de noviembre de 2021) hasta el Cyber Monday 2021 (29 de noviembre de 2021) desde la medianoche del Este (UTC-5) hasta las 23:59:59 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

Visualiza la política de mantenimiento de un clúster

Para ver la política de mantenimiento de un clúster, que incluye ver si tiene si tiene un período de mantenimiento y todas sus exclusiones de mantenimiento, usa el siguiente comando:

gcloud container clusters describe CLUSTER_NAME

Soluciona problemas

La restricción del permiso de las exclusiones de mantenimiento solo se puede aplicar a los canales de versiones

Cuando restringes el permiso de las actualizaciones automáticas en una exclusión de mantenimiento, el clúster debe estar inscrito en un canal de versiones; de lo contrario, verás los siguientes errores:

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.

Las exclusiones de mantenimiento exceden el límite

Solo puedes especificar 3 exclusiones de mantenimiento como máximo que excluyan todas las actualizaciones (es decir, un permiso de “sin actualizaciones”); de lo contrario, recibirás el siguiente error:

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

Solo puedes especificar un máximo de 20 exclusiones de mantenimiento en total; de lo contrario, recibirás el siguiente error:

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

¿Qué sigue?

Obtén más información sobre las actualizaciones de clústeres y nodos
Obtén más información para Habilitar la actualización automática de nodos.
Aprende a recibir notificaciones del clúster.