Configura modelli flessibili

Questa pagina documenta le varie configurazioni del modello flessibile Dataflow tra cui:

• Autorizzazioni
• Variabili di ambiente Dockerfile
• Dipendenze pacchetto
• Immagini Docker
• Opzioni pipeline
• Posizione di gestione temporanea e temperatura

Per configurare un modello flessibile di esempio, consulta Tutorial sui modelli flessibili.

Comprendi le autorizzazioni del modello flessibile

Quando lavori con i modelli flessibili, hai bisogno di tre set di autorizzazioni:

• Autorizzazioni per la creazione di risorse
• Autorizzazioni per creare un modello flessibile
• Autorizzazioni per eseguire un modello flessibile

Autorizzazioni per la creazione di risorse

Per sviluppare ed eseguire una pipeline di modello flessibile, devi creare varie di risorse (ad esempio, un bucket gestione temporanea). Per attività una tantum di creazione di risorse, puoi utilizzare il ruolo Proprietario di base.

Autorizzazioni per creare un modello flessibile

In qualità di sviluppatore di un modello flessibile, devi creare il modello per renderlo disponibili per gli utenti. La creazione comporta il caricamento delle specifiche di un modello nel bucket Cloud Storage ed eseguire il provisioning di un'immagine Docker con il codice necessarie per eseguire la pipeline. Per creare un modello flessibile, è necessario leggere e l'accesso in scrittura a Cloud Storage Accesso in Writer ad Artifact Registry nel repository Artifact Registry. Puoi concedere queste autorizzazioni assegnando il parametro ruoli:

• Amministratore Storage (roles/storage.admin)
• Editor Cloud Build (roles/cloudbuild.builds.editor)
• Writer Artifact Registry (roles/artifactregistry.writer)

Autorizzazioni per eseguire un modello flessibile

Quando esegui un modello flessibile, Dataflow crea un job per te. Per creare il job, l'account di servizio Dataflow richiede la seguente autorizzazione:

• dataflow.serviceAgent

Quando utilizzi Dataflow per la prima volta, il servizio assegna questo ruolo quindi non è necessario concederla.

Per impostazione predefinita, l'account di servizio Compute Engine viene utilizzato per le VM di avvio e VM worker. L'account di servizio richiede i ruoli e le competenze seguenti:

• Amministratore oggetti Storage (roles/storage.objectAdmin)
• Visualizzatore (roles/viewer)
• Worker Dataflow (roles/dataflow.worker)
• Accesso in lettura e scrittura al bucket di gestione temporanea
• Accesso in lettura all'immagine del modello flessibile

Per concedere l'accesso in lettura e scrittura al bucket di gestione temporanea, puoi utilizzare il ruolo Amministratore oggetti Storage (roles/storage.objectAdmin). Per ulteriori informazioni, consulta Ruoli IAM per Cloud Storage.

Per concedere l'accesso in lettura all'immagine del modello flessibile, puoi utilizzare il ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer). Per ulteriori informazioni, consulta Configurazione del controllo dell'accesso.

Imposta le variabili di ambiente Dockerfile richieste

Se vuoi creare il tuo Dockerfile per un job di modello flessibile, specificare le seguenti variabili di ambiente:

ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="${WORKDIR}/requirements.txt"
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="${WORKDIR}/streaming_beam.py"

Dipendenze pacchetto

Quando una pipeline Python Dataflow utilizza dipendenze aggiuntive, potresti dover configurare il modello flessibile per installare dipendenze aggiuntive sulle VM worker Dataflow.

Quando esegui un job Dataflow in Python che utilizza i modelli flessibili in un ambiente che limita l'accesso a internet, è necessario preconfezionare delle dipendenze quando crei il modello.

Utilizza una delle seguenti opzioni per precompilare le dipendenze Python.

Per istruzioni su come gestire le dipendenze della pipeline nelle pipeline Java e Go, consulta Gestire le dipendenze della pipeline in Dataflow.

Usa un file dei requisiti e preconfeziona le dipendenze con il modello

Se utilizzi il tuo Dockerfile per definire l'immagine del modello flessibile, segui questi passaggi:

1. Crea un file requirements.txt che elenca le dipendenze della pipeline.

   COPY requirements.txt /template/
   ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="/template/requirements.txt"
   

2. Installa le dipendenze nell'immagine del modello flessibile.

   RUN pip install --no-cache-dir -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE
   

3. Scarica le dipendenze nella cache dei requisiti locali, in fasi per i worker Dataflow al momento del lancio del modello.

   RUN pip download --no-cache-dir --dest /tmp/dataflow-requirements-cache -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE
   

Di seguito è riportato un esempio di codice che pre-scarica le dipendenze.

# Copyright 2020 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

FROM gcr.io/dataflow-templates-base/python3-template-launcher-base

# Configure the Template to launch the pipeline with a --requirements_file option.
# See: https://beam.apache.org/documentation/sdks/python-pipeline-dependencies/#pypi-dependencies
ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="/template/requirements.txt"
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/streaming_beam.py"

COPY . /template

RUN apt-get update \
    # Install any apt packages if required by your template pipeline.
    && apt-get install -y libffi-dev git \
    && rm -rf /var/lib/apt/lists/* \
    # Upgrade pip and install the requirements.
    && pip install --no-cache-dir --upgrade pip \
    # Install dependencies from requirements file in the launch environment.
    && pip install --no-cache-dir -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE \
    # When FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE  option is used,
    # then during Template launch Beam downloads dependencies
    # into a local requirements cache folder and stages the cache to workers.
    # To speed up Flex Template launch, pre-download the requirements cache
    # when creating the Template.
    && pip download --no-cache-dir --dest /tmp/dataflow-requirements-cache -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE

# Set this if using Beam 2.37.0 or earlier SDK to speed up job submission.
ENV PIP_NO_DEPS=True

ENTRYPOINT ["/opt/google/dataflow/python_template_launcher"]

Utilizza un container personalizzato che preinstalla tutte le dipendenze

Questa opzione è preferita per le pipeline in esecuzione in ambienti senza accesso a internet.

Per utilizzare un container personalizzato:

1. Crea un container personalizzato che preinstalla le dipendenze necessarie.

2. Preinstalla le stesse dipendenze nel Dockerfile del modello flessibile. Non utilizzare l'opzione FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE.

   Un elemento dataflow/flex-templates/streaming_beam/Dockerfile modificato potrebbe essere simile al seguente esempio:

   FROM gcr.io/dataflow-templates-base/python3-template-launcher-base
   ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/streaming_beam.py"
   COPY . /template
   RUN pip install --no-cache-dir -r /template/requirements.txt
   

   In alternativa, per ridurre il numero di immagini da gestire, utilizza la tua immagine container personalizzata come immagine di base per il modello flessibile.

3. Se utilizzi Apache Beam SDK versione 2.49.0 o precedente, aggiungi l'opzione pipeline --sdk_location=container nel launcher di pipeline. Questa opzione indica alla pipeline di utilizzare l'SDK del container personalizzato anziché scaricare l'SDK.

   options = PipelineOptions(beam_args, save_main_session=True, streaming=True, sdk_location="container")
   

4. Imposta il parametro sdk_container_image nel comando flex-template run. Ad esempio:

   gcloud dataflow flex-template run $JOB_NAME \
      --region=$REGION \
      --template-file-gcs-location=$TEMPLATE_PATH \
      --parameters=sdk_container_image=$CUSTOM_CONTAINER_IMAGE \
      --additional-experiments=use_runner_v2
   

   Per ulteriori informazioni, vedi Utilizzare i container personalizzati in Dataflow.

Struttura la pipeline come pacchetto

Se strutturi la pipeline come pacchetto, usa l'opzione FLEX_TEMPLATE_PYTHON_SETUP_FILE. Per ulteriori informazioni su come strutturare la pipeline come pacchetto, vedi Dipendenze file multiple nella documentazione di Apache Beam.

Se utilizzi il tuo Dockerfile per definire l'immagine del modello flessibile, installare il pacchetto nel Dockerfile.

Il Dockerfile del modello flessibile potrebbe includere quanto segue:

  COPY setup.py .
  COPY main.py .
  COPY package_name package_name

  RUN pip install -e .

  ENV FLEX_TEMPLATE_PYTHON_SETUP_FILE="${WORKDIR}/setup.py"
  ENV FLEX_TEMPLATE_PYTHON_PY_FILE="${WORKDIR}/main.py"

Se utilizzi questo metodo e un'immagine container personalizzata per preinstallare nell'ambiente di runtime, consigliamo di installare il pacchetto della pipeline nell'immagine container personalizzata al momento della sua creazione. Non specificare il Opzione FLEX_TEMPLATE_PYTHON_SETUP_FILE.

Per un esempio che segue questo approccio, consulta Modello flessibile per una pipeline con dipendenze e un'immagine container personalizzata in GitHub.

Scegli un'immagine di base

Puoi utilizzare un modello fornito da Google immagine di base per pacchettizzare il modello utilizzando Docker. Scegli il tag più recente dal Immagini di base di modelli Flex. Ti consigliamo di utilizzare un tag immagine specifico anziché latest.

Specifica l'immagine di base nel seguente formato:

gcr.io/dataflow-templates-base/IMAGE_NAME:TAG

Sostituisci quanto segue:

• IMAGE_NAME: un'immagine di base fornita da Google
• TAG: un nome versione per l'immagine di base, disponibile nelle immagini di base di modelli flessibili riferimento

Utilizza immagini container personalizzate

Se la tua pipeline utilizza un'immagine container personalizzata, ti consigliamo di utilizzare come immagine di base per l'immagine Docker del modello flessibile. Per farlo, copia il file binario dell'Avvio app del modello flessibile dal file immagine di base del modello all'immagine personalizzata.

Un esempio di Dockerfile per un'immagine che può essere utilizzata sia come immagine container SDK personalizzata sia come modello flessibile, potrebbe avere il seguente aspetto:

FROM gcr.io/dataflow-templates-base/IMAGE_NAME:TAG as template_launcher
FROM apache/beam_python3.10_sdk:2.57.0

# RUN <...Make image customizations here...>
# See: https://cloud.google.com/dataflow/docs/guides/build-container-image

# Configure the Flex Template here.
COPY --from=template_launcher /opt/google/dataflow/python_template_launcher /opt/google/dataflow/python_template_launcher
COPY my_pipeline.py /template/
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/my_pipeline.py"

Sostituisci quanto segue:

• IMAGE_NAME: un'immagine di base fornita da Google. Ad esempio: python311-template-launcher-base.
• TAG: un tag versione per l'immagine di base disponibile nelle immagini di base di modelli flessibili riferimento. Per una maggiore stabilità e risoluzione dei problemi, evita utilizzando latest. Limita invece a un tag di versione specifico.

Per un esempio che segue questo approccio, consulta il tutorial Flex Template per una pipeline con dipendenze e un'immagine container personalizzata.

Usa un'immagine da un registro privato

Puoi creare un'immagine di un modello flessibile Docker Registry se il registro privato utilizza HTTPS e ha un certificato valido.

Per utilizzare un'immagine da un registro privato, specifica il percorso dell'immagine e un nome utente e una password per il registro. Il nome utente e la password devono essere archiviati in Secret Manager. Puoi fornire il parametro secret in uno dei seguenti formati:

• projects/{project}/secrets/{secret}/versions/{secret_version}
• projects/{project}/secrets/{secret}

Se usi il secondo formato, dato che non specifica la versione, Dataflow utilizza l'ultima versione.

Se il registry utilizza un certificato autofirmato, devi specificare anche del certificato autofirmato in Cloud Storage.

La tabella seguente descrive le opzioni di gcloud CLI che puoi utilizzare per configurare un registro privato.

Ecco un esempio di comando Google Cloud CLI che crea un modello flessibile utilizzando in un registro privato con un certificato autofirmato.

gcloud dataflow flex-template build gs://example-bucket/custom-pipeline-private-repo.json
--sdk-language=JAVA
--image="gcp.repository.example.com:9082/registry/example/image:latest"
--image-repository-username-secret-id="projects/example-project/secrets/username-secret"
--image-repository-password-secret-id="projects/example-project/secrets/password-secret/versions/latest"
--image-repository-cert-path="gs://example-bucket/self-signed.crt"
--metadata-file=metadata.json

Per creare il tuo modello flessibile, devi sostituire i valori di esempio e potresti dover specificare opzioni diverse o aggiuntive. Per ulteriori informazioni vedi le risorse seguenti:

• gcloud Dataflow Flex-template Build
• Utilizzo dei modelli flessibili

Specifica le opzioni della pipeline

Per informazioni sulle opzioni di pipeline supportate direttamente da Flex Per i modelli, consulta Opzioni pipeline.

Puoi anche utilizzare indirettamente qualsiasi opzione della pipeline Apache Beam. Se utilizzando un file metadata.json per il job relativo al modello flessibile, includi queste opzioni di pipeline nel file. Questo file di metadati deve essere nel formato TemplateMetadata.

Altrimenti, quando avvii il job del modello flessibile, passare queste opzioni della pipeline utilizzando il campo dei parametri.

Quando utilizzi i modelli flessibili, puoi configurare alcune opzioni della pipeline durante dell'inizializzazione, ma non è possibile modificare altre opzioni della pipeline. Se gli argomenti della riga di comando richiesti dal modello flessibile vengono sovrascritti, il job potrebbe ignorare, ignorare o ignorare le opzioni della pipeline trasmesso dall'utilità di avvio dei modelli. Il job potrebbe non essere avviato o un job che non utilizza il modello flessibile potrebbe essere lanciato. Per ulteriori informazioni, vedi Impossibile leggere il file del job.

Durante l'inizializzazione della pipeline, non modificare quanto segue opzioni pipeline:

Blocca le chiavi SSH del progetto dalle VM che utilizzano chiavi SSH basate su metadati

Puoi impedire alle VM di accettare le chiavi SSH archiviate nei metadati di progetto bloccando le chiavi SSH del progetto dalle VM. Usa il flag additional-experiments con l'opzione di servizio block_project_ssh_keys:

--additional-experiments=block_project_ssh_keys

Per ulteriori informazioni, vedi Opzioni del servizio Dataflow.

Metadati

Puoi estendere il modello con metadati aggiuntivi in modo che i parametri personalizzati vengano convalidati quando viene eseguito il modello. Se vuoi creare metadati per il tuo modello, segui questi passaggi:

1. Crea un file metadata.json utilizzando i parametri in Parametri dei metadati.

   Per visualizzare un esempio, consulta la sezione Esempio di file di metadati.

2. Archivia il file di metadati in Cloud Storage nella stessa cartella del modello.

{
  "name": "Streaming Beam SQL",
  "description": "An Apache Beam streaming pipeline that reads JSON encoded messages from Pub/Sub, uses Beam SQL to transform the message data, and writes the results to a BigQuery",
  "parameters": [
    {
      "name": "inputSubscription",
      "label": "Pub/Sub input subscription.",
      "helpText": "Pub/Sub subscription to read from.",
      "regexes": [
        "[a-zA-Z][-_.~+%a-zA-Z0-9]{2,}"
      ]
    },
    {
      "name": "outputTable",
      "label": "BigQuery output table",
      "helpText": "BigQuery table spec to write to, in the form 'project:dataset.table'.",
      "isOptional": true,
      "regexes": [
        "[^:]+:[^.]+[.].+"
      ]
    }
  ]
}

{
  "name": "Streaming beam Python flex template",
  "description": "Streaming beam example for python flex template.",
  "parameters": [
    {
      "name": "input_subscription",
      "label": "Input PubSub subscription.",
      "helpText": "Name of the input PubSub subscription to consume from.",
      "regexes": [
        "projects/[^/]+/subscriptions/[a-zA-Z][-_.~+%a-zA-Z0-9]{2,}"
      ]
    },
    {
      "name": "output_table",
      "label": "BigQuery output table name.",
      "helpText": "Name of the BigQuery output table name.",
      "isOptional": true,
      "regexes": [
        "([^:]+:)?[^.]+[.].+"
      ]
    }
  ]
}

Informazioni sulla posizione per la gestione temporanea e sulla posizione della temperatura

Google Cloud CLI fornisce le opzioni --staging-location e --temp-location quando esegui un modello flessibile. Analogamente, l'API REST Dataflow fornisce stagingLocation tempLocation campi per FlexTemplateRuntimeEnvironment.

Per i modelli flessibili, la posizione temporanea è l'URL di Cloud Storage che durante la fase di gestione temporanea dell'avvio di un modello. Dataflow legge questi file temporanei per creare il grafico del modello. La temperatura è l'URL di Cloud Storage in cui vengono scritti i file temporanei il passaggio di esecuzione.

Aggiorna un job di modello flessibile

La seguente richiesta di esempio mostra come aggiornare un job di flusso del modello utilizzando projects.locations.flexTemplates.launch . Se vuoi utilizzare gcloud CLI, consulta Aggiorna una pipeline esistente.

Se vuoi aggiornare un modello classico, usa projects.locations.templates.launch .

1. Segui i passaggi per creare un job di flussi di dati da un modello flessibile. Invia la seguente richiesta POST HTTP con i valori modificati:

   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"
       },
   }
   

   • Sostituisci PROJECT_ID con l'ID progetto.
   • Sostituisci REGION con Dataflow region del job che stai aggiornando.
   • Sostituisci JOB_NAME con il nome esatto del job da aggiornare.
   • Imposta parameters sull'elenco di coppie chiave/valore. La i parametri elencati sono specifici per questo esempio di modello. Se utilizzi un modello personalizzato, modifica i parametri in base alle esigenze. Se stai utilizzando il modello di esempio, sostituisci le seguenti variabili.
     • Sostituisci SUBSCRIPTION_NAME con Nome sottoscrizione Pub/Sub.
     • Sostituisci DATASET con con il nome del tuo set di dati BigQuery.
     • Sostituisci TABLE_NAME con con il nome della tua tabella BigQuery.
   • Sostituisci STORAGE_PATH con Cloud Storage del modello. La località deve iniziare con gs://.

2. Utilizza il parametro environment per modificare le impostazioni dell'ambiente. Per ulteriori informazioni informazioni, vedi FlexTemplateRuntimeEnvironment.

3. (Facoltativo) Per inviare la richiesta utilizzando curl (Linux, macOS o Cloud Shell), salva il a un file JSON ed esegui questo 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
   

   Sostituisci FILE_PATH con il percorso del file JSON che contiene l'oggetto corpo della richiesta.

4. Utilizza la Interfaccia di monitoraggio di Dataflow per verificare che sia stato creato un nuovo job con lo stesso nome. Questo job ha stato Aggiornato.

Limitazioni

Le seguenti limitazioni si applicano ai job dei modelli flessibili:

• Devi utilizzare un'immagine di base fornita da Google per pacchettizzare i container utilizzando e Docker. Per un elenco delle immagini applicabili, consulta Immagini di base del modello flessibile.
• Il programma che crea la pipeline deve uscire dopo la chiamata di run in modo da consentire l'avvio della pipeline.
• waitUntilFinish (Java) e wait_until_finish (Python) non sono supportati.

Passaggi successivi

• Per saperne di più sui modelli classici e flessibili e sui relativi scenari di utilizzo, consulta l'articolo sui modelli Dataflow.
• Per informazioni sulla risoluzione dei problemi relativi ai modelli flessibili, vedi Risolvere i problemi di timeout dei modelli flessibili.
• Per altre architetture di riferimento, diagrammi e best practice, esplora il Centro architetture cloud.