Compila y ejecuta una plantilla de Flex de ejemplo

En este instructivo, se explican las plantillas de Flex y se muestra cómo puedes compilar y ejecutar una canalización de datos alojada en contenedores en Dataflow. Aprenderás a empaquetar tus canalizaciones para una implementación eficiente con una plantilla flexible de ejemplo.

Objetivos

• Compilar una plantilla de Flex de Dataflow
• Usa la plantilla para ejecutar un trabajo de Dataflow.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

• Dataflow
• Cloud Storage
• Artifact Registry

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.

Es posible que los usuarios de Google Cloud nuevos cumplan con los requisitos para acceder a una prueba gratuita.

Cuando completes las tareas que se describen en este documento, podrás borrar los recursos que creaste para evitar que se te siga facturando. Para obtener más información, consulta Realiza una limpieza.

Antes de comenzar

Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
Instala Google Cloud CLI.
Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.
Para inicializar gcloud CLI, ejecuta el siguiente comando:
gcloud init
Crea o selecciona un Google Cloud proyecto.
Roles necesarios para seleccionar o crear un proyecto
• Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.
Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.
• Crea un proyecto de Google Cloud :

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

• Selecciona el proyecto Google Cloud que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.
Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .
Habilita las APIs de Dataflow, Compute Engine, Logging, Cloud Storage, Cloud Storage JSON, Resource Manager y Artifact Registry:
Roles necesarios para habilitar las APIs
Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.
gcloud services enable dataflow compute_component logging storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com
Si usas un shell local, crea credenciales de autenticación locales para tu cuenta de usuario:
gcloud auth application-default login
No es necesario que lo hagas si usas Cloud Shell.
Si se devuelve un error de autenticación y usas un proveedor de identidad (IdP) externo, confirma que accediste a la gcloud CLI con tu identidad federada.
Otorga roles a tu cuenta de usuario. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM: roles/iam.serviceAccountUser
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Reemplaza lo siguiente:
• PROJECT_ID: ID del proyecto
• USER_IDENTIFIER: Es el identificador de tu cuenta de usuario de . Por ejemplo, [e-mail].
• ROLE: Es el rol de IAM que otorgas a tu cuenta de usuario.

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

• Crea un proyecto de Google Cloud :

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

• Selecciona el proyecto Google Cloud que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

Habilita las APIs de Dataflow, Compute Engine, Logging, Cloud Storage, Cloud Storage JSON, Resource Manager y Artifact Registry:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

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

Si usas un shell local, crea credenciales de autenticación locales para tu cuenta de usuario:

gcloud auth application-default login

No es necesario que lo hagas si usas Cloud Shell.

Si se devuelve un error de autenticación y usas un proveedor de identidad (IdP) externo, confirma que accediste a la gcloud CLI con tu identidad federada.

Otorga roles a tu cuenta de usuario. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM: roles/iam.serviceAccountUser

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

Reemplaza lo siguiente:

• PROJECT_ID: ID del proyecto
• USER_IDENTIFIER: Es el identificador de tu cuenta de usuario de . Por ejemplo, [e-mail].
• ROLE: Es el rol de IAM que otorgas a tu cuenta de usuario.

1. Otorga roles a tu cuenta de servicio predeterminada de Compute Engine. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM:

   • 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

   Reemplaza lo siguiente:

   • PROJECT_ID: el ID de tu proyecto
   • PROJECT_NUMBER tu Google Cloud número de proyecto
   • SERVICE_ACCOUNT_ROLE: Es cada rol individual.

Prepara tu entorno para las plantillas flexibles

Instala el SDK y cualquier requisito para 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é establecida y que apunte a la instalación del JDK.

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

Python

Usa el SDK de Apache Beam para Python.

Go

Usa la guía de descarga e instalación de Go para descargarlo e instalarlo en tu sistema operativo específico. Para obtener información sobre qué entornos de ejecución de Go son compatibles con Apache Beam, consulta Compatibilidad con el entorno de ejecución de Apache Beam.

Descarga la muestra de código.

Java

1. Clona el repositorio java-docs-samples.

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

2. Navega a la muestra de código para este instructivo.

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

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

   mvn clean package

   Este archivo Uber JAR tiene todas las dependencias incorporadas. Puedes ejecutar el archivo como una aplicación independiente sin dependencias externas en otras bibliotecas.

Python

1. Clona el repositorio python-docs-samples.

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

2. Navega a la muestra de código para este instructivo.

   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. Navega a la muestra de código para este instructivo.

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

3. Compila el objeto binario Go.

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

Crea un bucket de Cloud Storage para tu canalización de datos

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

gcloud storage buckets create gs://BUCKET_NAME

Reemplaza BUCKET_NAME por un nombre para tu bucket de Cloud Storage. Los nombres de los buckets de Cloud Storage deben ser únicos a nivel global y cumplir con los requisitos de nombres de los depósitos.

Crea un repositorio de Artifact Registry

Crea un repositorio de Artifact Registry al que enviarás la imagen de contenedor de Docker para la plantilla.

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

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

   Reemplaza lo siguiente:

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

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

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

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

Compila tu plantilla flexible de Dataflow

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

Una plantilla de Flex consta de los siguientes componentes:

• Una imagen de contenedor de Docker que empaqueta el código de tu canalización y forma una canalización de datos en contenedores. Para las plantillas flexibles de Java y Python, la imagen de Docker se compila 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 plantillas. Este archivo es un documento JSON que contiene la ubicación de la imagen de contenedor y los metadatos de la plantilla, como los parámetros de canalización.

El repositorio de muestra en GitHub contiene el archivo metadata.json.

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

Para extender 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"

Reemplaza lo siguiente:

• BUCKET_NAME: Es el nombre del bucket de Cloud Storage que creaste.
• LOCATION: la ubicación
• PROJECT_ID: Es el ID del proyecto de Google Cloud .
• REPOSITORY: Es el nombre del repositorio de Artifact Registry que creaste.

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"

Reemplaza lo siguiente:

• BUCKET_NAME: Es el nombre del bucket de Cloud Storage que creaste.
• LOCATION: la ubicación
• PROJECT_ID: Es el ID del proyecto de Google Cloud .
• REPOSITORY: Es el nombre del repositorio de Artifact Registry que creaste.

Go

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

Reemplaza lo siguiente:

• BUCKET_NAME: Es el nombre del bucket de Cloud Storage que creaste.
• LOCATION: la ubicación
• PROJECT_ID: Es el ID del proyecto de Google Cloud .
• REPOSITORY: Es el nombre del repositorio de Artifact Registry que creaste.

Ejecuta la plantilla de Flex

En este paso, usarás la plantilla para ejecutar un trabajo de Dataflow.

Java

1. Usa el comando gcloud dataflow flex-template run para ejecutar un trabajo de Dataflow que use la plantilla de 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-" \
    --region "REGION"

   Reemplaza lo siguiente:

   • BUCKET_NAME: Es el nombre del bucket de Cloud Storage que creaste.
   • REGION: la región

2. Para ver el estado del trabajo de Dataflow en la consola deGoogle Cloud , ve a la página Trabajos de Dataflow.

   Ir a Trabajos

Si el trabajo se ejecuta de forma correcta, escribe el resultado en un archivo llamado gs://BUCKET_NAME/output--00000-of-00001.txt en el bucket de Cloud Storage.

Python

1. Usa el comando gcloud dataflow flex-template run para ejecutar un trabajo de Dataflow que use la plantilla de 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-" \
    --region "REGION"

   Reemplaza lo siguiente:

   • BUCKET_NAME: Es el nombre del bucket de Cloud Storage que creaste.
   • REGION: la región

2. Para ver el estado del trabajo de Dataflow en la consola deGoogle Cloud , ve a la página Trabajos de Dataflow.

   Ir a Trabajos

Si el trabajo se ejecuta de forma correcta, escribe el resultado en un archivo llamado gs://BUCKET_NAME/output--00000-of-00001.txt en el bucket de Cloud Storage.

Go

1. Usa el comando gcloud dataflow flex-template run para ejecutar un trabajo de Dataflow que use la plantilla de 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" \
    --region "REGION"

   Reemplaza lo siguiente:

   • BUCKET_NAME: Es el nombre del bucket de Cloud Storage que creaste.
   • REGION: la región

2. Para ver el estado del trabajo de Dataflow en la consola deGoogle Cloud , ve a la página Trabajos de Dataflow.

   Ir a Trabajos

Si el trabajo se ejecuta de forma correcta, escribe el resultado en un archivo llamado gs://BUCKET_NAME/samples/dataflow/templates/count.txt en el bucket de Cloud Storage.

Si tu trabajo no se ejecuta y recibes el siguiente mensaje de error, consulta Soluciona problemas de tiempos de espera de plantillas de Flex.

A Timeout in polling error message

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

Borra el proyecto

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

• Se borra todo su contenido. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los IDs personalizados de los proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID personalizado del proyecto que desees utilizar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto, en lugar de todo el proyecto.

Si planeas explorar varios instructivos, arquitecturas o guías de inicio rápido, reutilizar proyectos puede ser útil para no exceder los límites de cuota de los proyectos.

Borra un Google Cloud proyecto:

gcloud projects delete PROJECT_ID

Borra los recursos individuales

1. Borra el bucket de Cloud Storage y todos los objetos en el bucket.

   gcloud storage rm gs://BUCKET_NAME --recursive

2. Borra el repositorio de Artifact Registry.

   gcloud artifacts repositories delete REPOSITORY \
       --location=LOCATION

3. Revoca los roles que otorgaste a la cuenta de servicio predeterminada de Compute Engine. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM:
   • 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. Opcional: Revoca las credenciales de autenticación que creaste y borra el archivo local de credenciales.

   gcloud auth application-default revoke

5. Opcional: Revoca credenciales desde gcloud CLI.

   gcloud auth revoke

¿Qué sigue?

• Usa plantillas de Flex para empaquetar una canalización de Dataflow.
• Explora los beneficios de las plantillas prediseñadas y las plantillas proporcionadas por Google para casos de uso comunes.