Crea ed esegui un modello flessibile di esempio in Dataflow

I modelli flessibili di Dataflow ti consentono di pacchettizzare una pipeline Dataflow per il deployment. Questo tutorial mostra come creare un modello flessibile di esempio e poi eseguire un job Dataflow utilizzando questo modello.

Obiettivi

• Crea un modello flessibile Dataflow.
• Utilizza il modello per eseguire un job Dataflow.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud Platform:

• Dataflow
• Cloud Storage
• Artifact Registry

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi.

I nuovi utenti di Google Cloud potrebbero avere diritto a una prova gratuita.

Al termine delle attività descritte in questo documento, puoi evitare l'addebito di ulteriori costi eliminando le risorse che hai creato. Per saperne di più, consulta Esegui la pulizia.

Prima di iniziare

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.
Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.
Per inizializzare gcloud CLI, esegui questo 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 role (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, and Artifact Registry 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
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.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo 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 role (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, and Artifact Registry 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

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. Concedi ruoli al account di servizio Compute Engine predefinito. Esegui il seguente comando una volta per ciascuno dei seguenti ruoli 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

   Sostituisci quanto segue:

   • PROJECT_ID: il tuo ID progetto
   • PROJECT_NUMBER il tuo numero di progetto
   • SERVICE_ACCOUNT_ROLE: ogni singolo ruolo

Prepara l'ambiente

Installa l'SDK e tutti i requisiti per l'ambiente di sviluppo.

Java

1. Scarica e installa Java Development Kit (JDK) versione 17. Verifica che la variabile di ambiente JAVA_HOME sia impostata e punti all'installazione di JDK.

2. Scarica e installa Apache Maven seguendo la guida all'installazione di Maven per il tuo sistema operativo specifico.

Python

Installa l'SDK Apache Beam per Python.

Vai

Utilizza la guida al download e all'installazione di Go per scaricare e installare Go per il tuo sistema operativo specifico. Per scoprire quali ambienti di runtime Go sono supportati da Apache Beam, consulta Supporto del runtime Apache Beam.

Scarica il esempio di codice.

Java

1. Clona il repository java-docs-samples.

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

2. Vai al esempio di codice per questo tutorial.

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

3. Crea il progetto Java in un file Uber JAR.

   mvn clean package

   Questo file Uber JAR contiene tutte le dipendenze incorporate. Puoi eseguire questo file come applicazione autonoma senza dipendenze esterne da altre librerie.

Python

1. Clona il repository python-docs-samples.

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

2. Vai al esempio di codice per questo tutorial.

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

Vai

1. Clona il repository golang-samples.

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

2. Vai al esempio di codice per questo tutorial.

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

3. Compila il binario Go.

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

Crea un bucket Cloud Storage

Utilizza il comando gcloud storage buckets create per creare un bucket Cloud Storage:

gcloud storage buckets create gs://BUCKET_NAME

Sostituisci BUCKET_NAME con un nome per il tuo bucket Cloud Storage. I nomi dei bucket Cloud Storage devono essere univoci a livello globale e soddisfare i requisiti di denominazione dei bucket.

Crea un repository Artifact Registry

Crea un repository Artifact Registry in cui eseguire il push dell'immagine del container Docker per il modello.

1. Utilizza il comando gcloud artifacts repositories create per creare un nuovo repository Artifact Registry.

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

   Sostituisci quanto segue:

   • REPOSITORY: un nome per il repository. I nomi dei repository devono essere univoci per ogni posizione del repository in un progetto.
   • LOCATION: la posizione regionale o multiregionale per il repository.

2. Utilizza il comando gcloud auth configure-docker per configurare Docker in modo da autenticare le richieste per Artifact Registry. Questo comando aggiorna la configurazione Docker in modo da poterti connettere ad Artifact Registry per eseguire il push delle immagini.

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

I modelli flessibili possono utilizzare anche immagini archiviate in registri privati. Per saperne di più, consulta Utilizzare un'immagine di un registro privato.

Crea il modello flessibile

In questo passaggio, utilizzi il comando gcloud dataflow flex-template build per creare il modello flessibile.

Un modello flessibile è costituito dai seguenti componenti:

• Un'immagine container Docker che contiene il codice della pipeline. Per i modelli flessibili Java e Python, l'immagine Docker viene creata e ne viene eseguito il push nel repository Artifact Registry quando esegui il comando gcloud dataflow flex-template build.
• Un file di specifica del modello. Questo file è un documento JSON che contiene la posizione dell'immagine container e i metadati relativi al modello, ad esempio i parametri della pipeline.

Il repository di esempio in GitHub contiene il file metadata.json.

• repository java-docs-samples
• repository python-docs-samples
• repository golang-samples

Per estendere il modello con metadati aggiuntivi, puoi creare il tuo file 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"

Sostituisci quanto segue:

• BUCKET_NAME: il nome del bucket Cloud Storage che hai creato in precedenza
• LOCATION: la posizione
• PROJECT_ID: l' Google Cloud ID progetto
• REPOSITORY: il nome del repository Artifact Registry che hai creato in precedenza

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"

Sostituisci quanto segue:

• BUCKET_NAME: il nome del bucket Cloud Storage che hai creato in precedenza
• LOCATION: la posizione
• PROJECT_ID: l' Google Cloud ID progetto
• REPOSITORY: il nome del repository Artifact Registry che hai creato in precedenza

Vai

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"

Sostituisci quanto segue:

• BUCKET_NAME: il nome del bucket Cloud Storage che hai creato in precedenza.
• LOCATION: la posizione
• PROJECT_ID: l' Google Cloud ID progetto
• REPOSITORY: il nome del repository Artifact Registry che hai creato in precedenza

Esegui il modello flessibile

In questo passaggio, utilizzi il modello per eseguire un job Dataflow.

Java

1. Utilizza il comando gcloud dataflow flex-template run per eseguire un job Dataflow che utilizza il modello flessibile.

   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"

   Sostituisci quanto segue:

   • BUCKET_NAME: il nome del bucket Cloud Storage che hai creato in precedenza
   • REGION: la regione

2. Per visualizzare lo stato del job Dataflow nella consoleGoogle Cloud , vai alla pagina Job di Dataflow.

   Vai a Job

Se il job viene eseguito correttamente, scrive l'output in un file denominato gs://BUCKET_NAME/output--00000-of-00001.txt nel bucket Cloud Storage.

Python

1. Utilizza il comando gcloud dataflow flex-template run per eseguire un job Dataflow che utilizza il modello flessibile.

   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"

   Sostituisci quanto segue:

   • BUCKET_NAME: il nome del bucket Cloud Storage che hai creato in precedenza
   • REGION: la regione

2. Per visualizzare lo stato del job Dataflow nella consoleGoogle Cloud , vai alla pagina Job di Dataflow.

   Vai a Job

Se il job viene eseguito correttamente, scrive l'output in un file denominato gs://BUCKET_NAME/output--00000-of-00001.txt nel bucket Cloud Storage.

Vai

1. Utilizza il comando gcloud dataflow flex-template run per eseguire un job Dataflow che utilizza il modello flessibile.

   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"

   Sostituisci quanto segue:

   • BUCKET_NAME: il nome del bucket Cloud Storage che hai creato in precedenza
   • REGION: la regione

2. Per visualizzare lo stato del job Dataflow nella consoleGoogle Cloud , vai alla pagina Job di Dataflow.

   Vai a Job

Se il job viene eseguito correttamente, scrive l'output in un file denominato gs://BUCKET_NAME/samples/dataflow/templates/count.txt nel bucket Cloud Storage.

Se l'esecuzione del job non riesce e viene visualizzato il messaggio di errore A Timeout in polling error message, consulta la sezione Risolvere i problemi relativi ai timeout dei modelli flessibili.

Esegui la pulizia

Per evitare che al tuo Account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Elimina il progetto

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività descritte in questo documento, eliminerai anche tutto il lavoro che hai svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Elimina singole risorse

1. Elimina il bucket Cloud Storage e tutti gli oggetti al suo interno.

   gcloud storage rm gs://BUCKET_NAME --recursive

2. Elimina il repository Artifact Registry.

   gcloud artifacts repositories delete REPOSITORY \
       --location=LOCATION

3. Revoca i ruoli che hai concesso all'account di servizio Compute Engine predefinito. Esegui il seguente comando una volta per ciascuno dei seguenti ruoli 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. 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

Passaggi successivi

• Utilizza i modelli flessibili per pacchettizzare una pipeline Dataflow.
• Consulta l'elenco dei modelli forniti da Google.