Prácticas recomendadas para Workflows

Puedes consultar las prácticas recomendadas que se mencionan aquí cuando organices tus servicios con Workflows.

Esta no es una lista exhaustiva de recomendaciones y no te enseña los conceptos básicos para usar Workflows. En este documento, se supone que ya tienes una comprensión general del panorama general Google Cloud y de Workflows. Para obtener más información, consulta el Google Cloud Well-Architected Framework y la descripción general de Workflows.

Selecciona un patrón de comunicación óptimo

Cuando diseñes una arquitectura de microservicios para implementar varios servicios, puedes seleccionar entre los siguientes patrones de comunicación:

  • Comunicación directa entre servicios

  • Comunicación indirecta basada en eventos (también conocida como coreografía)

  • Configuración, coordinación y administración automatizadas (también conocidas como organización)

Asegúrate de tener en cuenta los beneficios y las desventajas de cada una de las opciones anteriores y selecciona un patrón óptimo para tu caso de uso. Por ejemplo, la comunicación directa entre servicios puede ser más fácil de implementar que otras opciones, pero une tus servicios de forma más estrecha. Por el contrario, una arquitectura basada en eventos te permite unir tus servicios de forma más flexible. Sin embargo, la supervisión y la depuración pueden ser más complicadas. Por último, un organizador central como Workflows, aunque es menos flexible, te permite coordinar la comunicación entre servicios sin el acoplamiento alto de la comunicación directa entre servicios ni la complejidad de los eventos coreografiados.

También puedes combinar patrones de comunicación. Por ejemplo, en la organización basada en eventos, los servicios relacionados se administran en una organización que se activa mediante un evento. Del mismo modo, puedes diseñar un sistema en el que una organización genere un mensaje de Pub/Sub a otro sistema organizado.

Sugerencias generales

Una vez que decidas usar Workflows como organizador de servicios, ten en cuenta las siguientes sugerencias útiles.

Evita codificar URLs

Puedes admitir flujos de trabajo que sean portátiles en varios entornos y más fáciles de mantener si evitas las URLs codificadas. Puedes lograrlo de las siguientes maneras:

  • Define las URLs como argumentos de tiempo de ejecución.

    Esto puede ser útil cuando se invoca tu flujo de trabajo a través de una biblioteca cliente o la API. (Sin embargo, esto no funcionará si tu flujo de trabajo se activa mediante un evento de Eventarc y el único argumento que se puede pasar es la carga útil del evento).

    Ejemplo

    main:
  params: [args]
  steps:
    - init:
        assign:
          - url1: ${args.urls.url1}
          - url2: ${args.urls.url2}

    Cuando ejecutas el flujo de trabajo, puedes especificar las URLs. Por ejemplo:

    gcloud workflows run multi-env --data='{"urls":{"url1": "URL_ONE", "url2": "URL_TWO"}}'

  • Usa variables de entorno y crea un flujo de trabajo que se configure de forma dinámica según el entorno en el que se implemente. O bien, crea un flujo de trabajo que se pueda reutilizar como plantilla y configurar según las variables de entorno que se mantienen por separado.

  • Usa una técnica de sustitución que te permita crear un solo archivo de definición de flujo de trabajo, pero implementa variantes con una herramienta que reemplaza los marcadores de posición en tu flujo de trabajo. Por ejemplo, puedes usar Cloud Build para implementar un flujo de trabajo y, en el archivo de configuración de Cloud Build, agregar un paso para reemplazar las URLs de marcador de posición en el flujo de trabajo.

    Ejemplo

    steps:
‐ id: 'replace-urls'
  name: 'gcr.io/cloud-builders/gcloud'
  entrypoint: bash
  args:
    - -c
    - |
      sed -i -e "s~REPLACE_url1~$_URL1~" workflow.yaml
      sed -i -e "s~REPLACE_url2~$_URL2~" workflow.yaml
‐ id: 'deploy-workflow'
  name: 'gcr.io/cloud-builders/gcloud'
  args: ['workflows', 'deploy', 'multi-env-$_ENV', '--source', 'workflow.yaml']

    Luego, puedes sustituir los valores de las variables en el tiempo de compilación. Por ejemplo:

    gcloud builds submit --config cloudbuild.yaml \
    --substitutions=_ENV=staging,_URL1="URL_ONE",_URL2="URL_TWO"

    Para obtener más información, consulta Envía una compilación a través de la CLI y la API.

    También puedes usar Terraform para aprovisionar tu infraestructura y definir un archivo de configuración que cree flujos de trabajo para cada entorno con variables de entrada.

    Ejemplo

    variable "project_id" {
  type = string
}

variable "url1" {
  type = string
}

variable "url2" {
  type = string
}

locals {
  env = ["staging", "prod"]
}

# Define and deploy staging and production workflows
resource "google_workflows_workflow" "multi-env-workflows" {
  for_each = toset(local.env)

  name            = "multi-env-${each.key}"
  project         = var.project_id
  region          = "us-central1"
  source_contents = templatefile("${path.module}/workflow.yaml", { url1 : "${var.url1}-${each.key}", url2 : "${var.url2}-${each.key}" })
}

    Cuando las variables se declaran en el módulo raíz de tu configuración, se les pueden asignar valores de varias maneras. Por ejemplo:

    terraform apply -var="project_id=PROJECT_ID" -var="url1=URL_ONE" -var="url2=URL_TWO"

  • Usa el conector de Secret Manager para almacenar de forma segura las URLs en Secret Manager y recuperarlas.

Usa pasos anidados

Cada flujo de trabajo debe tener al menos un paso. De forma predeterminada, Workflows trata los pasos como si estuvieran en una lista ordenada y los ejecuta de a uno hasta que se hayan ejecutado todos. Lógicamente, algunos pasos deben agruparse y puedes usar un bloque steps para anidar una serie de pasos. Esto es conveniente, ya que te permite señalar el paso atómico correcto para procesar un conjunto de pasos.

Ejemplo

main:
    params: [input]
    steps:
    - callWikipedia:
        steps:
        - checkSearchTermInInput:
            switch:
                - condition: ${"searchTerm" in input}
                  assign:
                    - searchTerm: ${input.searchTerm}
                  next: readWikipedia
        - getCurrentDate:
            call: http.get
            args:
                url: https://timeapi.io/api/Time/current/zone?timeZone=Europe/Amsterdam
            result: currentDate
        - setFromCallResult:
            assign:
                - searchTerm: ${currentDate.body.dayOfWeek}
        - readWikipedia:
            call: http.get
            args:
                url: https://en.wikipedia.org/w/api.php
                query:
                    action: opensearch
                    search: ${searchTerm}
            result: wikiResult
    - returnOutput:
            return: ${wikiResult.body[1]}

Une expresiones

Todas las expresiones deben comenzar con un $ y estar encerradas entre llaves:

${EXPRESSION}

Para evitar problemas de análisis de YAML, puedes unir expresiones entre comillas. Por ejemplo, las expresiones que contienen dos puntos pueden causar un comportamiento inesperado cuando los dos puntos se interpretan como la definición de un mapa. Para resolver este problema, une la expresión YAML entre comillas simples:

'${"Name: " + myVar}'

También puedes usar expresiones que abarcan varias líneas. Por ejemplo, es posible que debas unir una consulta en SQL entre comillas cuando uses el conector de BigQuery de Workflows.

Ejemplo

- runQuery:
    call: googleapis.bigquery.v2.jobs.query
    args:
        projectId: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID")}
        body:
            useLegacySql: false
            useQueryCache: false
            timeoutMs: 30000
            # Find top 100 titles with most views on Wikipedia
            query: ${
                "SELECT TITLE, SUM(views)
                FROM `bigquery-samples.wikipedia_pageviews." + table + "`
                WHERE LENGTH(TITLE) > 10
                GROUP BY TITLE
                ORDER BY SUM(VIEWS) DESC
                LIMIT 100"
                }
    result: queryResult

Para obtener la definición completa del flujo de trabajo, consulta Ejecuta varios trabajos de BigQuery en paralelo.

Usa llamadas declarativas

Usa Workflows para llamar a los servicios desde el flujo de trabajo y controlar los resultados, y para ejecutar tareas simples, como realizar una llamada HTTP. Workflows puede invocar servicios, analizar respuestas y construir entradas para otros servicios conectados. Llamar a un servicio te permite evitar las complicaciones de las invocaciones adicionales, las dependencias adicionales y los servicios que llaman a otros servicios. Considera reemplazar los servicios que no tienen lógica empresarial con llamadas a la API declarativas y usa Workflows para abstraer la complejidad.

Sin embargo, debes crear servicios para realizar cualquier trabajo que sea demasiado complejo para Workflows; por ejemplo, implementar lógica empresarial reutilizable, cálculos complejos o transformaciones que no sean compatibles con las expresiones de Workflows y su biblioteca estándar. Por lo general, un caso complicado es más fácil de implementar en el código, en lugar de usar YAML o JSON y la sintaxis de Workflows.

Almacena solo lo que necesitas

Mantén bajo control el consumo de memoria para no encontrar límites de recursos o un error que lo indique como ResourceLimitError, MemoryLimitExceededError, o ResultSizeLimitExceededError.

Sé selectivo con lo que almacenas en variables, filtra y almacena solo lo que necesitas. Si un servicio muestra una carga útil demasiado grande, usa una función separada para realizar la llamada por ti y muestra solo lo que se requiere.

Puedes liberar memoria si borras variables. Por ejemplo, es posible que desees liberar memoria que se necesita para los pasos posteriores. O bien, es posible que tengas llamadas con resultados que no te interesen y puedes omitir esos resultados por completo.

Puedes borrar una variable si asignas null. En YAML, también puedes asignar un valor vacío o ~ a una variable. Esto identifica la memoria que se puede recuperar de forma segura.

Ejemplo

  - step:
      assign:
        - bigVar:

Usa subflujos de trabajo y flujos de trabajo externos

Puedes usar subflujos de trabajo para definir una parte de la lógica o un conjunto de pasos que deseas llamar varias veces, lo que simplifica la definición del flujo de trabajo. Los subflujos de trabajo son similares a una función o rutina en un lenguaje de programación. Pueden aceptar parámetros y mostrar valores, lo que te permite crear flujos de trabajo más complejos con una gama más amplia de aplicaciones.

Ten en cuenta que los subflujos de trabajo son locales para la definición de tu flujo de trabajo y no se pueden reutilizar en otros flujos de trabajo. Sin embargo, puedes llamar a flujos de trabajo desde otros flujos de trabajo. Los conectores de Workflows pueden ayudarte con esto. Para obtener más información, consulta las descripciones generales de los conectores para la API de Workflow Executions y la API de Workflows.

Usa conectores de Workflows

Workflows proporciona varios conectores que facilitan el acceso a otros Google Cloud productos dentro de un flujo de trabajo. Los conectores simplifican las llamadas a los servicios porque controlan el formato de las solicitudes por ti, proporcionan métodos y argumentos para que no necesites conocer los detalles de una Google Cloud API. Los conectores también tienen un comportamiento integrado para controlar los reintentos y las operaciones de larga duración, de modo que puedes evitar la iteración y la espera a que se completen las llamadas. Los conectores se encargan de esto por ti.

Si necesitas llamar a una Google Cloud API, primero verifica si existe un conector de Workflows para ella. Y si no ves un conector para un Google Cloud producto, puedes solicitarlo.

Obtén información para usar un conector y, para obtener una referencia detallada de los conectores disponibles, consulta la referencia de conectores.

Ejecuta los pasos del flujo de trabajo en paralelo

Si bien Workflows puede ejecutar pasos de forma secuencial, también puedes ejecutar pasos independientes en paralelo. En algunos casos, esto puede acelerar significativamente la ejecución del flujo de trabajo. Para obtener más información, consulta Ejecuta los pasos del flujo de trabajo en paralelo.

Aplica reintentos y el patrón de saga

Diseña flujos de trabajo que sean resistentes y puedan controlar las fallas de servicio transitorias y permanentes. Los errores de Workflows pueden generarse, por ejemplo, por solicitudes HTTP, funciones, conectores o por tu propio código de flujo de trabajo. Agrega el manejo de errores y los reintentos para que una falla en un paso no provoque la falla de todo el flujo de trabajo.

Algunas transacciones comerciales abarcan varios servicios, por lo que necesitas un mecanismo para implementar transacciones que abarquen servicios. El patrón de diseño de saga es una forma de administrar la coherencia de los datos en los microservicios en situaciones de transacciones distribuidas. Una saga es una secuencia de transacciones que publica un evento para cada transacción y que activa la siguiente transacción. Si una transacción falla, la saga ejecuta transacciones de compensación que contrarrestan las fallas anteriores en la secuencia. Prueba el instructivo de reintentos y patrón de saga en Workflows en GitHub.

Usa devoluciones de llamada para esperar

Las devoluciones de llamada permiten que las ejecuciones del flujo de trabajo esperen a que otro servicio realice una solicitud al extremo de devolución de llamada; esa solicitud reanuda la ejecución del flujo de trabajo.

Con las devoluciones de llamada, puedes indicarle a tu flujo de trabajo que se produjo un evento especificado y esperar ese evento sin sondeo. Por ejemplo, puedes crear un flujo de trabajo que te notifique cuando un producto vuelva a estar en stock o cuando se haya enviado un artículo, o que espere para permitir la interacción humana como revisar un pedido o validar una traducción. También puedes esperar eventos con devoluciones de llamada y activadores de Eventarc.

Organiza trabajos de larga duración

Si necesitas ejecutar cargas de trabajo de procesamiento por lotes de larga duración, puedes usar trabajos de Batch o Cloud Run, y puedes usar Workflows para administrar los servicios. Esto te permite combinar ventajas y aprovisionar y organizar de manera eficiente todo el proceso.

Batch es un servicio completamente administrado que te permite programar, poner en cola y ejecutar cargas de trabajo por lotes en instancias de máquinas virtuales (VM) de Compute Engine. Puedes usar el conector de Workflows para Batch para programar y ejecutar un trabajo por lotes. Para obtener más información, prueba el instructivo the tutorial.

Los trabajos de Cloud Run se usan para ejecutar código que realiza un trabajo y se cierra cuando este se completa. Workflows te permite ejecutar trabajos de Cloud Run como parte de un flujo de trabajo para realizar procesamientos de datos más complejos, o bien organizar un sistema de trabajos existentes. Prueba el instructivo que muestra cómo usar Workflows para ejecutar un trabajo de Cloud Run.

Aloja en contenedores tareas de larga duración

Puedes automatizar la ejecución de un contenedor de larga duración con Workflows y Compute Engine. Por ejemplo, puedes alojar en contenedores una tarea de larga duración para que se pueda ejecutar en cualquier lugar y, luego, ejecutar el contenedor en una VM de Compute Engine durante la duración máxima de una ejecución de flujo de trabajo (un año).

Con Workflows, puedes automatizar la creación de la VM, la ejecución del contenedor en la VM y el borrado de la VM. Esto te permite usar un servidor y ejecutar un contenedor, pero abstrae la complejidad de administrar ambos y puede ser útil si tienes limitaciones de tiempo cuando usas un servicio como las funciones de Cloud Run o Cloud Run. Prueba el instructivo de contenedores de larga duración con Workflows y Compute Engine en GitHub.

Ejecuta herramientas de línea de comandos desde Workflows

Cloud Build es un servicio que ejecuta tus compilaciones en Google Cloud como una serie de pasos de compilación, en los que cada uno se ejecuta en un contenedor de Docker. La ejecución de pasos de compilación es similar a la ejecución de comandos en una secuencia de comandos.

La CLI de Google Cloud incluye las herramientas de línea de comandos gcloud, bq y kubectl, pero no hay una forma directa de ejecutar comandos de gcloud CLI desde Workflows. Sin embargo, Cloud Build proporciona imágenes de contenedor que incluyen gcloud CLI. Puedes ejecutar comandos de gcloud CLI en esos contenedores desde un paso de Cloud Build y puedes crear ese paso en Workflows con el conector de Cloud Build.

Ejemplo

Ejecuta gcloud en un flujo de trabajo:

# This example shows how to execute gcloud commands from Workflows
# using Cloud Build and returns the output

main:
  steps:
  - execute_command:
      call: gcloud
      args:
          args: "workflows list"
      result: result
  - return_result:
      return: ${result}

gcloud:
  params: [args]
  steps:
  - create_build:
      call: googleapis.cloudbuild.v1.projects.builds.create
      args:
        projectId: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID")}
        parent: ${"projects/" + sys.get_env("GOOGLE_CLOUD_PROJECT_ID") + "/locations/global"}
        body:
          serviceAccount: ${sys.get_env("GOOGLE_CLOUD_SERVICE_ACCOUNT_NAME")}
          options:
            logging: CLOUD_LOGGING_ONLY
          steps:
          - name: gcr.io/google.com/cloudsdktool/cloud-sdk
            entrypoint: /bin/bash
            args: ${["-c", "gcloud " + args + " > $$BUILDER_OUTPUT/output"]}
      result: result_builds_create
  - return_build_result:
      return: ${text.split(text.decode(base64.decode(result_builds_create.metadata.build.results.buildStepOutputs[0])), "\n")}

Run kubectl in a workflow:

# This example shows how to execute kubectl commands from Workflows
# using Cloud Build and returns the output

main:
  steps:
  - execute_command:
      call: kubectl
      args:
          args: "--help"
      result: result
  - return_result:
      return: ${result}

kubectl:
  params: [args]
  steps:
  - create_build:
      call: googleapis.cloudbuild.v1.projects.builds.create
      args:
        projectId: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID")}
        parent: ${"projects/" + sys.get_env("GOOGLE_CLOUD_PROJECT_ID") + "/locations/global"}
        body:
          serviceAccount: ${sys.get_env("GOOGLE_CLOUD_SERVICE_ACCOUNT_NAME")}
          options:
            logging: CLOUD_LOGGING_ONLY
          steps:
          - name: gcr.io/cloud-builders/kubectl
            entrypoint: /bin/bash
            args: ${["-c", "kubectl " + args + " > $$BUILDER_OUTPUT/output"]}
      result: result_builds_create
  - return_build_result:
      return: ${text.split(text.decode(base64.decode(result_builds_create.metadata.build.results.buildStepOutputs[0])), "\n")}

Usa Terraform para crear tu flujo de trabajo

Terraform es una herramienta de infraestructura como código que te permite crear, cambiar y mejorar de forma predecible tu infraestructura de nube mediante código.

Puedes definir e implementar un flujo de trabajo con el recurso de Terraform google_workflows_workflow. Para obtener más información, consulta Crea un flujo de trabajo con Terraform.

Para ayudarte a administrar y mantener flujos de trabajo grandes, puedes crear tu flujo de trabajo en un archivo YAML separado y, luego, importar ese archivo a Terraform con la templatefile función que lee un archivo en una ruta de acceso determinada y renderiza su contenido como una plantilla.

Ejemplo

  # Define a workflow
  resource "google_workflows_workflow" "workflows_example" {
    name            = "sample-workflow"
    region          = var.region
    description     = "A sample workflow"
    service_account = google_service_account.workflows_service_account.id
    # Import main workflow YAML file
    source_contents = templatefile("${path.module}/workflow.yaml",{})
  }

Del mismo modo, si tienes un flujo de trabajo principal que llama a varios subflujos de trabajo, puedes definir el flujo de trabajo principal y los subflujos de trabajo en archivos separados y usar la función templatefile para importarlos.

Ejemplo

  # Define a workflow
  resource "google_workflows_workflow" "workflows_example" {
    name            = "sample-workflow"
    region          = var.region
    description     = "A sample workflow"
    service_account = google_service_account.workflows_service_account.id
    # Import main workflow and subworkflow YAML files
    source_contents = join("", [
      templatefile(
        "${path.module}/workflow.yaml",{}
      ),

      templatefile(
        "${path.module}/subworkflow.yaml",{}
      )])
  }

Ten en cuenta que, si haces referencia a números de línea cuando depuras un flujo de trabajo, todos los archivos YAML importados a través del archivo de configuración de Terraform se combinan y se implementan como un solo flujo de trabajo.

Implementa un flujo de trabajo desde un repositorio de Git

Cloud Build usa activadores de compilación para habilitar la automatización de CI/CD. Puedes configurar activadores para que detecten eventos entrantes, como cuando se envía una confirmación nueva a un repositorio o cuando se inicia una solicitud de extracción, y, luego, ejecutar automáticamente una compilación cuando lleguen eventos nuevos.

Puedes usar un activador de compilación de Cloud Build para iniciar automáticamente una compilación y, luego, implementar un flujo de trabajo desde un repositorio de Git. Puedes configurar el activador para que implemente tu flujo de trabajo ante cualquier cambio en el repositorio de código fuente o solo cuando el cambio coincida con criterios específicos.

Este enfoque puede ayudarte a administrar el ciclo de vida de implementación. Por ejemplo, puedes implementar cambios en un flujo de trabajo en un entorno de etapa de pruebas, ejecutar pruebas en ese entorno y, luego, lanzar de forma incremental estos cambios al entorno de producción. Para obtener más información, consulta Implementa un flujo de trabajo desde un repositorio de Git con Cloud Build.

Optimiza el uso

El costo de ejecutar un flujo de trabajo es mínimo. Sin embargo, para un uso de gran volumen, aplica los siguientes lineamientos para optimizar el uso y disminuir el costo:

  • En lugar de usar dominios personalizados, asegúrate de que todas las llamadas a Google Cloud los servicios usen *.appspot.com, *.cloud.goog, *.cloudfunctions.net, o *.run.app para que se te facture por los pasos internos y no externos.

  • Aplica una política de reintentos personalizada que equilibre tus necesidades de latencia y confiabilidad con los costos. Los reintentos más frecuentes disminuyen la latencia y aumentan la confiabilidad, pero también pueden aumentar los costos.

  • Cuando uses conectores que esperan operaciones de larga duración, establece una política de sondeo personalizada que optimice la latencia para el costo. Por ejemplo, si esperas que una operación tarde más de una hora, es posible que desees una política que, inicialmente, sondee después de un minuto en caso de una falla inmediata y, luego, cada 15 minutos.

  • Combina asignaciones en un solo paso.

  • Evita el uso excesivo de pasos sys.log. Considera usar el registro de llamadas en su lugar.

  • Comprende qué operaciones se consideran un paso. Las operaciones que no cuentan como pasos por sí solas se cuentan cuando se usan dentro de un paso aplicable. Por ejemplo, lo siguiente cuenta como un paso:

    - type_check:
    return: if(get_type((int("6"))) == integer, 1, 2)

    Las operaciones clave que cuentan y no cuentan para el límite máximo de pasos se clasifican en la siguiente tabla:

    Categoría Operación
    Cuenta como un paso
    • Operaciones de datos: Asignación, devolución de valores
    • Control de flujo: Saltos (next), conmutadores, inicio de un for bucle, y cada iteración de un for bucle
    • Llamadas: Invocar sys.get_env o alguna otra función de biblioteca estándar función, otro flujo de trabajo o un conector
    • Simultaneidad: Generación de subprocesos y ejecución paralela
    • Manejo de errores: Cada bloque raise, try, retry y except cuenta como un paso separado, incluso si otras operaciones forman parte del mismo paso más grande.

      Por ejemplo, un paso que incluye un try bloque con una operación de llamada cuenta como tres pasos: uno para el paso principal, uno para el intento y uno para la llamada. Agregar un bloque retry agrega tres pasos más (uno para el reintento, el intento y la llamada), lo que hace un total de seis pasos.
    No cuenta como un paso

Resumen de prácticas recomendadas

En la siguiente tabla, se resumen las sugerencias generales y las prácticas recomendadas de este documento.

Sugerencias generales
Prácticas recomendadas

¿Qué sigue?