Configura períodos de mantenimiento y exclusiones

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 el comando gcloud components update para obtener la versión más reciente. Es posible que las versiones anteriores de gcloud CLI no admitan la ejecución de los comandos de este documento.

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 Google Cloud console 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 Google Cloud console, 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 windows.

Configura un período de mantenimiento

Puedes configurar un período de mantenimiento en un clúster existente con la Google Cloud console o gcloud CLI.

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: Es el nombre del clúster.
  • 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. Esto solo calcula la duración del período y no se establece cuándo deja de repetirse el período de mantenimiento. Los períodos de mantenimiento solo dejan de repetirse cuando se quitan.
  • 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.

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

Console

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

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

    Ir a Google Kubernetes Engine

  2. En la lista de clústeres, haz clic en el nombre del clúster que deseas modificar.

  3. En Automatización, haz clic en Editar política de mantenimiento junto al campo Período de mantenimiento.

  4. Selecciona la casilla de verificación Habilitar período de mantenimiento.

  5. 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 Editor personalizado.

  6. 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:

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

    Ir a Google Kubernetes Engine

  2. En la lista de clústeres, haz clic en el nombre del clúster que deseas modificar.

  3. En Automatización, haz clic en Editar política de mantenimiento junto al campo Período de mantenimiento.

  4. Desmarca la casilla de verificación Habilitar período de mantenimiento.

  5. 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 Google Cloud cuenta. La Google Cloud consola 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. La hora de inicio debe ser ahora o en el futuro.
  • Hora de finalización: Es la fecha y hora de finalización del período de exclusión. Consulta la siguiente tabla para conocer las restricciones sobre la duración de un período de exclusión para cada uno de los permisos disponibles. Para ciertos permisos de exclusión de mantenimiento, puedes establecer la hora de finalización para hacer un seguimiento de la fecha de final de la compatibilidad de la versión secundaria de tu clúster.
  • 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 Plano de control Nodos Longitud máxima de la exclusión
Actualización secundaria automática Actualización de parches automática Actualización secundaria automática Actualización de parches automática
Sin actualizaciones (predeterminado) No permitido No permitido No permitido No permitido No puede superar los 30 días
Sin actualizaciones secundarias No permitido Permitido No permitido Permitido 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. Puedes configurar la hora de finalización para hacer un seguimiento del final de la compatibilidad de la versión secundaria de tu clúster. La exclusión de mantenimiento finaliza cuando la versión secundaria del clúster alcanza el final de la compatibilidad. Para obtener más información, consulta Cómo una exclusión de mantenimiento hace un seguimiento del final de la compatibilidad.
Sin actualizaciones secundarias ni de nodos No permitido Permitido No permitido No permitido 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. Puedes configurar la hora de finalización para hacer un seguimiento del final de la compatibilidad de la versión secundaria de tu clúster. La exclusión de mantenimiento finaliza cuando la versión secundaria del clúster alcanza el final de la compatibilidad. Para obtener más información, consulta Cómo una exclusión de mantenimiento hace un seguimiento del final de la compatibilidad.

Cómo configurar una exclusión de mantenimiento

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

Con la gcloud CLI, puedes configurar de forma opcional la hora de finalización de una exclusión de mantenimiento para hacer un seguimiento de la fecha de final de la compatibilidad de la versión secundaria de tu clúster.

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

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

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

  1. En la Google Cloud console, ve a la página Crea un clúster de Autopilot.

    Ir a Crea un clúster de Autopilot

    También puedes completar esta tarea creando un clúster de Standard.

  2. Configurar el clúster.

  3. En el panel de navegación, en Clúster, haz clic en Automatización.

  4. En Exclusiones de mantenimiento, haz clic en Agregar exclusión de mantenimiento.

  5. Selecciona el Alcance, una Hora de inicio y una Hora de finalización.

  6. 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 Google Cloud console o gcloud CLI. Con la gcloud CLI, puedes configurar de forma opcional la hora de finalización de una exclusión de mantenimiento para hacer un seguimiento de la fecha de final de la compatibilidad de la versión secundaria de tu clúster.

gcloud

  • Hora de finalización fija: Configura una exclusión de mantenimiento para un clúster existente con una hora de finalización fija:

    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: De manera opcional, establece la fecha y la hora de inicio de la exclusión para un momento en el futuro. Si omites esta marca, la exclusión de mantenimiento comienza de inmediato.
    • 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.

  • Finaliza al final de la compatibilidad: Configura una exclusión de mantenimiento que haga un seguimiento de la fecha de final de la compatibilidad de la versión secundaria de tu clúster:

    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

Console

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

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

    Ir a Google Kubernetes Engine

  2. En la lista de clústeres, haz clic en el nombre del clúster que deseas modificar.

  3. En Automatización, junto al campo Exclusiones de mantenimiento, haz clic en Editar exclusiones de mantenimiento.

  4. En Exclusiones de mantenimiento, haz clic en Agregar exclusión de mantenimiento.

  5. Selecciona el Alcance, una Hora de inicio y una Hora de finalización.

  6. Haz clic en Save Changes.

Quita una exclusión de mantenimiento

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

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:

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

    Ir a Google Kubernetes Engine

  2. En la lista de clústeres, haz clic en el nombre del clúster que deseas modificar.

  3. En Automatización, junto al campo Exclusiones de mantenimiento, haz clic en Editar exclusiones de mantenimiento.

  4. En Exclusiones de mantenimiento, haz clic en Borrar elemento junto al campo Hora de finalización de la exclusión que quieres quitar.

  5. 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

Identifica clústeres sin un período de mantenimiento configurado

GKE identifica los clústeres para los que no configuraste un período de mantenimiento para que puedas elegir un período recurrente en el que GKE pueda realizar el mantenimiento del clúster. Te recomendamos que configures un período de mantenimiento para garantizar que GKE realice actualizaciones automáticas y otro mantenimiento del clúster que respete las políticas de mantenimiento cuando sea más conveniente para tu entorno de clúster.

GKE entrega esta guía con una estadística y una recomendación a través del servicio de recomendador. Para obtener más información acerca de cómo administrar las estadísticas y las recomendaciones del recomendador, consulta Optimiza el uso de GKE con estadísticas y recomendaciones.

Para encontrar clústeres sin un período de mantenimiento configurado, puedes usar una de las siguientes formas:

  • Usa la Google Cloud console.
  • Usa gcloud CLI o la API de Recommender y especifica el CLUSTER_MAINTENANCE_WINDOW_AND_EXCLUSIONS subtipo de recomendador.

Para obtener instrucciones, consulta cómo ver estadísticas y recomendaciones.

Para implementar esta recomendación, configura un período de mantenimiento window.

Soluciona problemas

Usa la siguiente información para solucionar problemas comunes sobre períodos y exclusiones de mantenimiento.

El período de mantenimiento impide que se complete la actualización del nodo

Si tu clúster no puede finalizar las actualizaciones de nodos, como las actualizaciones de versiones de nodos, dentro del período de mantenimiento programado, esto puede ralentizar la frecuencia de actualizaciones o retrasar la finalización de los cambios en los nodos. Es posible que debas experimentar con tu configuración para encontrar el equilibrio óptimo entre la velocidad y la interrupción de tu entorno. Entre los factores que pueden afectar la frecuencia de actualización, se incluyen los siguientes:

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?