Plantillas de Dataflow

Las plantillas de Dataflow te permiten empaquetar una canalización de Dataflow para su implementación. Cualquier persona con los permisos correctos puede usar la plantilla para implementar la canalización empaquetada. Puedes crear tus propias plantillas de Dataflow personalizadas y Google proporciona plantillas compiladas con anterioridad para situaciones comunes.

Beneficios

Las plantillas tienen varias ventajas sobre la implementación directa de una canalización en Dataflow:

  • Las plantillas separan el diseño de canalización de la implementación. Por ejemplo, un desarrollador puede crear una plantilla y un científico de datos puede implementarla más adelante.
  • Las plantillas pueden tener parámetros que te permitan personalizar la canalización cuando implementas la plantilla.
  • Puedes implementar una plantilla con la consola de Google Cloud , Google Cloud CLI o las llamadas a la API de REST. No necesitas un entorno de desarrollo ni dependencias de canalización instaladas en tu máquina local.
  • Una plantilla es un artefacto de código que se puede almacenar en un repositorio de control de código fuente y se puede usar en canalizaciones de integración continua (CI/CD).

Plantillas proporcionadas por Google

Google proporciona una variedad de plantillas de Dataflow compiladas de código abierto previamente que puedes usar para situaciones comunes. Para obtener más información sobre las plantillas disponibles, consulta las plantillas que proporciona Google.

Comparación entre las plantillas de Flex y las clásicas

Dataflow admite dos tipos de plantillas: plantillas de Flex, que son más recientes, y plantillas clásicas. Si creas una plantilla de Dataflow nueva, te recomendamos que la crees como plantilla de Flex.

Con una plantilla de Flex, la canalización se empaqueta como una imagen de Docker en Artifact Registry, junto con un archivo de especificación de plantilla en Cloud Storage. La especificación de la plantilla contiene un puntero a la imagen de Docker. Cuando ejecutas la plantilla, el servicio de Dataflow inicia una VM de selector, extrae la imagen de Docker y ejecuta la canalización. El grafo de ejecución se compila de forma dinámica según los parámetros del entorno de ejecución que proporciona el usuario. Si deseas usar la API para iniciar un trabajo que use una plantilla de Flex, usa el método projects.locations.flexTemplates.launch.

Una plantilla clásica contiene la serialización de JSON de un grafo de trabajo de Dataflow. El código de la canalización debe unir cualquier parámetro de entorno de ejecución en la interfaz ValueProvider. Esta interfaz permite a los usuarios especificar los valores de los parámetros cuando implementan la plantilla. Si quieres usar la API para trabajar con plantillas clásicas, consulta la documentación de referencia de la API de projects.locations.templates.

Las plantillas de Flex tienen las siguientes ventajas sobre las plantillas clásicas:

  • A diferencia de las plantillas clásicas, las plantillas de Flex no requieren la interfaz ValueProvider para los parámetros de entrada. No todas las fuentes y receptores de Dataflow admiten ValueProvider.
  • Si bien las plantillas clásicas tienen un grafo de trabajo estático, las plantillas de Flex pueden construir el grafo de trabajo de forma dinámica. Por ejemplo, la plantilla puede seleccionar un conector de E/S diferente según los parámetros de entrada.
  • Una plantilla de Flex puede realizar un procesamiento previo en una máquina virtual (VM) durante la construcción de la canalización. Por ejemplo, puede validar valores de parámetros de entrada.

Flujo de trabajo de la plantilla

El uso de plantillas de Dataflow implica los siguientes pasos de alto nivel:

  1. Los desarrolladores configuran un entorno de desarrollo y desarrollan su canalización. El entorno incluye el SDK de Apache Beam y otras dependencias.
  2. Según el tipo de plantilla (Flex o clásica):
    • Para las plantillas de Flex, los desarrolladores empaquetan la canalización en una imagen de Docker, la envían a Artifact Registry y suben un archivo de especificación de plantilla a Cloud Storage.
    • En el caso de las plantillas clásicas, los desarrolladores ejecutan la canalización, crean un archivo de plantilla y almacenan la plantilla en etapa intermedia en Cloud Storage.
  3. Otros usuarios envían una solicitud al servicio de Dataflow para ejecutar la plantilla.
  4. Dataflow crea una canalización a partir de la plantilla. La canalización puede tardar entre cinco y siete minutos en comenzar a ejecutarse.

Inspecciona y audita los trabajos de plantilla

Cuando auditas trabajos de plantillas de Dataflow en ejecución o históricos de manera programática con la API de REST o Google Cloud CLI, la vista predeterminada es una vista de resumen (JOB_VIEW_SUMMARY). En la vista de resumen, se omiten los detalles de ejecución de la canalización, los metadatos de la plantilla y las opciones de canalización del SDK. Para recuperar los detalles de la plantilla y las opciones del entorno, debes solicitar de forma explícita la vista completa del trabajo.

Para inspeccionar los detalles de la plantilla de un trabajo, usa uno de los siguientes métodos:

gcloud CLI

Para recuperar la descripción completa del trabajo, incluidos los detalles de la plantilla, ejecuta el comando gcloud dataflow jobs describe con la marca --full:

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • REGION: Es la región de Dataflow en la que se ejecuta el trabajo.
  • JOB_ID: Es el ID del trabajo de Dataflow.

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Windows (PowerShell)

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Windows (cmd.exe)

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Deberías recibir una respuesta similar a la que figura a continuación:

environment:
  sdkPipelineOptions:
    options:
      templateLocation: gs://BUCKET_NAME/templates/TEMPLATE_NAME
id: JOB_ID
name: JOB_NAME
type: JOB_TYPE_BATCH

REST

Para recuperar el recurso de trabajo completo, incluidos los detalles de la plantilla, envía una solicitud HTTP GET al método projects.locations.jobs.get con el parámetro de consulta view=JOB_VIEW_ALL:

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • REGION: Es la región de Dataflow en la que se ejecuta el trabajo.
  • JOB_ID: Es el ID del trabajo de Dataflow.

Método HTTP y URL: 

GET https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL"

PowerShell

Ejecuta el siguiente comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "id": "JOB_ID",
  "name": "JOB_NAME",
  "type": "JOB_TYPE_BATCH",
  "environment": {
    "sdkPipelineOptions": {
      "options": {
        "templateLocation": "gs://BUCKET_NAME/templates/TEMPLATE_NAME"
      }
    }
  }
}

Identificar los tipos de plantillas

La carga útil de la respuesta varía según si el trabajo se creó a partir de una plantilla proporcionada por Google o una plantilla personalizada:

  • Plantillas proporcionadas por Google: Dataflow asigna automáticamente etiquetas predefinidas al recurso del trabajo:
    • goog-dataflow-provided-template-name: el nombre de la plantilla.
    • goog-dataflow-provided-template-type: Es el tipo de plantilla, ya sea flex o legacy (clásica).
    • goog-dataflow-provided-template-version: Es la versión de actualización de la plantilla.
  • Plantillas personalizadas: Los trabajos de plantillas personalizadas no tienen las etiquetas goog-dataflow-provided-*. Los trabajos de plantillas de Flex y clásicas propagan la opción templateLocation en environment.sdkPipelineOptions. Para determinar el tipo de plantilla de los trabajos personalizados cuando no hay etiquetas, inspecciona los siguientes campos en la respuesta completa del trabajo (JOB_VIEW_ALL):
    • Plantillas clásicas: El campo templateLocation apunta directamente al archivo JSON de la plantilla en etapa de pruebas en Cloud Storage. Por ejemplo, la ruta se parece a gs://BUCKET_NAME/templates/TEMPLATE_NAME. Los trabajos de plantillas clásicas no tienen configuraciones de imágenes de iniciador de contenedores.
    • Plantillas de Flex: Los trabajos de plantilla de Flex se ejecutan desde una imagen de contenedor de selector. En el objeto environment, los trabajos de plantilla de Flex contienen especificaciones y parámetros del contenedor de iniciador (como flexResourceLimits). Además, la ruta de acceso de Cloud Storage templateLocation en etapa de pruebas generada durante el inicio contiene el ID del trabajo.

Práctica recomendada: Adjunta etiquetas de usuario durante el lanzamiento

Debido a que distinguir los tipos de plantillas personalizadas de manera programática requiere recuperar y analizar las opciones completas del entorno de JOB_VIEW_ALL, te recomendamos que adjuntes etiquetas de usuario descriptivas cuando inicies tus trabajos de plantilla. Por ejemplo, adjunta etiquetas como template-type: flex o template-type: classic.

Las etiquetas de usuario se devuelven en la vista de resumen predeterminada (JOB_VIEW_SUMMARY) y en las operaciones de lista de trabajos. Las etiquetas de usuario te permiten filtrar, buscar y auditar trabajos de plantilla de manera eficiente en todo tu proyecto sin recuperar la carga útil de ejecución completa para cada trabajo.

Para adjuntar etiquetas cuando inicias una plantilla, usa los siguientes métodos:

  • Para las plantillas de Flex en gcloud CLI, usa la marca --additional-user-labels en el comando gcloud dataflow flex-template run.
  • Para las plantillas clásicas en gcloud CLI, usa la marca --labels en el comando gcloud dataflow jobs run.
  • Cuando uses la API de REST, incluye el mapa de pares clave-valor labels en el cuerpo de la solicitud de inicio.

Configura los permisos de IAM

Los trabajos de Dataflow, incluidos los trabajos que se ejecutan desde plantillas, usan dos cuentas de servicio de IAM:

  • El servicio de Dataflow usa una cuenta de servicio de Dataflow para manipular los recursos de Google Cloud , como la creación de VMs.
  • Las VM de trabajador de Dataflow usan una cuenta de servicio de trabajador para acceder a los archivos y a otros recursos de la canalización. Esta cuenta de servicio necesita acceder a cualquier recurso al que haga referencia el trabajo de canalización, incluidos el receptor y la fuente que usa la plantilla. Para obtener más información, consulta Cómo acceder a los recursos de Google Cloud .

Asegúrate de que estas dos cuentas de servicio tengan los roles adecuados. Para obtener más información, consulta Seguridad y permisos de Dataflow.

Si tu organización usa políticas de límite de acceso de la entidad (PAB), es posible que se bloquee a las entidades (como usuarios o cuentas de servicio) para que no vean ni ejecuten plantillas proporcionadas por Google. Para obtener más información y soluciones, consulta Accede a las plantillas proporcionadas por Google con las políticas de límite de acceso de las principales.

Requisitos de la versión del SDK de Apache Beam

Para crear tus propias plantillas, asegúrate de que la versión del SDK de Apache Beam admita la creación de plantillas.

Java

Si quieres crear plantillas con el SDK 2.x de Apache Beam para Java, debes tener la versión 2.0.0-beta3 o superior.

Python

Si quieres crear plantillas con el SDK 2.x de Apache Beam para Python, debes tener la versión 2.0.0 o superior.

Para ejecutar plantillas con Google Cloud CLI, debes tener la versión 138.0.0 o posterior de Google Cloud CLI.

Extender plantillas

Puedes compilar tus propias canalizaciones si extiendes las plantillas de Dataflow de código abierto. Por ejemplo, en el caso de una plantilla que usa una duración de ventana fija, los datos que llegan fuera de la ventana podrían descartarse. A fin de evitar este comportamiento, usa el código de la plantilla como base y modifícalo para invocar la operación .withAllowedLateness.

¿Qué sigue?