Crear y ejecutar una plantilla Flex

---

Las plantillas flexibles de Dataflow te permiten empaquetar un flujo de procesamiento de Dataflow para desplegarlo. En este tutorial se muestra cómo crear una plantilla flexible de Dataflow y, a continuación, ejecutar un trabajo de Dataflow con esa plantilla.

Objetivos

• Crea una plantilla flexible de Dataflow.
• Usa la plantilla para ejecutar un trabajo de Dataflow.

Costes

En este documento, se usan los siguientes componentes facturables de Google Cloud Platform:

• Dataflow
• Cloud Storage
• Artifact Registry
• Cloud Build

Para generar una estimación de costes basada en el uso previsto, utiliza la calculadora de precios.

Los usuarios nuevos Google Cloud pueden disfrutar de una prueba gratuita.

Cuando termines las tareas que se describen en este documento, puedes evitar que se te siga facturando eliminando los recursos que has creado. Para obtener más información, consulta la sección Limpiar.

Antes de empezar

Sign in to your Google Cloud Platform account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
Install the Google Cloud CLI.
Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.
Para inicializar gcloud CLI, ejecuta el siguiente comando:
gcloud init
Create or select a Google Cloud project.
Roles required to select or create a project
• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.
• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.
Verify that billing is enabled for your Google Cloud project.
Enable the Dataflow, Compute Engine, Logging, Cloud Storage, Cloud Storage JSON, Resource Manager, Artifact Registry, and Cloud Build API:
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
gcloud services enable dataflow compute_component logging storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/iam.serviceAccountUser
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Replace the following:
• PROJECT_ID: your project ID.
• USER_IDENTIFIER: the identifier for your user account—for example, [e-mail].
• ROLE: the IAM role that you grant to your user account.

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Dataflow, Compute Engine, Logging, Cloud Storage, Cloud Storage JSON, Resource Manager, Artifact Registry, and Cloud Build API:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable dataflow compute_component logging storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com

If you're using a local shell, then create local authentication credentials for your user account:

gcloud auth application-default login

You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/iam.serviceAccountUser

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

Replace the following:

• PROJECT_ID: your project ID.
• USER_IDENTIFIER: the identifier for your user account—for example, [e-mail].
• ROLE: the IAM role that you grant to your user account.

1. Concede roles a tu cuenta de servicio predeterminada de Compute Engine. Ejecuta el siguiente comando una vez por cada uno de los siguientes roles de gestión de identidades y accesos:

   • roles/dataflow.admin
   • roles/dataflow.worker
   • roles/storage.objectAdmin
   • roles/artifactregistry.writer

   gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:[e-mail]" --role=SERVICE_ACCOUNT_ROLE

   Haz los cambios siguientes:

   • PROJECT_ID: tu ID de proyecto
   • PROJECT_NUMBER tu número de proyecto
   • SERVICE_ACCOUNT_ROLE: cada rol individual

Preparar el entorno

Instala el SDK y los requisitos de tu entorno de desarrollo.

Java

1. Descarga e instala la versión 17 del Java Development Kit (JDK). Verifica que la variable de entorno JAVA_HOME esté definida y apunte a tu instalación de JDK.

2. Descarga e instala Apache Maven siguiendo la guía de instalación de Maven para tu sistema operativo.

Python

Instala el SDK de Apache Beam para Python.

Go

Consulta la guía de descarga e instalación de Go para descargar e instalar Go en tu sistema operativo. Para saber qué entornos de ejecución de Go son compatibles con Apache Beam, consulta Compatibilidad con el entorno de ejecución de Apache Beam.

Descarga el código de ejemplo.

Java

1. Clona el repositorio java-docs-samples.

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

2. Ve al código de ejemplo de este tutorial.

   cd java-docs-samples/dataflow/flex-templates/getting_started

3. Compila el proyecto de Java en un archivo JAR Uber.

   mvn clean package

   Este archivo Uber JAR tiene todas las dependencias insertadas. Puedes ejecutar este archivo como una aplicación independiente sin dependencias externas de otras bibliotecas.

Python

1. Clona el repositorio python-docs-samples.

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

2. Ve al código de ejemplo de este tutorial.

   cd python-docs-samples/dataflow/flex-templates/getting_started

Go

1. Clona el repositorio golang-samples.

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

2. Ve al código de ejemplo de este tutorial.

   cd golang-samples/dataflow/flex-templates/wordcount

3. Compila el archivo binario de Go.

   CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o wordcount .

Crea un segmento de Cloud Storage

Usa el comando gcloud storage buckets create para crear un segmento de Cloud Storage:

gcloud storage buckets create gs://BUCKET_NAME

Sustituye BUCKET_NAME por el nombre que quieras darle al segmento de Cloud Storage. Los nombres de los segmentos de Cloud Storage deben ser únicos en todo el mundo y cumplir los requisitos de nomenclatura de segmentos.

Crear un repositorio de Artifact Registry

Crea un repositorio de Artifact Registry en el que insertarás la imagen del contenedor Docker de la plantilla.

1. Usa el comando gcloud artifacts repositories create para crear un repositorio de Artifact Registry.

   gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=LOCATION

   Haz los cambios siguientes:

   • REPOSITORY: un nombre para tu repositorio. Los nombres de los repositorios deben ser únicos en cada ubicación de repositorio de un proyecto.
   • LOCATION: la ubicación regional o multirregional del repositorio.

2. Usa el comando gcloud auth configure-docker para configurar Docker de forma que autentique las solicitudes de Artifact Registry. Este comando actualiza tu configuración de Docker para que puedas conectarte con Artifact Registry y enviar imágenes.

   gcloud auth configure-docker LOCATION-docker.pkg.dev

Las plantillas Flex también pueden usar imágenes almacenadas en registros privados. Para obtener más información, consulta Usar una imagen de un registro privado.

Crear la plantilla Flex

En este paso, usará el comando gcloud dataflow flex-template build para crear la plantilla Flex.

Una plantilla Flex consta de los siguientes componentes:

• Una imagen de contenedor Docker que empaqueta el código de tu canal. En el caso de las plantillas flexibles de Java y Python, la imagen Docker se crea y se envía a tu repositorio de Artifact Registry cuando ejecutas el comando gcloud dataflow flex-template build.
• Un archivo de especificación de plantilla. Este archivo es un documento JSON que contiene la ubicación de la imagen del contenedor, así como metadatos sobre la plantilla, como los parámetros de la canalización.

El repositorio de ejemplo de GitHub contiene el archivo metadata.json.

• repositorio java-docs-samples
• repositorio python-docs-samples
• repositorio golang-samples

Para ampliar tu plantilla con metadatos adicionales, puedes crear tu propio archivo metadata.json.

Java

gcloud dataflow flex-template build gs://BUCKET_NAME/getting_started-java.json \
 --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/getting-started-java:latest" \
 --sdk-language "JAVA" \
 --flex-template-base-image JAVA17 \
 --metadata-file "metadata.json" \
 --jar "target/flex-template-getting-started-1.0.jar" \
 --env FLEX_TEMPLATE_JAVA_MAIN_CLASS="com.example.dataflow.FlexTemplateGettingStarted"

Haz los cambios siguientes:

• BUCKET_NAME: el nombre del segmento de Cloud Storage que has creado antes
• LOCATION: la ubicación
• PROJECT_ID: el ID del proyecto Google Cloud
• REPOSITORY: el nombre del repositorio de Artifact Registry que has creado antes

Python

gcloud dataflow flex-template build gs://BUCKET_NAME/getting_started-py.json \
 --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/getting-started-python:latest" \
 --sdk-language "PYTHON" \
 --flex-template-base-image "PYTHON3" \
 --metadata-file "metadata.json" \
 --py-path "." \
 --env "FLEX_TEMPLATE_PYTHON_PY_FILE=getting_started.py" \
 --env "FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE=requirements.txt"

Haz los cambios siguientes:

• BUCKET_NAME: el nombre del segmento de Cloud Storage que has creado antes
• LOCATION: la ubicación
• PROJECT_ID: el ID del proyecto Google Cloud
• REPOSITORY: el nombre del repositorio de Artifact Registry que has creado antes

Go

1. Usa el comando gcloud builds submit para compilar la imagen Docker con un Dockerfile mediante Cloud Build. Este comando compila el archivo y lo envía a tu repositorio de Artifact Registry.

   gcloud builds submit --tag LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/wordcount-go:latest .

   Haz los cambios siguientes:

   • LOCATION: la ubicación
   • PROJECT_ID: el ID del proyecto Google Cloud
   • REPOSITORY: el nombre del repositorio de Artifact Registry que has creado antes

2. Usa el comando gcloud dataflow flex-template build para crear una plantilla flexible llamada wordcount-go.json en tu segmento de Cloud Storage.

   gcloud dataflow flex-template build gs://BUCKET_NAME/samples/dataflow/templates/wordcount-go.json \
     --image "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/wordcount-go:latest" \
     --sdk-language "GO" \
     --metadata-file "metadata.json"

   Sustituye BUCKET_NAME por el nombre del segmento de Cloud Storage que has creado anteriormente.

Ejecutar la plantilla Flex

En este paso, usará la plantilla para ejecutar una tarea de Dataflow.

Java

1. Usa el comando gcloud dataflow flex-template run para ejecutar una tarea de Dataflow que utilice la plantilla Flex.

   gcloud dataflow flex-template run "getting-started-`date +%Y%m%d-%H%M%S`" \
    --template-file-gcs-location "gs://BUCKET_NAME/getting_started-java.json" \
    --parameters output="gs://BUCKET_NAME/output-" \
    --additional-user-labels "LABELS" \
    --region "REGION"

   Haz los cambios siguientes:

   • BUCKET_NAME: el nombre del segmento de Cloud Storage que has creado anteriormente
   • REGION: la región
   • LABELS: opcional. Etiquetas asociadas a tu trabajo con el formato <key1>=<val1>,<key2>=<val2>,...

2. Para ver el estado de la tarea de Dataflow en la consola deGoogle Cloud , ve a la página Tareas de Dataflow.

   Ir a Tareas

Si la tarea se ejecuta correctamente, escribe la salida en un archivo llamado gs://BUCKET_NAME/output--00000-of-00001.txt en tu segmento de Cloud Storage.

Python

1. Usa el comando gcloud dataflow flex-template run para ejecutar una tarea de Dataflow que utilice la plantilla Flex.

   gcloud dataflow flex-template run "getting-started-`date +%Y%m%d-%H%M%S`" \
    --template-file-gcs-location "gs://BUCKET_NAME/getting_started-py.json" \
    --parameters output="gs://BUCKET_NAME/output-" \
    --additional-user-labels "LABELS" \
    --region "REGION"

   Haz los cambios siguientes:

   • BUCKET_NAME: el nombre del segmento de Cloud Storage que has creado antes
   • REGION: la región
   • LABELS: opcional. Etiquetas asociadas a tu trabajo con el formato <key1>=<val1>,<key2>=<val2>,...

2. Para ver el estado de la tarea de Dataflow en la consola deGoogle Cloud , ve a la página Tareas de Dataflow.

   Ir a Tareas

Si la tarea se ejecuta correctamente, escribe la salida en un archivo llamado gs://BUCKET_NAME/output--00000-of-00001.txt en tu segmento de Cloud Storage.

Go

1. Usa el comando gcloud dataflow flex-template run para ejecutar una tarea de Dataflow que utilice la plantilla Flex.

   gcloud dataflow flex-template run "wordcount-go-`date +%Y%m%d-%H%M%S`" \
    --template-file-gcs-location "gs://BUCKET_NAME/samples/dataflow/templates/wordcount-go.json" \
    --parameters output="gs://BUCKET_NAME/samples/dataflow/templates/counts.txt" \
    --additional-user-labels "LABELS" \
    --region "REGION"

   Haz los cambios siguientes:

   • BUCKET_NAME: el nombre del segmento de Cloud Storage que has creado anteriormente
   • REGION: la región
   • LABELS: opcional. Etiquetas asociadas a tu trabajo con el formato <key1>=<val1>,<key2>=<val2>,...

2. Para ver el estado de la tarea de Dataflow en la consola deGoogle Cloud , ve a la página Tareas de Dataflow.

   Ir a Tareas

Si el trabajo se ejecuta correctamente, escribe la salida en un archivo llamado gs://BUCKET_NAME/samples/dataflow/templates/count.txt en tu segmento de Cloud Storage.

Nota: Si el trabajo no se ejecuta y se muestra el mensaje de error A Timeout in polling error message, consulta el artículo Solucionar problemas de tiempo de espera de plantillas flexibles.

Limpieza

Para evitar que los recursos utilizados en este tutorial se cobren en tu cuenta de Google Cloud, elimina el proyecto que contiene los recursos o conserva el proyecto y elimina los recursos.

Eliminar el proyecto

Precaución: Eliminar un proyecto tiene los siguientes efectos:

• Se elimina todo el contenido del proyecto. Si has usado un proyecto que ya existía para las tareas de este documento, cuando lo elimines, también se eliminará cualquier otro trabajo que hayas realizado en él.
• Se pierden los IDs de proyecto personalizados. Cuando creaste este proyecto, es posible que hayas creado un ID de proyecto personalizado que quieras usar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, elimina los recursos seleccionados dentro del proyecto en lugar de eliminar todo el proyecto.

Si tienes previsto consultar varias arquitecturas, tutoriales o guías de inicio rápido, reutilizar los proyectos puede ayudarte a no superar los límites de cuota de proyectos.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Eliminar recursos concretos

1. Elimina el segmento de Cloud Storage y todos los objetos que contiene.

   gcloud storage rm gs://BUCKET_NAME --recursive

2. Elimina el repositorio de Artifact Registry.

   gcloud artifacts repositories delete REPOSITORY \
       --location=LOCATION

3. Revoca los roles que hayas concedido a la cuenta de servicio predeterminada de Compute Engine. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de gestión de identidades y accesos:
   • roles/dataflow.admin
   • roles/dataflow.worker
   • roles/storage.objectAdmin
   • roles/artifactregistry.writer

   gcloud projects remove-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=SERVICE_ACCOUNT_ROLE

4. Optional: Revoke the authentication credentials that you created, and delete the local credential file.

   gcloud auth application-default revoke

5. Optional: Revoke credentials from the gcloud CLI.

   gcloud auth revoke

Siguientes pasos

• Consulta cómo configurar plantillas Flex.
• Consulta la lista de plantillas proporcionadas por Google.