Configurar ventanas de mantenimiento y exclusiones

Usa ventanas y exclusiones de mantenimiento para controlar cuándo se puede y cuándo no se puede llevar a cabo el mantenimiento automático de los clústeres, 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 cuáles no las políticas de mantenimiento de GKE.

Antes de empezar

Antes de empezar, asegúrate de que has realizado las siguientes tareas:

• Habilita la API de Google Kubernetes Engine.
Habilitar la API de Google Kubernetes Engine
• Si quieres usar Google Cloud CLI para esta tarea, instálala y, a continuación, inicialízala. Si ya has instalado la gcloud CLI, obtén la versión más reciente ejecutando gcloud components update.

Configurar una ventana de mantenimiento

Para configurar una ventana de mantenimiento, especifica cuándo empieza, cuánto dura y con qué frecuencia se repite. Por ejemplo, puedes configurar una ventana de mantenimiento que se repita semanalmente de lunes a viernes durante cuatro horas cada día.

Puedes configurar una ventana de mantenimiento mediante la Trusted Cloud consola o la CLI de Google Cloud.

Consideraciones al configurar una ventana de mantenimiento

Cuando configures una ventana de mantenimiento, sigue estas directrices:

• Descubre qué tipos de eventos de mantenimiento respetan y cuáles no las ventanas 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 una ventana de mantenimiento por clúster. Si configuras una nueva, se sobrescribirá la anterior.
• Debes permitir al menos 48 horas de disponibilidad de mantenimiento en un periodo de 32 días. Solo se tienen en cuenta los periodos de disponibilidad contiguos de al menos 4 horas.
• Cuando se usa la consola Trusted Cloud , las horas siempre se muestran en la zona horaria local.
• Las repeticiones por día de la semana siempre se basan en la hora UTC. Por lo tanto, te recomendamos que definas las ventanas de mantenimiento que incluyan estas recurrencias completamente en UTC a través de la CLI de gcloud. Aunque se puede usar la hora local al definir las marcas, la zona horaria no se almacenará. Por ejemplo, si tu zona horaria es UTC+6 y quieres que una ventana de mantenimiento empiece a las 02:00 los miércoles en tu zona horaria, especifica el valor UTC de las 20:00 los martes. Para obtener más información, consulta Zonas horarias de las ventanas de mantenimiento.

La ventana de mantenimiento impide que se complete la actualización del nodo

Si tu clúster no puede completar las actualizaciones de los nodos, como las actualizaciones de la versión de los nodos, en la ventana de mantenimiento programada, esto puede ralentizar el ritmo de las actualizaciones o retrasar la finalización de los cambios en los nodos. Puede que tengas que experimentar con la configuración para encontrar el equilibrio óptimo entre velocidad e interrupción en tu entorno. Entre los factores que pueden afectar a la tasa de actualización se incluyen los siguientes:

• Baja disponibilidad de mantenimiento (por ejemplo, ventanas de mantenimiento cortas).
• Grupos de nodos Standard grandes.
• Estrategia de actualización de nodos: configuración que prioriza la mínima interrupción frente a la velocidad.
• Algunas opciones de configuración de los Pods. Consulta Consideraciones sobre la duración de la actualización de nodos para obtener más información.

Crear un clúster estándar con una ventana de mantenimiento sencilla

Puedes crear una ventana de mantenimiento sencilla en la CLI de gcloud especificando la marca --maintenance-window. Este indicador te permite especificar una ventana de mantenimiento diaria de 4 horas con un formato simplificado. Para crear un clúster de Autopilot con una ventana de mantenimiento, usa la Trusted Cloud consola.

Crea un clúster estándar con una ventana de mantenimiento sencilla:

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

Haz los cambios siguientes:

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

La ventana de mantenimiento se ejecuta cada día a la hora especificada START_TIME y dura cuatro horas.

Crear una ventana de mantenimiento personalizada

Puede crear una ventana de mantenimiento que se produzca en determinados momentos de la semana o del mes mediante los parámetros adicionales que se explican en esta sección.

Por ejemplo, el siguiente comando crea un clúster llamado my-cluster con una ventana de mantenimiento habilitada a las 02:00 (UTC) del viernes 23 de agosto del 2024. Esta ventana de mantenimiento se repite semanalmente todos los lunes y viernes, y finaliza 30 horas después. La primera vez que se produce la ventana de mantenimiento es el viernes 23 de agosto a las 2:00 y finaliza el sábado 24 de agosto a las 8:00. Puedes consultar más información sobre el formato de fechas y 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 ver más casos prácticos, consulta los ejemplos de ventanas de mantenimiento.

Crear un clúster con una ventana de mantenimiento

Puedes crear un clúster estándar con una ventana de mantenimiento mediante la CLI de gcloud o la Trusted Cloud consola. Para crear un clúster de Autopilot con una ventana de mantenimiento, usa laTrusted Cloud consola.

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

Configurar una ventana de mantenimiento para un clúster

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

Finalizar manualmente el mantenimiento incompleto

Si una actualización u otro mantenimiento automático tarda más en completarse que la ventana de mantenimiento, GKE intenta detener las tareas de mantenimiento en curso y las reanuda durante la próxima ventana de mantenimiento. Si se cancela una actualización automática y tienes habilitadas las actualizaciones automáticas de nodos, es posible que tus nodos tengan versiones mixtas, pero el clúster debería funcionar con normalidad.

Para actualizar manualmente tu clúster, o cancelar o revertir una actualización parcial, consulta el artículo Actualizar manualmente un clúster.

Eliminar una ventana de mantenimiento

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

Ejemplos de ventanas de mantenimiento

En los siguientes ejemplos se muestran algunas de las diferentes formas en las que puedes configurar una ventana de mantenimiento. Solo se muestran las marcas relevantes, ya que las marcas usan la misma sintaxis para crear un clúster o actualizar uno que ya exista.

Fines de semana a partir del 22 de agosto del 2026

En este ejemplo, la diferencia entre las marcas de tiempo de inicio y finalización es de dos días completos, por lo que la ventana de mantenimiento se ejecuta durante todo el fin de semana, es decir, los sábados y los domingos. Si quiere que la ventana tenga una duración diferente a 48 horas, modifique -start para cambiar el momento en que empieza 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 laborables de 9:00 a 17:00 (UTC-4)

En este ejemplo se muestra cómo tener una ventana de mantenimiento diaria, pero sin incluir los fines de semana. En este ejemplo se especifica una zona horaria que no es 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 a las 16:00 durante 8 horas (UTC-7)

Si no especificas una zona horaria para --maintenance-window-start, se usará la hora local configurada en tu cuenta de Trusted Cloud . La consola Trusted 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'

Noches entre semana

En este ejemplo se muestra una ventana de mantenimiento diaria que se ejecuta por la noche entre los días laborables en la zona horaria UTC-7. En este ejemplo, el intervalo va desde las 20:00 de la tarde hasta las 4:00 de la mañana siguiente.

   --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 una exclusión de mantenimiento

Para configurar una exclusión de mantenimiento en tu clúster, debes especificar lo siguiente:

• Nombre: el nombre de la exclusión (opcional).
• Hora de inicio: la fecha y la hora en las que debe empezar el periodo de exclusión. La hora de inicio debe ser la actual o una posterior.
• Hora de finalización: la fecha y la hora en las que debe finalizar el periodo de exclusión. Consulta la siguiente tabla para ver las restricciones sobre la duración de un periodo de exclusión para cada uno de los ámbitos disponibles.
• Ámbito: el ámbito de las actualizaciones automáticas que se van a restringir. Consulta la siguiente tabla, en la que se enumeran los ámbitos de exclusión disponibles.

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

Puedes configurar una exclusión de mantenimiento al crear un clúster mediante la consola de Trusted Cloud . Esta tarea no se puede realizar en la CLI de gcloud.

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

1. En la Trusted Cloud consola, ve a la página Crear un clúster de Autopilot.

   Ir a Crear un clúster de Autopilot

   También puedes completar esta tarea creando un clúster estándar.

2. Configura el clúster.

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

4. En Exclusiones de mantenimiento, haz clic en add Añadir exclusión de mantenimiento.

5. Selecciona el ámbito, la hora de inicio y la hora de finalización.

6. Haz clic en Crear.

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

Configurar una exclusión de mantenimiento para un clúster

Puedes configurar una exclusión de mantenimiento en un clúster que ya tengas mediante la consola o la CLI de gcloud.Trusted Cloud

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

Quitar una exclusión de mantenimiento

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

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

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

Ejemplo de exclusión de mantenimiento

En el siguiente ejemplo, se impide el mantenimiento durante los cuatro días que abarcan el Black Friday y el Cyber Monday, el periodo de ventas de mayor volumen del año para muchas empresas del sector retail. En este ejemplo se muestra cómo evitar que se produzca una ventana de mantenimiento desde el Black Friday del 2021 (26 de noviembre del 2021) hasta el Cyber Monday del 2021 (29 de noviembre del 2021), desde la medianoche (UTC-5) hasta las 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

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

Para ver la política de mantenimiento de un clúster, incluido si tiene una ventana de mantenimiento y todas sus exclusiones de mantenimiento, usa el siguiente comando:

gcloud container clusters describe CLUSTER_NAME

Identificar clústeres sin una ventana de mantenimiento configurada

GKE identifica los clústeres para los que no has configurado una ventana de mantenimiento para que puedas elegir una ventana periódica en la que GKE pueda realizar el mantenimiento del clúster. Te recomendamos que configures una ventana de mantenimiento para asegurarte de que GKE realice actualizaciones automáticas y otras tareas de mantenimiento del clúster que respeten las políticas de mantenimiento cuando sea más conveniente para tu entorno de clúster.

GKE ofrece estas directrices con información valiosa y recomendaciones a través del servicio Recommender. Para obtener más información sobre cómo gestionar las estadísticas y las recomendaciones de Recommender, consulta el artículo Optimizar el uso de GKE con estadísticas y recomendaciones.

Para encontrar clústeres sin una ventana de mantenimiento configurada, puedes usar uno de los siguientes métodos:

• Usa la consola Trusted Cloud .
• Usa gcloud CLI o la API Recommender especificando 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 una ventana de mantenimiento.

Solución de problemas

La restricción del ámbito de las exclusiones de mantenimiento solo se puede aplicar a los canales de lanzamiento

Cuando restringes el alcance de las actualizaciones automáticas en una exclusión de mantenimiento, el clúster debe estar registrado en un canal de lanzamiento. De lo contrario, es posible que se produzcan 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.

Se ha superado el límite de exclusiones de mantenimiento

Solo puede especificar un máximo de 3 exclusiones de mantenimiento que excluyan todas las actualizaciones (es decir, un ámbito de "sin actualizaciones"). De lo contrario, recibirá el siguiente error:

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

Solo puede especificar un máximo de 20 exclusiones de mantenimiento en total. De lo contrario, recibirá el siguiente error:

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

Siguientes pasos

• Consulta más información sobre las actualizaciones de clústeres y nodos.
• Consulta cómo habilitar la actualización automática de nodos.
• Consulta información sobre las notificaciones de clústeres.