Implementaciones de versiones canary en Cloud Run

En este documento, se describe cómo configurar y usar las implementaciones de versiones canary para implementar tus aplicaciones en Cloud Run. La versión canary de Cloud Deploy admite servicios de Cloud Run y grupos de trabajadores, pero no trabajos.

Una implementación de versiones canary es un lanzamiento progresivo de una versión nueva de tu aplicación, en la que aumentas gradualmente el porcentaje de tráfico enviado a la versión nueva mientras supervisas el rendimiento de la aplicación. Esto te ayuda a detectar posibles problemas con anticipación y minimizar el impacto en tus usuarios.

Cómo funcionan las implementaciones de versiones canary para Cloud Run

Cuando realizas una implementación en Cloud Run con una estrategia de implementación de versiones canary, Cloud Deploy actualiza tu servicio existente con una revisión nueva. La revisión nueva recibe un porcentaje especificado de tráfico, y la revisión anterior continúa recibiendo el resto. Aumentas gradualmente la división de tráfico a la revisión nueva con el tiempo.

Con Cloud Deploy, puedes configurar implementaciones de versiones canary en Cloud Run en una sola etapa o en varias etapas.

Las instrucciones que se incluyen aquí solo contienen lo que es específico para la configuración de versiones canary. En el documento Implementa un servicio, un trabajo o un grupo de trabajadores de Cloud Run, se incluyen las instrucciones generales para configurar y ejecutar tu canalización de implementación.

Asegúrate de contar con los permisos requeridos

Además de otros permisos de Identity and Access Management que necesitas para usar Cloud Deploy, necesitas los siguientes permisos para realizar acciones adicionales que podrían ser necesarias para una implementación de versiones canary:

  • clouddeploy.rollouts.advance
  • clouddeploy.rollouts.ignoreJob
  • clouddeploy.rollouts.cancel
  • clouddeploy.rollouts.retryJob
  • clouddeploy.jobRuns.get
  • clouddeploy.jobRuns.list
  • clouddeploy.jobRuns.terminate

Consulta Roles y permisos de IAM para obtener más información sobre qué roles disponibles incluyen estos permisos.

Prepara tu skaffold.yaml

Tu archivo skaffold.yaml define cómo se renderizan y se implementan las definiciones de servicio de Cloud Run. Para una implementación de versiones canary en Cloud Run, asegúrate de que apunte correctamente a tus archivos de definición de servicio y defina los artefactos de compilación necesarios (como las imágenes de contenedor). No se requiere ninguna configuración especial específica de versiones canary dentro de skaffold.yaml más allá de lo que se necesita para una implementación estándar. Puedes usar perfiles de Skaffold para administrar diferentes variaciones de definición de servicio para las fases canary personalizadas.

Prepara la definición de tu servicio o grupo de trabajadores

Tu archivo de definición de servicio normal de Cloud Run es suficiente, pero sin una sección traffic. Cloud Deploy administra la división del tráfico entre la última revisión correcta y la revisión nueva.

Servicio

Ejemplo de service.yaml (sin sección traffic):

 apiVersion: serving.knative.dev/v1
 kind: Service
 metadata:
   name: my-cloudrun-service
 spec:
   template:
     spec:
       containers:
       - image: gcr.io/my-project/my-cloudrun-app
         ports:
         - containerPort: 8080

Grupo de trabajadores

Ejemplo de worker-pool.yaml (sin sección instanceSplit):

 apiVersion: run.googleapis.com/v1
 kind: WorkerPool
 metadata:
   name: my-wp
   annotations:
     run.googleapis.com/launch-stage: BETA
 spec:
   template:
     spec:
       containers:
       - image: us-docker.pkg.dev/cloudrun/container/worker-pool

Configura una versión canary automatizada

Configura una versión canary automatizada directamente en la definición de tu canalización de entrega para una etapa específica de Cloud Run. Cloud Deploy le indica automáticamente a Cloud Run que divida el tráfico entre la última revisión estable y la revisión nueva según los porcentajes especificados.

serialPipeline:
  stages:
  - targetId: prod
    profiles: []
    strategy:
      canary:
        runtimeConfig:
          cloudRun:
            automaticTrafficControl: true
        canaryDeployment:
          percentages: [PERCENTAGES]
          verify:
            tasks: [TASKS]
          predeploy:
            tasks: [TASKS]
          postdeploy:
            tasks: [TASKS]

En esta configuración:

  • PERCENTAGES es una lista separada por comas de valores porcentuales que representan tus incrementos de versiones canary, por ejemplo [25, 50, 75]. Ten en cuenta que esto no incluye 100, ya que se supone una implementación del 100% en la versión canary y la controla la fase stable.

  • Puedes habilitar la verificación de la implementación si configuras la sección verify. Si lo haces, se agrega un trabajo verify a cada fase canary.

  • Puedes habilitar los hooks de implementación previa si configuras la predeploy sección. Si lo haces, se agrega un trabajo predeploy a la primera fase canary.

  • Puedes habilitar los hooks de implementación posterior si configuras la postdeploy sección. Si lo haces, se agrega un trabajo postdeploy a la fase stable.

  • Cada propiedad tasks en verify, predeploy y postdeploy consta de una o más tareas para ejecutar como parte de ese trabajo. Las tareas configuradas se ejecutarán de forma secuencial en el orden en que se definan.

Configura una versión canary automatizada personalizada

Esto combina la definición de fase personalizada (nombres, porcentajes, perfiles, verificación, hooks) con la administración automática de tráfico de Cloud Deploy para Cloud Run. Defines las fases, pero Cloud Deploy se encarga de indicarle a Cloud Run que cambie el tráfico según los porcentajes.

Para configurar esto, incluye la configuración runtimeConfig.cloudRun.automaticTrafficControl: true y la sección customCanaryDeployment (que define phaseConfigs) dentro del bloque strategy.canary. Cloud Deploy usará los perfiles de Skaffold especificados para renderizar la definición de servicio (que aún no debería tener una sección traffic), pero administrará automáticamente el tráfico según los porcentajes de fase.

serialPipeline:
  stages:
  - targetId: cloudrun-prod
    profiles: []
    strategy:
      canary:
        # Include runtimeConfig for automatic traffic management
        runtimeConfig:
          cloudRun:
            automaticTrafficControl: true
        # Include customCanaryDeployment for phase customization
        customCanaryDeployment:
          phaseConfigs:
          - phaseId: "warmup-cr"
            percentage: 10
            profiles: ["base-config"] # Profile rendering service def (no traffic stanza)
            verify:
              tasks: [TASKS]
          - phaseId: "scaling-cr"
            percentage: 50
            profiles: ["base-config"] # Can use the same profile
            verify:
              tasks: [TASKS]
          - phaseId: "stable"
            percentage: 100
            profiles: ["base-config"]
            verify:
              tasks: [TASKS]

Ejecuta la versión canary de Cloud Run

  1. Registra la canalización y los destinos: Aplica tu canalización de entrega y los archivos de configuración de destino de Cloud Run.

    
gcloud deploy apply --file=delivery-pipeline.yaml --region=REGION
gcloud deploy apply --file=cloudrun-targets.yaml --region=REGION

    La canalización de entrega incluye la configuración de versiones canary automatizada o personalizada para el entorno de ejecución elegido.

  2. Crea un lanzamiento: Inicia la implementación y proporciona el nombre de la imagen.

    
gcloud deploy releases create RELEASE_NAME \
                                --delivery-pipeline=PIPELINE_NAME \
                                --region=REGION

    La canalización de entrega identificada por PIPELINE_NAME contiene la configuración de versiones canary automatizada o personalizada que se describe en este documento.

  3. Avanza la versión canary:

    gcloud CLI 

    gcloud deploy rollouts advance ROLLOUT_NAME \
                            --release=RELEASE_NAME \
                            --delivery-pipeline=PIPELINE_NAME \
                            --region=REGION

    Aquí:

    ROLLOUT_NAME es el nombre del lanzamiento actual que avanzas a la siguiente fase.

    RELEASE_NAME es el nombre del lanzamiento del que forma parte este lanzamiento.

    PIPELINE_NAME es el nombre de la canalización de entrega que usas para administrar la implementación de este lanzamiento.

    REGION es el nombre de la región en la que se creó el lanzamiento, por ejemplo, us-central1. Este campo es obligatorio.

    Consulta la referencia del SDK de Google Cloud para obtener más información sobre el gcloud deploy rollouts advance comando.

    Google Cloud Consola de

    1. Abre la página Canalizaciones de entrega.

    2. Haz clic en tu canalización que se muestra en la lista de canalizaciones de entrega.

      En la página de detalles de la canalización de entrega, se muestra una representación gráfica del progreso de tu canalización de entrega.

    3. En la pestaña Lanzamientos, en Detalles de la canalización de entrega, haz clic en el nombre de tu lanzamiento.

      Se muestra la página de detalles del lanzamiento para ese lanzamiento.

      Detalles del lanzamiento en la consola de Google Cloud

      Ten en cuenta que, en este ejemplo, el lanzamiento tiene una fase canary-50 y una fase stable. Tu lanzamiento podría tener más fases o fases diferentes.

    4. Haz clic en Avanzar lanzamiento.

      El lanzamiento avanza a la siguiente fase.

Fases omitidas

Si implementas una versión canary y tu aplicación aún no se implementó en ese entorno de ejecución, Cloud Deploy omite la fase canary y ejecuta la fase estable. Consulta Omite las fases por primera vez para descubrir por qué sucede esto.

¿Qué sigue?