En este instructivo, crearás una canalización que use contenedores personalizados con bibliotecas de C++ para ejecutar un flujo de trabajo altamente paralelo de HPC de Dataflow. Usa este instructivo para aprender a usar Dataflow y Apache Beam a fin de ejecutar aplicaciones de computación en red que requieran que los datos se distribuyan a funciones que se ejecutan en varios núcleos.
En el instructivo, primero se muestra cómo ejecutar la canalización mediante el ejecutor directo y, luego, mediante el ejecutor de Dataflow. Si ejecutas la canalización de forma local, puedes probarla antes de implementarla.
En este ejemplo, se usan vinculaciones y funciones de Cython de la biblioteca de GMP. Sin importar la biblioteca o la herramienta de vinculación que uses, puedes aplicar los mismos principios a tu canalización.
El código está disponible en GitHub.
Objetivos
Crear una canalización que use contenedores personalizados con bibliotecas C++.
Compilar una imagen de contenedor de Docker con un Dockerfile.
Empaquetar el código y las dependencias en un contenedor de Docker.
Ejecutar la canalización de forma local para probarla.
Ejecutar la canalización en un entorno distribuido.
Costos
En este documento, usarás los siguientes componentes facturables de Google Cloud:
- Artifact Registry
- Cloud Build
- Cloud Storage
- Compute Engine
- Dataflow
Para generar una estimación de costos en función del uso previsto,
usa la calculadora de precios.
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 permisoresourcemanager.projects.create. Obtén más información para otorgar roles.
-
Crea un proyecto de Google Cloud :
gcloud projects create PROJECT_ID
Reemplaza
PROJECT_IDpor 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_IDpor el nombre de tu Google Cloud proyecto.
-
Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .
Habilita las APIs de Cloud Storage, Cloud Storage JSON, Compute Engine, Dataflow, Resource Manager, Artifact Registry y Cloud Build:
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 permisoserviceusage.services.enable. Obtén más información para otorgar roles.gcloud services enable compute.googleapis.com
dataflow.googleapis.com storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com -
Crea credenciales de autenticación locales para tu cuenta de usuario:
gcloud auth application-default login
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.serviceAccountUsergcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Reemplaza lo siguiente:
PROJECT_ID: ID del proyectoUSER_IDENTIFIER: Es el identificador de tu cuenta de usuario de . Por ejemplo,myemail@example.com.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 permisoresourcemanager.projects.create. Obtén más información para otorgar roles.
-
Crea un proyecto de Google Cloud :
gcloud projects create PROJECT_ID
Reemplaza
PROJECT_IDpor 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_IDpor el nombre de tu Google Cloud proyecto.
-
Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .
Habilita las APIs de Cloud Storage, Cloud Storage JSON, Compute Engine, Dataflow, Resource Manager, Artifact Registry y Cloud Build:
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 permisoserviceusage.services.enable. Obtén más información para otorgar roles.gcloud services enable compute.googleapis.com
dataflow.googleapis.com storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com -
Crea credenciales de autenticación locales para tu cuenta de usuario:
gcloud auth application-default login
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.serviceAccountUsergcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Reemplaza lo siguiente:
PROJECT_ID: ID del proyectoUSER_IDENTIFIER: Es el identificador de tu cuenta de usuario de . Por ejemplo,myemail@example.com.ROLE: Es el rol de IAM que otorgas a tu cuenta de usuario.
Crea una cuenta de servicio de trabajador administrado por el usuario para tu canalización nueva y otórgale los roles necesarios.
Para crear la cuenta de servicio, ejecuta el comando
gcloud iam service-accounts create:gcloud iam service-accounts create parallelpipeline \ --description="Highly parallel pipeline worker service account" \ --display-name="Highly parallel data pipeline access"
Otorga roles a la cuenta de servicio. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM:
roles/dataflow.adminroles/dataflow.workerroles/storage.objectAdminroles/artifactregistry.reader
gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:parallelpipeline@PROJECT_ID.iam.gserviceaccount.com" --role=SERVICE_ACCOUNT_ROLE
Reemplaza
SERVICE_ACCOUNT_ROLEpor cada rol individual.Otorga a tu Cuenta de Google un rol que te permita crear tokens de acceso para la cuenta de servicio:
gcloud iam service-accounts add-iam-policy-binding parallelpipeline@PROJECT_ID.iam.gserviceaccount.com --member="user:EMAIL_ADDRESS" --role=roles/iam.serviceAccountTokenCreator
Descarga la muestra de código y, luego, cambia de directorio
Descarga la muestra de código y, luego, cambia de directorio. Las muestras de código en el repositorio de GitHub proporcionan todo el código que necesitas para ejecutar esta canalización. Cuando estés listo para compilar tu propia canalización, puedes usar este código de muestra como una plantilla.
Clona el repositorio beam-cpp-example.
Usa el comando
git clonepara clonar el repositorio de GitHub:git clone https://github.com/GoogleCloudPlatform/dataflow-sample-applications.gitCambia al directorio de la aplicación:
cd dataflow-sample-applications/beam-cpp-example
Código de canalización
Usa este instructivo para personalizar el código de este instructivo. Esta canalización completa las siguientes tareas:
- Produce de forma dinámica todos los números enteros en un rango de entrada.
- Ejecuta los números enteros a través de una función de C++ y filtra los valores incorrectos.
- Escribe los valores incorrectos en un canal lateral.
- Cuenta el caso de cada hora de detención y normaliza los resultados.
- Imprime el resultado, formatea y escribe los resultados en un archivo de texto.
- Crea una
PCollectionde un solo elemento. - Procesa el elemento único con una función
mapy pasa la frecuenciaPCollectioncomo una entrada complementaria. - Procesa
PCollectiony produce un solo resultado.
El archivo inicial se ve de la siguiente manera:
Configura tu entorno de desarrollo
Usa el SDK de Apache Beam para Python.
Instala la biblioteca de GMP:
apt-get install libgmp3-devPara instalar las dependencias, usa el archivo
requirements.txt.pip install -r requirements.txtPara compilar las vinculaciones de Python, ejecuta el siguiente comando.
python setup.py build_ext --inplace
Usa este instructivo para personalizar el requirements.txt. El archivo inicial incluye las siguientes dependencias:
Ejecute la canalización de forma local:
Ejecutar la canalización de manera local es útil para realizar pruebas. Si ejecutas la canalización de manera local, puedes confirmar que la canalización se ejecute y se comporte como se espera antes de implementar la canalización en un entorno distribuido.
Puedes ejecutar la canalización de manera local con el siguiente comando.
Este comando genera una imagen llamada out.png.
python pipeline.py
Crea los recursos Google Cloud
En esta sección, se explica cómo crear lo siguiente:
- Un bucket de Cloud Storage para usar como ubicación de almacenamiento temporal y de salida.
- Un contenedor de Docker para empaquetar el código de la canalización y las dependencias.
Crea un bucket de Cloud Storage
Primero, crea un bucket de Cloud Storage mediante Google Cloud CLI. La canalización de Dataflow usa este bucket como ubicación de almacenamiento temporal.
Para crear el bucket, usa el comando gcloud storage buckets create:
gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION
Reemplaza lo siguiente:
- BUCKET_NAME: Es un nombre para tu bucket de Cloud Storage que cumple con los requisitos de nombres de buckets. Los nombres de buckets de Cloud Storage deben ser únicos a nivel global.
- LOCATION: la ubicación del bucket.
Crea y compila una imagen de contenedor
Usa este instructivo para personalizar el Dockerfile. El archivo inicial se ve de la siguiente manera:
Este Dockerfile contiene los comandos FROM, COPY y RUN, que puedes leer en la referencia de Dockerfile.
Para subir artefactos, crea un repositorio de Artifact Registry. Cada repositorio puede contener artefactos para un formato compatible único.
Todo el contenido del repositorio se encripta con claves de encriptación Google-owned and Google-managed encryption keys o administradas por el cliente. Artifact Registry usaGoogle-owned and Google-managed encryption keys de forma predeterminada y no se requiere ninguna configuración para esta opción.
Debes tener al menos el acceso de escritor de Artifact Registry al repositorio.
Ejecuta el siguiente comando para crear un repositorio nuevo. El comando usa la marca
--asyncy se muestra de inmediato, sin necesidad de esperar a que se complete la operación en curso.gcloud artifacts repositories create REPOSITORY \ --repository-format=docker \ --location=LOCATION \ --asyncReemplaza
REPOSITORYpor un nombre para tu repositorio. Para la ubicación de cada repositorio en un proyecto, los nombres de los repositorios deben ser únicos.Crea el Dockerfile.
Para que los paquetes formen parte del contenedor de Apache Beam, debes especificarlos como parte del archivo
requirements.txt. Asegúrate de no especificarapache-beamcomo parte del archivorequirements.txt. El contenedor de Apache Beam ya tieneapache-beam.Antes de poder enviar o extraer imágenes, configura Docker para autenticar solicitudes de Artifact Registry. Para configurar la autenticación en los repositorios de Docker, ejecuta el siguiente comando:
gcloud auth configure-docker LOCATION-docker.pkg.devEl comando actualiza tu configuración de Docker. Ahora puedes conectarte con Artifact Registry en tu proyecto Google Cloud para enviar imágenes.
Compila la imagen de Docker mediante
Dockerfilecon Cloud Build.Actualiza la ruta de acceso en el siguiente comando para que coincida con el Dockerfile que creaste. 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/cpp_beam_container:latest .
Empaqueta el código y las dependencias en un contenedor de Docker
Para ejecutar esta canalización en un entorno distribuido, empaqueta el código y las dependencias en un contenedor de Docker.
docker build . -t cpp_beam_containerDespués de empaquetar el código y las dependencias, puedes ejecutar la canalización de forma local para probarla.
python pipeline.py \ --runner=PortableRunner \ --job_endpoint=embed \ --environment_type=DOCKER \ --environment_config="docker.io/library/cpp_beam_container"Con este comando, se escribe el resultado dentro de la imagen de Docker. Para ver el resultado, ejecuta la canalización con
--outputy escribe el resultado en un bucket de Cloud Storage. Por ejemplo, ejecuta el siguiente comando.python pipeline.py \ --runner=PortableRunner \ --job_endpoint=embed \ --environment_type=DOCKER \ --environment_config="docker.io/library/cpp_beam_container" \ --output=gs://BUCKET_NAME/out.png
Ejecuta la canalización
Ahora puedes ejecutar la canalización de Apache Beam en Dataflow mediante una consulta al archivo con el código de canalización y pasar los parámetros que requiere la canalización.
En tu shell o terminal, ejecuta la canalización con el ejecutor de Dataflow.
python pipeline.py \
--runner=DataflowRunner \
--project=PROJECT_ID \
--region=REGION \
--temp_location=gs://BUCKET_NAME/tmp \
--sdk_container_image="LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/cpp_beam_container:latest" \
--experiment=use_runner_v2 \
--output=gs://BUCKET_NAME/out.png
Después de ejecutar el comando para ejecutar la plantilla, el Dataflow muestra un ID de trabajo con el estado En cola. Es posible que el estado del trabajo demore varios minutos en Ejecutarse y que pueda acceder al grafo del trabajo.
Ve los resultados
Consulta los datos escritos en tu bucket de Cloud Storage. Usa el comando gcloud storage ls para mostrar el contenido en el nivel superior del bucket:
gcloud storage ls gs://BUCKET_NAME
Si no hay errores, el comando mostrará un mensaje similar a este:
gs://BUCKET_NAME/out.png
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
La manera más fácil de eliminar la facturación es borrar el Google Cloud proyecto que creaste para el instructivo.
- En la Google Cloud consola, ve a la página Administrar recursos.
- En la lista de proyectos, elige el proyecto que quieres borrar y haz clic en Borrar.
- En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.
Borra los recursos individuales
Si deseas volver a usar el proyecto, borra los recursos que creaste para el instructivo.
Limpia los Google Cloud recursos del proyecto
Borra el repositorio de Artifact Registry.
gcloud artifacts repositories delete REPOSITORY \ --location=LOCATION --asyncBorra el bucket de Cloud Storage y sus objetos. El bucket por sí solo no genera cargos.
gcloud storage rm gs://BUCKET_NAME --recursive
Revoca credenciales
Revoca los roles que otorgaste a la cuenta de servicio de trabajador administrada por el usuario. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM:
roles/dataflow.adminroles/dataflow.workerroles/storage.objectAdminroles/artifactregistry.reader
gcloud projects remove-iam-policy-binding PROJECT_ID \ --member=serviceAccount:parallelpipeline@PROJECT_ID.iam.gserviceaccount.com \ --role=SERVICE_ACCOUNT_ROLE
-
Opcional: Revoca las credenciales de autenticación que creaste y borra el archivo local de credenciales.
gcloud auth application-default revoke
-
Opcional: Revoca credenciales desde gcloud CLI.
gcloud auth revoke
¿Qué sigue?
- Consulta la aplicación de muestra en GitHub.
- Usa contenedores personalizados en Dataflow.
- Obtén más información sobre el uso de entornos de contenedores con Apache Beam.
- Explora arquitecturas de referencia, diagramas y prácticas recomendadas sobre Google Cloud. Consulta nuestro Cloud Architecture Center.