Secuenciar el lanzamiento de las actualizaciones de clústeres con fases personalizadas

En este documento se muestra cómo gestionar las actualizaciones de clústeres de Google Kubernetes Engine (GKE) que usan la secuenciación de lanzamientos con fases personalizadas. Para crear una secuencia de lanzamiento, utiliza grupos de clústeres organizados en flotas y, opcionalmente, subconjuntos de clústeres de esas flotas. Puedes elegir el tiempo de prueba de resistencia que quieras después de que se completen las actualizaciones del clúster en un grupo (máximo 30 días). Puedes incluir clústeres Autopilot y Estándar. Para obtener más información sobre cómo funciona esta función, consulta Acerca de la secuenciación de lanzamientos con fases personalizadas.

Si gestionas lanzamientos en varias flotas, te recomendamos que uses un proyecto específico para alojar tus objetos RolloutSequence. Este proyecto actúa como elemento principal y coordinador de los lanzamientos de la secuencia. Este proyecto no suele formar parte de la secuencia, es decir, no contiene flotas ni clústeres que formen parte de la secuencia.

Antes de empezar

  • Instala Google Cloud CLI. Después de la instalación, inicializa la CLI de Google Cloud ejecutando el siguiente comando: 

    gcloud init

    Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  • Asegúrate de que tienes clústeres Autopilot o Standard. Para crear un clúster, consulta Crear un clúster de Autopilot.

  • (Opcional) Si aún no tienes un Google Cloud proyectoRolloutSequence dedicado para alojar tu configuración, crea uno con la Google Cloud consola u otro método.

  • Asegúrate de que has habilitado las APIs necesarias para las flotas. Estas APIs deben estar habilitadas en tus proyectos host de la flota para crear cualquier tipo de secuencia de lanzamiento. En el proyecto host de la secuencia de lanzamiento, habilita la API gkehub.googleapis.com.

Roles obligatorios

Para crear un proyecto, necesitas el rol de creador de proyectos (roles/resourcemanager.projectCreator), que incluye el permiso resourcemanager.projects.create. Consulta cómo asignar roles.

Para crear o modificar una secuencia de lanzamiento, debes tener el rol de gestión de identidades y accesos de editor de flota (roles/gkehub.editor) en cada proyecto de host de la secuencia de lanzamiento y en el proyecto de host de la secuencia de lanzamiento. Este rol proporciona los siguientes permisos:

  • gkehub.rolloutsequences.create
  • gkehub.rolloutsequences.get
  • gkehub.rolloutsequences.list
  • gkehub.rolloutsequences.update
  • gkehub.rolloutsequences.delete
  • gkehub.fleet.get

Estos permisos te permiten crear, acceder y modificar objetos RolloutSequence, así como usar flotas en la secuencia de lanzamiento.

Si necesitas registrar o anular el registro de clústeres en una flota, debes tener todos los permisos siguientes:

Para obtener más información sobre los roles de IAM con los mínimos privilegios necesarios para realizar diferentes tareas, consulta el artículo Obtener sugerencias de roles predefinidos con la ayuda de Gemini.

Configurar una secuencia de lanzamiento

Para crear una secuencia de lanzamiento, los clústeres deben organizarse en grupos de flotas. También puedes crear fases granulares que se dirijan a subconjuntos específicos de clústeres de una flota mediante etiquetas de Kubernetes. Para obtener información sobre cómo organizar tus clústeres, consulta el ejemplo de banco comunitario. Después de organizar los clústeres en grupos y, opcionalmente, etiquetarlos, crea una secuencia de lanzamiento definiendo la lista ordenada de fases y el tiempo de permanencia de cada grupo.

Organizar clústeres en flotas

En una secuencia de lanzamiento, recomendamos registrar todos los clústeres en el mismo canal de lanzamiento. Si los clústeres no están registrados en el mismo canal, GKE selecciona una versión del canal más conservador de la secuencia. Por ejemplo, si los clústeres están registrados en los canales Estable y Habitual, GKE elige la versión del canal Estable. También recomendamos que todos los clústeres ejecuten la misma versión secundaria para poder optar a la misma versión de actualización automática.

Si ya has organizado tus clústeres en flotas, puedes saltarte los pasos siguientes y pasar a la sección Crear subconjuntos de clústeres.

  1. Agrupa tus clústeres en flotas. Puedes organizar tus clústeres por entornos de implementación, como Pruebas, Desarrollo y Producción (opción recomendada).
  2. Registra cada clúster en una flota en función de la agrupación que hayas elegido.

Crear subconjuntos de clústeres (opcional)

Para que una fase de tu secuencia de lanzamiento se dirija a clústeres específicos, debes etiquetarlos.

Por ejemplo, para probar una nueva versión en un pequeño subconjunto de clústeres antes de una implementación completa, puedes aplicar una etiqueta canary a esos clústeres. Para añadir la etiqueta canary con el valor true a un clúster mediante la CLI de Google Cloud, ejecuta el siguiente comando:

gcloud container clusters update CLUSTER_NAME \
    --location=CLUSTER_LOCATION\
    --update-labels=canary=true

Haz los cambios siguientes:

La marca --update-labels=canary=true indica a GKE que aplique la etiqueta canary al clúster .

Para obtener más información sobre cómo añadir una etiqueta a un clúster, consulta Añadir o actualizar etiquetas de clústeres.

Crear una secuencia de lanzamiento con fases personalizadas

Una secuencia de lanzamiento define el orden de las actualizaciones mediante fases. Para crear una secuencia de lanzamiento, primero debes crear un archivo YAML que defina las fases y, a continuación, crear un RolloutSequence.

Para asegurarse de que la secuencia captura todos los clústeres, cada flota debe incluir una fase de captura general (una fase sin selector de etiquetas). Esta fase de captura de todos los elementos incluye todos los clústeres restantes que GKE no ha seleccionado en fases anteriores. Si asignas un mismo clúster a varias fases de un RolloutSequence, para resolver los conflictos, GKE asigna implícitamente el clúster solo a la fase más temprana.

La siguiente configuración de ejemplo crea tres fases:

  • La primera fase se dirige a todos los clústeres de la flota dev. Una vez completada la actualización, hay un periodo de prueba de 7 días (un valor de 604800 segundos).
  • La segunda fase se centra en los clústeres de la flota prod que tienen la etiqueta canary=true. Una vez completada la actualización, hay un periodo de prueba de 7 días.
  • La tercera fase se centra en los clústeres restantes de la flota prod. Una vez completada la actualización, hay un periodo de prueba de 7 días.

  1. Guarda el siguiente archivo de manifiesto como rollout-sequence.yaml:

    - stage:
  fleet-projects:
  - projects/dev
  soak-duration: 604800s
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s
  label-selector: resource.labels.canary=='true'
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s

    Ten en cuenta lo siguiente:

    • stage: incluye una flota o un subconjunto de clústeres de una flota. Los clústeres de las fases anteriores deben actualizarse por completo y someterse a pruebas de carga antes de que la secuencia pase a la siguiente fase. Sin embargo, si un clúster no ha terminado de actualizarse 30 días después de que se inicie el proceso de actualización, GKE comienza el periodo de estabilización.
    • fleet-projects: una lista de flotas entre las que seleccionar clústeres para esta fase. Se puede hacer referencia a una flota como máximo por fase. Una flota se identifica por el proyecto en el que está alojada. Este proyecto puede ser diferente del proyecto en el que se encuentran los clústeres si la flota contiene membresías entre proyectos. El formato para especificar un proyecto de flota es projects/PROJECT_ID.
    • label-selector (opcional): selecciona un subconjunto de clústeres de las flotas especificadas. Este campo usa la sintaxis del lenguaje de expresión común (CEL) y debe empezar por resource.labels.
    • soak-duration: tiempo de espera después de actualizar todos los clústeres de una fase anterior antes de pasar a la siguiente. Se expresa en segundos.

  2. Para crear la secuencia de lanzamiento que has definido en el rollout-sequence.yaml manifiesto, ejecuta el siguiente comando:

    gcloud beta container fleet rolloutsequences create ROLLOUT_SEQUENCE_NAME \
    --display-name=DISPLAY_NAME \
    --stage-config=rollout-sequence.yaml

    Haz los cambios siguientes:

    • ROLLOUT_SEQUENCE_NAME: un identificador inmutable que cumple las especificaciones de RFC-1034, por ejemplo, test-rollout-sequence.
    • DISPLAY_NAME: una cadena legible por humanos para tu secuencia de lanzamiento.

Consultar el estado de un lanzamiento

Después de configurar una secuencia de lanzamiento, el sistema crea automáticamente Rollout objetos para gestionar las actualizaciones. Puedes observar y monitorizar el progreso de estos objetos mediante comandos de la CLI de Google Cloud.

Mostrar lanzamientos

Para mostrar todos los lanzamientos activos y del historial del proyecto host de la secuencia de lanzamientos, ejecuta el siguiente comando:

gcloud beta container fleet rollouts list --project=HOST_PROJECT_ID

Sustituye HOST_PROJECT_ID por el ID del proyecto host de la secuencia de lanzamiento.

Puedes omitir la marca --project=HOST_PROJECT_ID si ya estás en el proyecto en el que se aloja tu secuencia de lanzamiento.

El resultado debería ser similar al siguiente:

NAME                                              STATE      CREATE_TIME
05eb251e4f19269e23-node-1-33-5-gke-1201000-t7mqd  COMPLETED  2025-10-30T20:07:46
05eb251e4f19269e23-kcp-1-33-5-gke-1201000-djwst   COMPLETED  2025-10-30T18:07:06
05eb251e4f19269e23-node-1-33-5-gke-1125000-6bxvu  COMPLETED  2025-10-23T17:46:54
05eb251e4f19269e23-kcp-1-33-5-gke-1125000-2f6ct   RUNNING    2025-10-23T16:41:33

En el resultado anterior, los nombres de los lanzamientos que contienen kcp hacen referencia a las actualizaciones del plano de control, y los nombres que contienen node hacen referencia a las actualizaciones de los nodos. El segmento del nombre del lanzamiento después de kcp o node se deriva de la versión de GKE.

Describe un lanzamiento

Para obtener información detallada sobre una implementación concreta, como la versión de destino, el estado y los clústeres que se han actualizado, usa el comando describe con el ID de implementación que has obtenido en el comando anterior:

gcloud beta container fleet rollouts describe ROLLOUT_ID \
  --project=HOST_PROJECT_ID

Haz los cambios siguientes:

  • ROLLOUT_ID: el ID de lanzamiento que has obtenido al enumerar los lanzamientos.
  • HOST_PROJECT_ID: el ID del proyecto en el que se aloja tu secuencia de lanzamiento.

Por ejemplo:

gcloud beta container fleet rollouts describe 927e9a989930cf3b55-kcp-1-32-4-gke-1106006 \
  --project=my-hostfleet

El resultado debería ser similar al siguiente:

createTime: '2025-05-26T11:47:29.909959672Z'
membershipStates:
  projects/dev-project-id/locations/us-central1/memberships/c-1:
    lastUpdateTime: '2025-05-26T12:20:55.601542481Z'
    targets:
    - cluster:   projects/dev-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-1234567890-abcdefg-hijklm-nopqrst
      state: SUCCEEDED
    stageAssignment: 1
  projects/dev-project-id/locations/us-central1/memberships/c-2:
    lastUpdateTime: '2025-05-26T12:22:57.151203493Z'
    targets:
    - cluster:   projects/dev-project-id/locations/us-central1/clusters/c-2
      operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-987654321-ghijkl-mno-pqr-stu-vwxyz
      state: SUCCEEDED
    stageAssignment: 1
  projects/prod-project-id/locations/us-central1/memberships/c-1:
    lastUpdateTime: '2025-05-26T13:03:34.134308942Z'
    targets:
    - cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-567891234-efghij-klm-nopq-rstu-vwxyz
      state: SUCCEEDED
    stageAssignment: 2
  projects/prod-project-id/locations/us-central1/memberships/c-2:
    lastUpdateTime: '2025-05-26T13:06:34.025261641Z'
    targets:
    - cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-765432198-01a7b896-67c2-523-6fjjh4-icmdydh
      state: SUCCEEDED
    stageAssignment: 2
name: projects/user-hostfleet/locations/global/rollouts/05eb251e4f19269e23-kcp-1-32-4-gke-1106006
rolloutSequence: projects/project-id/locations/global/rolloutSequences/my-sequence
state: COMPLETED
updateTime: '2025-07-22T07:36:51.052691989Z'
versionUpgrade:
  desiredVersion: 1.32.4-gke.1106006
  type: TYPE_CONTROL_PLANE
stages:
- state: COMPLETED
  endTime: '2025-05-26T12:22:28.828506491Z'
  stageNumber: 1
  startTime: '2025-05-26T11:48:28.772658427Z'
  soakDuration: 600s
- state: COMPLETED
  endTime: '2025-05-26T13:06:20.026390832Z'
  stageNumber: 2
  startTime: '2025-05-26T12:32:38.419372153Z'
  soakDuration: 600s

Información sobre el estado de un lanzamiento

Cuando describes un lanzamiento, los campos stages y membershipStates de la salida proporcionan el estado del progreso de cada fase y clúster de esa fase, respectivamente.

En la siguiente tabla se enumeran los posibles estados de una fase:

Estado Descripción
PENDING La actualización aún no ha empezado en esta fase.
RUNNING La actualización está en curso en esta fase. Si has configurado una ventana de mantenimiento para los clústeres de la fase, GKE espera a que se abra la ventana para actualizar los clústeres.
SOAKING Todos los clústeres de esta fase han completado sus actualizaciones y la fase se encuentra en el periodo de rodaje configurado.
FORCED_SOAKING La actualización ha tardado más del tiempo máximo (30 días), por lo que GKE ha iniciado la fase de estabilización de forma forzada. La actualización sigue en los clústeres restantes.
COMPLETED La fase de remojo ha finalizado y el lanzamiento pasa a la siguiente fase.

En la siguiente tabla se muestran los posibles estados de un clúster dentro de una secuencia:

Estado Descripción
PENDING La actualización está pendiente en este clúster.
INELIGIBLE Este clúster no cumple los requisitos para la actualización, posiblemente debido a una discrepancia de versión. El motivo por el que no se cumplen los requisitos se indica en el resultado.
RUNNING La actualización está en curso en este clúster.
SUCCEEDED La actualización se ha completado correctamente en este clúster.
FAILED No se ha podido realizar la actualización en este clúster. Los destinos fallidos se vuelven a intentar indefinidamente mientras su fase esté activa (en estado RUNNING o FORCED_SOAKING).

Gestionar una secuencia de lanzamiento

Puedes controlar las actualizaciones automáticas de clústeres con la secuenciación de lanzamientos de varias formas, tal como se explica en las siguientes secciones.

Enumera tus secuencias de lanzamiento

Para enumerar todas las secuencias de lanzamiento de tu proyecto host, ejecuta el siguiente comando:

gcloud beta container fleet rolloutsequences list --project=HOST_PROJECT_ID

Sustituye HOST_PROJECT_ID por el ID del proyecto host de la secuencia de lanzamiento.

Describe una secuencia de lanzamiento

Para ver los detalles de una secuencia de lanzamiento específica, ejecuta el siguiente comando:

gcloud beta container fleet rolloutsequences describe ROLLOUT_SEQUENCE_NAME \
  --project=HOST_PROJECT_ID

Haz los cambios siguientes:

  • ROLLOUT_SEQUENCE_NAME: el nombre de la secuencia de lanzamiento.
  • HOST_PROJECT_ID: el ID de tu proyecto host de la secuencia de lanzamiento.

El resultado debería ser similar al siguiente:

createTime: '2025-10-23T16:40:16.403871189Z'
displayName: my-display-name
name: projects/HOST_PROJECT_ID/locations/global/rolloutSequences/ROLLOUT_SEQUENCE_NAME
stages:
- clusterSelector:
    labelSelector: resource.labels.canary=='true'
  fleetProjects:
  - projects/FLEET_PROJECT_ID
  soakDuration: 600s
- fleetProjects:
  - projects/FLEET_PROJECT_ID
  soakDuration: 300s
uid: 5c5b2ac8-9d76-45f9-92ca-5e6bd3fbcaef
updateTime: '2025-10-23T17:11:57.285678399Z'

Modificar una secuencia de lanzamiento

Para modificar una secuencia de lanzamiento, edita el archivo de configuración YAML en el que la definiste. Por ejemplo, puedes actualizar el tiempo de remojo de una fase o actualizar la fase para cambiar el orden de las mejoras. Después de editar el archivo, aplique los cambios.

Por ejemplo, si has definido la secuencia de lanzamiento original en un archivo llamado rollout-sequence.yaml, edita el archivo según sea necesario. A continuación, ejecuta el siguiente comando:

gcloud beta container fleet rolloutsequences update test-rollout-sequence \
  --display-name="My Updated Rollout Sequence" \
  --stage-config=rollout-sequence.yaml

Eliminar una secuencia de lanzamiento

Para eliminar una secuencia de lanzamiento, ejecuta el siguiente comando:

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME \
  --project=HOST_PROJECT_ID

Haz los cambios siguientes:

  • ROLLOUT_SEQUENCE_NAME con el nombre de la secuencia de lanzamiento.
  • HOST_PROJECT_ID con el ID de tu proyecto host de la secuencia de lanzamiento.

Si eliminas una secuencia de lanzamiento, se cancelarán todos los lanzamientos en curso de esa secuencia. Los clústeres que formaban parte de la secuencia vuelven al comportamiento de actualización automática predeterminado de su canal de lanzamiento registrado.

Migrar una secuencia de lanzamiento a etapas personalizadas

Si usas la versión de secuenciación basada en flotas disponible de forma general, puedes migrar a una secuencia que use fases personalizadas creando un nuevo RolloutSequence que haga referencia a tus flotas.

Antes de migrar la secuencia, te recomendamos que hagas una copia de la configuración de la secuencia de lanzamiento actual.

Para migrar tu secuencia de lanzamiento, sigue estos pasos:

  1. Crea un proyecto específico Google Cloud para alojar tu secuencia de lanzamiento. Este proyecto no suele formar parte de la secuencia, es decir, no contiene flotas ni clústeres que formen parte de la secuencia.
  2. Si quieres que la secuencia de lanzamiento incluya clústeres específicos de una flota, añade etiquetas a esos clústeres. Este paso es opcional.

  3. Sigue las instrucciones que se indican en Crear una secuencia de lanzamiento con fases personalizadas.

    Por ejemplo, el siguiente manifiesto, denominado rollout-sequence-migrate.yaml, hace referencia a las flotas que ya existen en una secuencia de lanzamiento anterior. Este manifiesto describe tres fases, incluida una fase canary en la flota prod:

    - stage:
  fleet-projects:
  - projects/dev
  soak-duration: 604800s
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s
  label-selector: canary=true
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s

Inmediatamente después de definir un nuevo RolloutSequence para tus flotas, GKE empieza a actualizar las flotas según la nueva secuencia y elimina la configuración anterior.

Migrar una secuencia de lanzamiento con fases personalizadas a la secuencia de lanzamiento anterior

En esta sección se describe cómo volver del lanzamiento secuencial con fases personalizadas al modelo de secuenciación basado en flotas disponible de forma general. Este proceso implica eliminar la nueva RolloutSequence y restaurar la configuración original basada en la flota.

Evitar que se produzca una actualización desordenada durante la migración

Para evitar actualizaciones no deseadas o desordenadas mientras reconfiguras tu secuencia, aplica una exclusión de mantenimiento a tus clústeres de producción. Este paso pausa temporalmente todas las actualizaciones automáticas de esos clústeres. Por ejemplo, puedes configurar una exclusión de mantenimiento de tipo no upgrades en tus clústeres de producción.

Eliminar la secuencia de lanzamiento

Elimina el objeto RolloutSequence que gestiona tus clústeres. Si lo haces, se inhabilitará la función de fases personalizadas.

Para eliminar el RolloutSequence, ejecuta el siguiente comando:

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME

Sustituye ROLLOUT_SEQUENCE_NAME por el nombre de tu secuencia de lanzamiento.

Restaurar la configuración de la secuencia de lanzamiento anterior (sin fases personalizadas)

Después de eliminar el RolloutSequence, puedes restaurar la configuración original basada en la flota. Este proceso implica volver a crear las funciones de clusterupgrade con sus parámetros originales, incluidos los enlaces upstreamFleet y los tiempos de permanencia de cada flota de tu secuencia. Para obtener más información, consulta Crear una secuencia de lanzamiento.

Quitar las exclusiones de mantenimiento

Después de restaurar la configuración original de la secuencia de lanzamiento basada en la flota, elimine la exclusión de mantenimiento que aplicó en el primer paso de esta sección. GKE reanuda las actualizaciones automáticas, que ahora se rigen por la secuencia restaurada basada en la flota.

Siguientes pasos