Establece una secuencia para el lanzamiento de las actualizaciones de los clústeres con etapas personalizadas

En este documento, se muestra cómo administrar las actualizaciones de clústeres de Google Kubernetes Engine (GKE) que usan secuencias de lanzamientos con etapas personalizadas. Para crear una secuencia de lanzamiento, usa grupos de clústeres organizados en flotas y, de manera opcional, subconjuntos de clústeres de esas flotas. Puedes elegir cuánto tiempo de prueba deseas después de que se completen las actualizaciones de clústeres en un grupo (30 días como máximo). Puedes incluir clústeres de Autopilot y Standard. Para obtener más información sobre cómo funciona esta función, consulta Acerca de la secuenciación de lanzamiento con etapas personalizadas.

Si administras lanzamientos en varias flotas, te recomendamos que uses un proyecto dedicado para alojar tus objetos RolloutSequence. Este proyecto actúa como coordinador y superior de las versiones en toda la secuencia. Por lo general, este proyecto no forma parte de la secuencia, es decir, no contiene flotas ni clústeres que sí formen parte de ella.

Antes de comenzar

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

    gcloud init

    Si usas un proveedor de identidad (IdP) externo, primero debes acceder a la gcloud CLI con tu identidad federada.

  • Asegúrate de tener clústeres existentes de Autopilot o Standard. Para crear un clúster nuevo, consulta Crea un clúster de Autopilot.

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

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

Roles obligatorios

Para crear un proyecto, necesitas el rol de creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

Para crear o modificar una secuencia de lanzamiento, debes tener el rol de IAM de editor de flota (roles/gkehub.editor) en cada proyecto host de la flota de la secuencia de lanzamiento y en el proyecto 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, y usar flotas en la secuencia de lanzamiento.

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

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

Configura una secuencia de lanzamiento

Para crear una secuencia de lanzamiento, tus clústeres deben estar organizados en grupos de flotas. También puedes crear etapas detalladas que se pueden segmentar para subconjuntos específicos de clústeres dentro de una flota con etiquetas de Kubernetes. Para obtener orientación sobre cómo organizar tus clústeres, consulta el ejemplo del banco comunitario. Después de organizar los clústeres en grupos y, de manera opcional, etiquetarlos, debes crear una secuencia de lanzamiento definiendo la lista ordenada de etapas y el tiempo de prueba para cada grupo.

Organiza los clústeres en flotas

En una secuencia de lanzamiento, recomendamos inscribir todos los clústeres en el mismo canal de versiones. Si los clústeres no están inscritos 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 inscritos en los canales Estable y Regular, GKE elige la versión del canal Estable. También recomendamos que todos los clústeres ejecuten la misma versión secundaria para que sean aptos para la misma versión de destino de actualización automática.

Si ya organizaste tus clústeres en flotas, puedes omitir los siguientes pasos y continuar con la sección Crea subconjuntos de clústeres.

  1. Agrupa tus clústeres en flotas. Puedes organizar tus clústeres por entornos de implementación, como Pruebas, Etapa de pruebas y Producción (recomendado).
  2. Registra cada clúster con una flota según la agrupación elegida.

Crea subconjuntos de clústeres (opcional)

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

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

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

Reemplaza lo siguiente:

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 agregar una etiqueta a un clúster, consulta Agrega o actualiza etiquetas en clústeres existentes.

Crea una secuencia de lanzamiento con etapas personalizadas

Una secuencia de lanzamiento define el orden de las actualizaciones por etapas. Para crear una secuencia de lanzamiento, primero debes crear un archivo YAML que defina las etapas y, luego, crear un RolloutSequence.

Para garantizar que la secuencia capture todos los clústeres, cada flota debe incluir una etapa general (una etapa sin un selector de etiquetas). Esta etapa general captura todos los clústeres restantes que GKE no seleccionó en etapas anteriores. Si asignas un solo clúster a varias etapas dentro de un solo RolloutSequence, para resolver conflictos, GKE asigna implícitamente el clúster solo a la etapa más temprana.

En el siguiente ejemplo de configuración, se crean tres etapas:

  • La primera etapa se dirige a todos los clústeres de la flota dev. Una vez que se completa la actualización, hay un tiempo de prueba de 7 días (un valor de 604800 segundos).
  • La segunda etapa segmenta los clústeres de la flota prod que tienen la etiqueta canary=true. Una vez que se completa la actualización, hay un tiempo de estabilización de 7 días.
  • La tercera etapa se dirige a los clústeres restantes de la flota prod. Una vez que se completa la actualización, hay un período de estabilización de 7 días.

  1. Guarda el siguiente 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 dentro de una flota. Los clústeres en etapas anteriores deben actualizarse y probarse por completo antes de que la secuencia avance a la siguiente etapa. Sin embargo, si un clúster no finalizó la actualización 30 días después de que comenzó el proceso, GKE inicia el período de prueba.
    • fleet-projects: Es una lista de flotas desde las que se pueden seleccionar clústeres para esta etapa. Se puede hacer referencia a un máximo de una flota por etapa. Una flota se identifica por el proyecto en el que se aloja. Este proyecto puede ser diferente del proyecto en el que residen 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 de Common Expression Language (CEL) y debe comenzar con resource.labels.
    • soak-duration: Es el tiempo de espera después de actualizar todos los clústeres en una etapa anterior antes de continuar con la siguiente etapa. Se expresa en segundos.

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

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

    Reemplaza lo siguiente:

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

Verifica el estado de un lanzamiento

Después de configurar una secuencia de lanzamiento, el sistema crea automáticamente objetos Rollout para administrar las actualizaciones. Puedes observar y hacer un seguimiento del progreso de estos objetos con los comandos de Google Cloud CLI.

Enumera lanzamientos

Para enumerar todos los lanzamientos activos y los históricos en el proyecto host de la secuencia de lanzamiento, ejecuta el siguiente comando:

gcloud beta container fleet rollouts list --project=HOST_PROJECT_ID

Reemplaza HOST_PROJECT_ID por el ID de tu 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 es similar a lo 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 la implementación que contienen kcp hacen referencia a las actualizaciones del plano de control, y los nombres que contienen node hacen referencia a las actualizaciones de nodos. El segmento del nombre de la versión de lanzamiento después de kcp o node se deriva de la versión de GKE.

Describe un lanzamiento

Para obtener información detallada sobre un lanzamiento en particular, incluida la versión de destino, el estado y los clústeres que se actualizaron, usa el comando describe con el ID del lanzamiento que obtuviste del comando anterior:

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

Reemplaza lo siguiente:

  • ROLLOUT_ID: ID de la versión que obtuviste cuando enumeraste las versiones.
  • HOST_PROJECT_ID: Es 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 es similar a lo 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 de estado de un lanzamiento

Cuando describes un lanzamiento, los campos stages y membershipStates del resultado proporcionan el estado de progreso de cada etapa y clúster dentro de esa etapa, respectivamente.

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

Estado Descripción
PENDING La actualización aún no comenzó para esta etapa.
RUNNING La actualización está en curso para esta etapa. Si configuraste un período de mantenimiento para los clústeres en la etapa, GKE espera a que se abra el período antes de actualizar los clústeres.
SOAKING Todos los clústeres en esta etapa completaron sus actualizaciones, y la etapa se encuentra en su período de prueba configurado.
FORCED_SOAKING La actualización tardó más que el tiempo máximo de actualización (30 días) y, por lo tanto, GKE inició la fase de prueba de forma forzada. La actualización aún continúa en los clústeres restantes.
COMPLETED La etapa finalizó su período de permanencia y el lanzamiento continúa con la siguiente etapa.

En la siguiente tabla, se enumeran los estados posibles 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 es apto para la actualización, posiblemente debido a una discrepancia de versión. El motivo por el que no cumple con los requisitos se proporciona en el resultado.
RUNNING La actualización está en curso en este clúster.
SUCCEEDED La actualización se completó correctamente en este clúster.
FAILED No se pudo realizar la actualización en este clúster. Los destinos con errores se reintentan de forma indefinida mientras su etapa está activa (en estado RUNNING o FORCED_SOAKING).

Administra una secuencia de lanzamiento

Puedes controlar las actualizaciones automáticas del clúster con la secuencia de lanzamiento de varias maneras, que se explican en las siguientes secciones.

Enumera tus secuencias de lanzamiento

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

gcloud beta container fleet rolloutsequences list --project=HOST_PROJECT_ID

Reemplaza HOST_PROJECT_ID por el ID de tu 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

Reemplaza lo siguiente:

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

El resultado es similar a lo 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'

Modifica una secuencia de lanzamiento

Puedes modificar una secuencia de lanzamiento existente editando el archivo de configuración YAML en el que definiste la secuencia. Por ejemplo, puedes actualizar el tiempo de prueba de una etapa o actualizar la etapa para cambiar el orden de las actualizaciones. Después de editar el archivo, aplica los cambios.

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

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

Cómo borrar una secuencia de lanzamiento

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

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

Reemplaza lo siguiente:

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

Cuando borras una secuencia de lanzamiento, se cancelan todos los lanzamientos en curso de esa secuencia. Los clústeres que formaban parte de la secuencia vuelven al comportamiento predeterminado de actualización automática para su canal de versiones inscrito.

Migra una secuencia de lanzamiento existente para usar etapas personalizadas

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

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

Para migrar tu secuencia de lanzamiento, completa los siguientes pasos:

  1. Crea un proyecto Google Cloud dedicado para alojar tu secuencia de lanzamiento. Por lo general, este proyecto no forma parte de la secuencia, es decir, no contiene flotas ni clústeres que sí formen parte de la secuencia.
  2. Si deseas que la secuencia de lanzamiento incluya clústeres específicos dentro de una flota, agrega etiquetas a esos clústeres. Este paso es opcional.

  3. Sigue las instrucciones en Crea una secuencia de lanzamiento con etapas personalizadas.

    Por ejemplo, el siguiente manifiesto, llamado rollout-sequence-migrate.yaml, hace referencia a las versiones existentes en una secuencia de lanzamiento anterior. En este manifiesto, se describen tres etapas, incluida una etapa de canary en la flota de 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 que definas un nuevo RolloutSequence para tus flotas, GKE comenzará a actualizarlas según la nueva secuencia y quitará la configuración anterior.

Migra una secuencia de lanzamiento con etapas personalizadas a la secuencia de lanzamiento anterior

En esta sección, se describe cómo volver de la secuenciación de lanzamientos con etapas personalizadas al modelo de secuenciación basado en flotas disponible de forma general. Este proceso implica borrar el nuevo RolloutSequence y restablecer la configuración original basada en la flota.

Evita la actualización desordenada durante la migración

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

Borra la secuencia de lanzamiento

Borra el objeto RolloutSequence que administra tus clústeres. Esta eliminación desactiva la función de etapas personalizadas.

Para borrar el RolloutSequence, ejecuta el siguiente comando:

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME

Reemplaza ROLLOUT_SEQUENCE_NAME por el nombre de tu secuencia de lanzamiento.

Restablece la configuración anterior de la secuencia de lanzamiento (sin etapas personalizadas)

Después de borrar el RolloutSequence, puedes restablecer 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 vínculos de upstreamFleet y los tiempos de absorción de cada flota en tu secuencia. Para obtener más información, consulta Crea una secuencia de lanzamiento.

Quita las exclusiones de mantenimiento

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

Pasos siguientes