Ejecuta plantillas flexibles en Dataflow

En esta página, se describe cómo ejecutar un trabajo de Dataflow con una plantilla de Flex. Las plantillas de Flex te permiten empaquetar una canalización de Dataflow para que puedas ejecutarla sin tener un entorno de desarrollo de Apache Beam.

Permisos necesarios

Cuando ejecutas una plantilla flexible, Dataflow crea un trabajo por ti. Para crear el trabajo, la cuenta de servicio de Dataflow necesita el siguiente permiso:

  • dataflow.serviceAgent

Cuando usas Dataflow por primera vez, el servicio te asigna este rol, por lo que no necesitas otorgar este permiso.

De forma predeterminada, la cuenta de servicio de Compute Engine se usa para las VMs de iniciador y de trabajador. La cuenta de servicio necesita las siguientes funciones y capacidades:

  • Administrador de objetos de almacenamiento (roles/storage.objectAdmin)
  • Visualizador (roles/viewer)
  • Trabajador de Dataflow (roles/dataflow.worker)
  • Acceso de lectura y escritura al bucket de etapa de pruebas
  • Acceso de lectura a la imagen de la plantilla flexible

Para otorgar acceso de lectura y escritura al bucket de etapa de pruebas, puedes usar el rol Administrador de objetos de almacenamiento (roles/storage.objectAdmin). Si deseas obtener más información, consulta Roles de IAM para Cloud Storage.

Para otorgar acceso de lectura a la imagen de la plantilla de Flex, puedes usar el rol Visualizador de objetos de almacenamiento (roles/storage.objectViewer). Para obtener más información, consulta Configurar el control de acceso.

Ejecuta una plantilla de Flex

Para ejecutar una plantilla de Flex, usa el comando gcloud dataflow flex-template run:

gcloud dataflow flex-template run JOB_ID \
  --template-file-gcs-location gs://TEMPLATE_FILE_LOCATION \
  --region REGION \
  --staging-location STAGING_LOCATION \
  --temp-location TEMP_LOCATION \
  --parameters  PARAMETERS \
  --additional-user-labels LABELS \

Reemplaza lo siguiente:

  • JOB_ID: Es el ID de tu trabajo.

  • TEMPLATE_FILE_LOCATION: Es la ubicación de Cloud Storage del archivo de plantilla.

  • REGION: Es la región en la que se ejecutará el trabajo de Dataflow.

  • STAGING_LOCATION: Es la ubicación de Cloud Storage para transferir archivos locales de forma intermedia.

  • TEMP_LOCATION: Es la ubicación de Cloud Storage en la que se escribirán los archivos temporales. Si no se establece, se usa la ubicación de etapa de pruebas de forma predeterminada.

  • PARAMETERS: Parámetros de canalización para el trabajo

  • LABELS: Opcional Son las etiquetas adjuntas a tu trabajo, con el formato KEY_1=VALUE_1,KEY_2=VALUE_2,....

Durante el paso de etapa de pruebas del lanzamiento de una plantilla, Dataflow escribe archivos en la ubicación de etapa de pruebas. Dataflow lee estos archivos en etapa de pruebas para crear el grafo del trabajo. Durante el paso de ejecución, Dataflow escribe archivos en la ubicación temporal.

Configura las opciones de canalización

Para establecer opciones de canalización cuando ejecutas una plantilla de Flex, usa las siguientes marcas en el comando gcloud dataflow flex-template run:

gcloud

Cuando pasas parámetros de tipo List o Map, es posible que debas definir parámetros en un archivo YAML y usar la marca flags-file.

API

En el siguiente ejemplo, se muestra cómo incluir opciones de canalización, experimentos y opciones adicionales en el cuerpo de una solicitud:

{
  "jobName": "my-flex-template-job",
  "parameters": {
    "option_defined_in_metadata": "value"
  },
  "environment": {
    "additionalExperiments": [
      "use_runner_v2"
    ],
    "additionalPipelineOptions": {
      "common_pipeline_option": "value"
    }
  }
}

Cuando usas plantillas de Flex, puedes configurar algunas opciones durante la inicialización de la canalización, pero otras opciones de canalización no se pueden cambiar. Si se reemplazan los argumentos de la línea de comandos requeridos por la plantilla flexible, el trabajo puede ignorar, anular o descartar las opciones de canalización que pasa el selector de plantillas. Es posible que el trabajo no se inicie o que se inicie un trabajo que no use la plantilla flexible. Para obtener más información, consulta No se pudo leer el archivo de trabajo.

Durante la inicialización de la canalización, no cambies las siguientes opciones de canalización:

Java

  • runner
  • project
  • jobName
  • templateLocation
  • region

Python

  • runner
  • project
  • job_name
  • template_location
  • region

Go

  • runner
  • project
  • job_name
  • template_location
  • region

Bloquea claves SSH del proyecto de las VM que usan claves SSH basadas en metadatos

Para evitar que las VM acepten claves SSH almacenadas en metadatos del proyecto, bloquea las claves SSH del proyecto desde las VM. Usa la marca additional-experiments con la opción de servicio block_project_ssh_keys:

--additional-experiments=block_project_ssh_keys

Para obtener más información, consulta Opciones de servicio de Dataflow.

Actualiza un trabajo de plantilla de Flex

En la siguiente solicitud de ejemplo, se muestra cómo actualizar un trabajo de transmisión de una plantilla con el método projects.locations.flexTemplates.launch. Si deseas usar gcloud CLI, consulta Actualiza una canalización existente.

Si quieres actualizar una plantilla clásica, usa projects.locations.templates.launch en su lugar.

  1. Sigue los pasos para crear un trabajo de transmisión a partir de una plantilla de Flex. Envía la siguiente solicitud HTTP POST, con los valores modificados:

    POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/flexTemplates:launch
{
    "launchParameter": {
      "update": true
      "jobName": "JOB_NAME",
      "parameters": {
        "input_subscription": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_NAME",
        "output_table": "PROJECT_ID:DATASET.TABLE_NAME"
      },
    "containerSpecGcsPath": "STORAGE_PATH"
    },
}
    • Reemplaza PROJECT_ID con el ID del proyecto.
    • Reemplaza REGION por la región de Dataflow del trabajo que estás actualizando.
    • Reemplaza JOB_NAME por el nombre exacto del trabajo que deseas actualizar.
    • Establece parameters en la lista de pares clave-valor. Los parámetros enumerados son específicos de este ejemplo de plantilla. Si usas una plantilla personalizada, modifica los parámetros según sea necesario. Si usas la plantilla de ejemplo, reemplaza las siguientes variables.
      • Reemplaza SUBSCRIPTION_NAME por el nombre de tu suscripción de Pub/Sub.
      • Reemplaza DATASET por el nombre de tu conjunto de datos de BigQuery.
      • Reemplaza TABLE_NAME por el nombre de tu tabla de BigQuery.
    • Reemplaza STORAGE_PATH por la ubicación de Cloud Storage del archivo de plantilla. La ubicación debe comenzar con gs://.

  2. Usa el parámetro environment para cambiar la configuración del entorno. Para obtener más información, consulta FlexTemplateRuntimeEnvironment.

  3. Opcional: para enviar tu solicitud con curl (Linux, macOS o Cloud Shell), guarda la solicitud en un archivo JSON y, luego, ejecuta el siguiente comando:

    curl -X POST -d "@FILE_PATH" -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)"  https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/flexTemplates:launch

    Reemplaza FILE_PATH por la ruta de acceso al archivo JSON que contiene el cuerpo de la solicitud.

  4. Usa la interfaz de supervisión de Dataflow para verificar que se haya creado un trabajo nuevo con el mismo nombre. Este trabajo tiene el estado Actualizado.

¿Qué sigue?