Reversiones, lanzamientos graduales y migración de tráfico

Cloud Run te permite especificar qué revisiones deben recibir tráfico y especificar los porcentajes de tráfico que recibe una revisión. Esta función te permite revertir a una revisión anterior, implementar una revisión de forma gradual y dividir el tráfico entre varias revisiones. En esta página, se describe cómo usar esta función para administrar el tráfico a las revisiones de Cloud Run.

Ten en cuenta que los ajustes de enrutamiento del tráfico no son instantáneos. Cuando cambies el tráfico de las revisiones, se completarán todas las solicitudes que están en proceso. Las solicitudes en tránsito no se descartarán y se pueden dirigir a una revisión nueva o a una revisión anterior durante el período de transición.

División del tráfico y afinidad de sesión

Si divides el tráfico entre varias revisiones con la afinidad de sesión habilitada, consulta Afinidad de sesión y división de tráfico para obtener detalles sobre el efecto de la afinidad de sesión en la división del tráfico.

Ciclo de vida de las divisiones de tráfico

Si divides el tráfico entre varias revisiones o asignas tráfico a una revisión anterior, todas las implementaciones posteriores usarán ese patrón de división de tráfico en el futuro. Para volver a usar solo la revisión más reciente sin división de tráfico, envía todo el tráfico a la revisión más reciente.

Roles obligatorios

Para obtener los permisos que necesitas para administrar los servicios y las revisiones de Cloud Run, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Para obtener una lista de los roles y los permisos de IAM asociados con Cloud Run, consulta Roles de IAM de Cloud Run y Permisos de IAM de Cloud Run. Si tu servicio de Cloud Run interactúa con las APIs de Google Cloud, como las bibliotecas cliente de Cloud, consulta la guía de configuración de identidades del servicio. Para obtener más información acerca de cómo otorgar roles, consulta Permisos de implementación y Administra el acceso.

Revierte a una revisión anterior

Para revertir a una revisión anterior, debes hacer lo siguiente:

Console

  1. En la consola de Google Cloud ve a Cloud Run:

    Ir a Cloud Run

  2. Ubicar el servicio en la lista de servicios y haz clic en él

  3. Hacer clic en la pestaña Revisions (Revisiones) para ver la lista de revisiones actuales de ese servicio

  4. En la lista de revisiones, debes hacer clic en el ícono de puntos suspensivos a la derecha de la revisión que deseas revertir:

    manage-traffic

  5. Hacer clic en Manage Traffic (Administrar tráfico) para ver el formulario de administración de tráfico:

    1. Selecciona la revisión anterior a la que deseas revertir en la lista desplegable.
    2. Establece el porcentaje de tráfico de esa revisión anterior en 100.
    3. Establece el porcentaje de la revisión actual en 0.
    4. Haz clic en Guardar.

gcloud

Usa el siguiente comando:

gcloud run services update-traffic SERVICE --to-revisions REVISION=100

  • Reemplaza SERVICE por el nombre del servicio.
  • Reemplaza REVISION por el nombre de la revisión a la que deseas revertir.

YAML

  1. Si creas un servicio nuevo, omite este paso. Si actualizas un servicio existente, descarga su configuración de YAML:

    gcloud run services describe SERVICE --format export > service.yaml

  2. Debajo del atributo spec, ubica y actualiza el atributo traffic a lo siguiente:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION
    percent: 100

    Reemplazar

    • REVISION por el nombre de la revisión que deseas revertir

  3. Reemplaza el servicio por la configuración nueva mediante el siguiente comando:

    gcloud run services replace service.yaml

  4. Espera a que se complete la actualización: deberías ver un mensaje que indica que la revisión desde la que estás revirtiendo se implementó y entrega 0 por ciento del tráfico.

Terraform

Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los comandos básicos de Terraform.

Agrega lo siguiente a tu archivo .tf:

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  template {}

  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"

  }
}

Lanzamiento gradual para las revisiones

Para lanzar una nueva revisión de manera gradual, haz lo siguiente:

Console

  1. En la consola de Google Cloud ve a Cloud Run:

    Ir a Cloud Run

  2. Selecciona un servicio en la lista de servicios.

  3. Hacer clic en Implementar una nueva revisión

  4. Debes completar el formulario de implementación según sea necesario, pero asegurarte de que la casilla de verificación Aplicar esta revisión inmediatamente no esté marcada

  5. Haz clic en Implementar.

  6. Hacer clic en Administrar tráfico.

  7. La revisión nueva aparece en la lista, pero con un porcentaje establecido como 0: no está entregando tráfico. En el formulario, haz lo siguiente:

    1. Establece el porcentaje deseado, por ejemplo, 5. Ten en cuenta que el porcentaje de la versión actual se reduce de forma automática en la misma cantidad.
    2. Haz clic en Guardar.
    3. Repite estos pasos para administrar el tráfico, pero con porcentajes cambiados, y aumenta el porcentaje según sea necesario para la revisión nueva. No es necesario volver a implementar para cambiar los porcentajes de tráfico.

gcloud

  1. Implementa la revisión que deseas lanzar de manera gradual y, en un principio, configúrala para que no reciba tráfico:

    gcloud run deploy --image IMAGE --no-traffic

    Reemplaza IMAGE por la imagen que implementas.

  2. Especifica el porcentaje de tráfico que deseas que maneje la revisión nueva, por ejemplo, un 5%:

    gcloud run services update-traffic SERVICE --to-revisions REVISION=PERCENTAGE
    • Reemplaza SERVICE por el nombre del servicio.
    • Reemplaza REVISION por el nombre de la revisión que implementas de manera gradual. Para especificar la última revisión, puedes usar LATEST, por ejemplo, LATEST=5.
    • Reemplaza PERCENTAGE por el porcentaje de tráfico que deseas enviar a la revisión nueva, por ejemplo, 5 para enviarle el 5% del tráfico.

  3. Una vez que el rendimiento de la revisión sea satisfactorio, repite el paso anterior update-traffic, pero aumenta el valor porcentual como desees.

YAML

  1. Si creas un servicio nuevo, omite este paso. Si actualizas un servicio existente, descarga su configuración de YAML:

    gcloud run services describe SERVICE --format export > service.yaml

  2. Realiza los cambios de configuración que desees en el servicio y especifica el nombre de la revisión que desees otorgarle a la revisión nueva:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
 template:
   metadata:
     annotations:
     ...
     name: REVISION-NAME

    Reemplazar

    • REVISION-NAME por el nombre que deseas que tenga la nueva revisión

  3. Debajo del atributo spec, ubica y actualiza el atributo traffic para que la nueva revisión entregue solo una pequeña cantidad de tráfico:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION-NEW
    percent: PERCENT-NEW
  - revisionName: REVISION-FORMER
    percent: PERCENT-FORMER

    Ten en cuenta que los porcentajes deben sumar 100. Reemplazar

    • REVISION-NEW por el nombre de la revisión que deseas realizar de manera gradual
    • REVISION-FORMER por el nombre de la revisión que entrega en este momento
    • PERCENT-NEW por el porcentaje de tráfico que deseas enviar a la nueva revisión, por ejemplo, usa 10 para enviar el 10% del tráfico a esa revisión.
    • PERCENT-FORMER por el porcentaje de tráfico que deseas enviar a la revisión anterior

  4. Espera a que se complete la actualización: deberías ver un mensaje que indica que la nueva revisión que estás lanzando de forma gradual se implementó y está entregando el valor de porcentaje de tráfico que usaste.

Terraform

Agrega lo siguiente a tu archivo .tf y actualiza de forma gradual el porcentaje de tráfico de la revisión anterior a la revisión más reciente. Ten en cuenta que cada cambio de tráfico requerirá que se ejecute otro terraform apply.

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  template {
    containers {
      # Image or image tag must be different from previous revision
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
  }

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # Deploy new revision with 0% traffic
    percent = 0
    type    = "TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST"
  }
}

Ingresa terraform apply para aplicar los cambios.

Divide el tráfico entre varias revisiones

Para dividir el tráfico entre dos o más revisiones, debes hacer lo siguiente:

Console

  1. En la consola de Google Cloud ve a Cloud Run:

    Ir a Cloud Run

  2. Ubicar el servicio en la lista de servicios y hacer clic en él

  3. Hacer clic en Administrar tráfico.

  4. Se muestra la revisión nueva actual. En el formulario, haz lo siguiente:

    1. Establece el porcentaje de la revisión actual en la división deseada.
    2. Selecciona una de las revisiones anteriores en la lista desplegable y configúrala en el porcentaje deseado.
    3. Para dividir el tráfico entre más revisiones, haz clic en Agregar revisión, selecciona la revisión deseada y establece el porcentaje en la división que desees.
    4. Haz clic en Guardar.

gcloud

Especifica las revisiones y el porcentaje de tráfico para cada revisión en una lista delimitada por comas:

gcloud run services update-traffic SERVICE --to-revisions LIST

  • Reemplaza SERVICE por el nombre del servicio.
  • Reemplaza LIST por una lista de revisiones y porcentajes delimitados por comas:
    REVISION1=PERCENTAGE1,REVISION2=PERCENTAGE2,REVISIONn=PERCENTAGEx
    por ejemplo, hello2-00005-red=25,hello2-00001-bod=25,hello2-00002-nan=50.

YAML

  1. Si creas un servicio nuevo, omite este paso. Si actualizas un servicio existente, descarga su configuración de YAML:

    gcloud run services describe SERVICE --format export > service.yaml

  2. Debajo del atributo spec, ubica y actualiza el atributo traffic para que la nueva revisión entregue solo una pequeña cantidad de tráfico:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION-A
    percent: PERCENT-A
  - revisionName: REVISION-B
    percent: PERCENT-B
  - revisionName: REVISION-C
    percent: PERCENT-C

    Ten en cuenta que los porcentajes deben sumar hasta 100. Reemplazar

    • REVISION-A, REVISION-B, REVISION-C por las revisiones a las que asignas tráfico.
    • PERCENT-A, PERCENT-B, PERCENT-C por el porcentaje de la revisión correspondiente.

  3. Reemplaza el servicio por la configuración nueva mediante el siguiente comando:

    gcloud run services replace service.yaml

  4. Espera a que se complete la actualización: deberías ver un mensaje que indica que la nueva revisión que estás lanzando de forma gradual se implementó y está entregando el 5 por ciento (o cualquier valor gradual que hayas usado) de tráfico.

Terraform

Agrega lo siguiente a tu archivo .tf:

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    revision = "green"
  }

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent  = 25
    revision = "green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    percent = 75
    # This revision needs to already exist
    revision = "blue"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }
}

Ingresa terraform apply para aplicar los cambios.

Envía todo el tráfico a la última revisión

Cuando implementas una revisión nueva, puedes hacer que esta revisión y todas las futuras entreguen el 100% del tráfico lo antes posible, lo que anula cualquier división de tráfico establecida:

Console

  1. En la consola de Google Cloud ve a Cloud Run:

    Ir a Cloud Run

  2. Ubicar el servicio en la lista de servicios y haz clic en él

  3. Hacer clic en Implementar una nueva revisión

  4. Debes completar el formulario de implementación según sea necesario y marcar la casilla de verificación Aplicar esta revisión inmediatamente. Esto anulará cualquier división de tráfico existente, y la revisión nueva entregará el 100% del tráfico.

  5. Haz clic en Implementar.

gcloud

Para enviar todo el tráfico a la última revisión que se implementó:

gcloud run services update-traffic SERVICE --to-latest

Reemplaza SERVICE por el nombre del servicio.

YAML

  1. Si creas un servicio nuevo, omite este paso. Si actualizas un servicio existente, descarga su configuración de YAML:

    gcloud run services describe SERVICE --format export > service.yaml

  2. Debajo del atributo spec, busca y actualiza el atributo traffic a lo siguiente:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - latestRevision: true
    percent: 100

  3. Reemplaza el servicio por la configuración nueva mediante el siguiente comando:

    gcloud run services replace service.yaml

  4. Espera a que se complete la actualización: deberías ver un mensaje que indica que la revisión (más reciente) se implementó y que está entregando el 100 por ciento del tráfico.

Terraform

Agrega lo siguiente a tu archivo .tf:

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  template {}

  traffic {
    percent = 100
    type    = "TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST"
  }
}

Ingresa terraform apply para aplicar los cambios.

Usa etiquetas para pruebas, migración de tráfico y reversión

Para evitar que se generen costos de facturación por las revisiones etiquetadas, usa las instancias mínimas a nivel de servicio o quita las etiquetas de las revisiones cuando ya no las necesites.

Un caso de uso común para esta función es usarla con el fin de probar y aprobar una revisión de servicio nueva antes de entregar tráfico, en esta secuencia típica:

  1. Ejecuta pruebas de integración en un contenedor durante el desarrollo.
  2. Implementa el contenedor en un proyecto de Google Cloud que uses solo para la etapa de pruebas y que no entregue tráfico. Luego, pruébalo con una revisión etiquetada.
  3. Impleméntalo en producción sin entregar tráfico y pruébalo con una revisión etiquetada en producción.
  4. Migra el tráfico a la revisión etiquetada.

Implementa una revisión etiquetada nueva

Para implementar una revisión nueva de un servicio existente en producción:

gcloud

Implementa una revisión etiquetada nueva

gcloud run deploy myservice --image IMAGE_URL  --no-traffic --tag TAG_NAME

Reemplazar

  • IMAGE_URL por la URL de la imagen
  • TAG_NAME por el nombre de la etiqueta en minúscula

La etiqueta te permite probar directamente la revisión nueva en una URL específica, sin entregar tráfico. La URL comienza con el nombre de etiqueta que proporcionaste: por ejemplo, si usaste el nombre de etiqueta green en el servicio myservice, debes probar la revisión etiquetada en la URL https://green---myservice-abcdef.a.run.app.

Terraform

Agrega lo siguiente a tu archivo .tf y actualiza de forma gradual el porcentaje de tráfico de la revisión anterior a la más reciente con la etiqueta nueva. Ten en cuenta que cada cambio de tráfico requerirá que se ejecute otro terraform apply.

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      # image or tag must be different from previous revision
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    revision = "blue"
  }

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # Deploy new revision with 0% traffic
    percent  = 0
    revision = "blue"
    tag      = "tag-name"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }
}

Ingresa terraform apply para aplicar los cambios.

Quita una etiqueta

Para quitar una etiqueta de una revisión, haz lo siguiente:

Console

  1. En la consola de Google Cloud ve a Cloud Run:

    Ir a Cloud Run

  2. Selecciona un servicio en la lista de servicios.

  3. Navega a la sección Revisiones dentro del servicio deseado y selecciona la revisión de la que deseas quitar la etiqueta existente.

  4. Coloca el puntero sobre la columna URL de revisión (etiquetas) y haz clic en el ícono de lápiz:

    borrar etiqueta

  5. En el menú del diálogo Revision URLs, haz clic en el ícono Papelera para quitar la etiqueta actual que se usa en la revisión.

  6. Haz clic en Guardar.

gcloud

Para quitar una etiqueta de revisión:

gcloud run services update-traffic SERVICE --remove-tags TAG_NAME

Reemplazar

  • TAG_NAME por el nombre de la etiqueta a la que migras el tráfico
  • SERVICE por el nombre del servicio del que deseas quitar la etiqueta

YAML

  1. Si creas un servicio nuevo, omite este paso. Si actualizas un servicio existente, descarga su configuración de YAML:

    gcloud run services describe SERVICE --format export > service.yaml

  2. Realiza los cambios de configuración deseados en el servicio.

  3. Debajo del atributo spec, ubica y quita el atributo tag para la revisión etiquetada:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION
    tag: TAG_NAME
    percent: PERCENT-NEW

  4. Reemplaza el servicio por la configuración nueva mediante el siguiente comando:

    gcloud run services replace service.yaml

Terraform

Agrega lo siguiente a tu archivo .tf:

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  template {}

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    percent = 100
    # This revision needs to already exist
    revision = "green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # No tags for this revision
    # Keep revision at 0% traffic
    percent = 0
    # This revision needs to already exist
    revision = "blue"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }
}

Ingresa terraform apply para aplicar los cambios.

Migra el tráfico a una revisión etiquetada

Después de confirmar que la revisión nueva funciona de forma correcta, puedes comenzar a migrar el tráfico mediante la consola de Google Cloud, la línea de comandos de gcloud, Terraform o un archivo YAML:

Console

  1. En la consola de Google Cloud ve a Cloud Run:

    Ir a Cloud Run

  2. Ubica el servicio en la lista de servicios y haz clic en él:

  3. Selecciona la revisión etiquetada a la que deseas enviar tráfico:

    manage-traffic

  4. Hacer clic en Administrar tráfico.

  5. Ubica el nombre de la revisión etiquetada; está en la lista, pero con un porcentaje establecido en 0, lo que implica que, en este momento, no está entregando tráfico. En el formulario Administrar tráfico*, haz lo siguiente:

    1. Establece el porcentaje deseado, por ejemplo, 5. Ten en cuenta que el porcentaje de la versión actual se reduce de forma automática en la misma cantidad.
    2. Haz clic en Guardar.
    3. Durante un período de horas o días, según sea necesario, repite estos pasos de Administrar tráfico, pero aumenta el porcentaje según sea necesario para la revisión etiquetada. No es necesario volver a implementar para cambiar los porcentajes de tráfico.

gcloud

Para migrar el tráfico a una etiqueta de revisión específica:

gcloud run services update-traffic myservice --to-tags TAG_NAME=TRAFFIC_PERCENT

Reemplazar

  • TAG_NAME por el nombre de la etiqueta a la que migras el tráfico
  • TRAFFIC_PERCENT por el porcentaje de tráfico que deseas que entregue la revisión etiquetada, por ejemplo, 1.

YAML

  1. Si creas un servicio nuevo, omite este paso. Si actualizas un servicio existente, descarga su configuración de YAML:

    gcloud run services describe SERVICE --format export > service.yaml

  2. Realiza los cambios de configuración que elijas en el servicio.

  3. Debajo del atributo spec, ubica y actualiza el atributo traffic para la revisión etiquetada de modo que la revisión etiquetada solo entregue una pequeña cantidad de tráfico:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: SERVICE
spec:
...
  traffic:
  - revisionName: REVISION
    tag: TAG_NAME
    percent: PERCENT-NEW
  - revisionName: REVISION-FORMER
    percent: PERCENT-FORMER

    Ten en cuenta que los porcentajes deben sumar 100. Reemplazar

    • REVISION por el nombre de la revisión etiquetada
    • TAG_NAME por el nombre de la etiqueta que lanzas de forma gradual
    • PERCENT-NEW por el porcentaje de tráfico que deseas enviar a la revisión etiquetada; por ejemplo, usa 10 para enviar el 10% del tráfico a esa revisión
    • REVISION-FORMER por el nombre de la revisión que entrega en este momento
    • PERCENT-FORMER por el porcentaje de tráfico que deseas enviar a la revisión anterior

  4. Reemplaza el servicio por la configuración nueva mediante el siguiente comando:

    gcloud run services replace service.yaml

  5. Espera a que se complete la actualización: deberías ver un mensaje que indica que la nueva revisión que estás lanzando de forma gradual se implementó y está entregando el valor de porcentaje de tráfico que usaste.

Terraform

Agrega lo siguiente a tu archivo .tf:

resource "google_cloud_run_v2_service" "default" {
  name     = "my-service"
  location = "us-central1"

  deletion_protection = false # set to true to prevent destruction of the resource

  template {}

  # Define the traffic split for each revision
  # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#traffic
  traffic {
    # Update revision to 50% traffic
    percent = 50
    # This revision needs to already exist
    revision = "green"
    type     = "TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION"
  }

  traffic {
    # Update tag to 50% traffic
    percent = 50
    # This tag needs to already exist
    tag = "tag-name"
  }
}

Durante un período de horas o días, según sea necesario, actualiza de una etiqueta a otra de forma gradual y aumenta el porcentaje para la revisión etiquetada según sea necesario.

Ingresa terraform apply después de cada cambio para aplicarlo.

¿Qué sigue?