Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzare i modelli flessibili per pacchettizzare una pipeline Dataflow per il deployment

Questa pagina descrive come creare un modello flessibile per una pipeline Dataflow. I modelli flessibili ti consentono di pacchettizzare il codice della pipeline Apache Beam in modo da poter eseguire la pipeline senza un ambiente di sviluppo. Se crei un modello flessibile, chiunque disponga delle autorizzazioni corrette può eseguire la pipeline come job Dataflow.

Per un tutorial end-to-end sulla creazione e l'esecuzione di un modello flessibile, consulta Crea ed esegui un modello flessibile di esempio.

Panoramica

Un modello flessibile è costituito dai seguenti componenti:

Un'immagine container archiviata in Artifact Registry. Il container è responsabile dell'avvio del job Dataflow.
Un file di specifica JSON archiviato in Cloud Storage. Questo file contiene un puntatore all'immagine del container e altri metadati.

Prima di creare un modello flessibile, devi utilizzare l'SDK Apache Beam per scrivere il codice della pipeline. Per saperne di più, consulta Utilizzare Apache Beam per creare pipeline.

Il programma che crea la pipeline deve uscire dopo la chiamata a run, in modo che la pipeline possa avviarsi. Non chiamare waitUntilFinish (Java) o wait_until_finish (Python), poiché queste funzioni bloccano e impediscono l'esecuzione del modello flessibile.

Autorizzazioni obbligatorie

Per ottenere le autorizzazioni necessarie per creare un modello flessibile, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

Storage Admin (roles/storage.admin)
Editor Cloud Build (roles/cloudbuild.builds.editor)
Autore Artifact Registry (roles/artifactregistry.writer)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Metadati del modello

Se vuoi, puoi fornire metadati aggiuntivi per il modello, tra cui:

Parametri pipeline: dichiara eventuali opzioni pipeline personalizzate utilizzate dalla pipeline. Dataflow convalida i parametri quando invii il job del modello flessibile. Se esegui il modello utilizzando la consoleGoogle Cloud , la finestra di dialogo Crea job dal modello include i parametri della pipeline dichiarati nei metadati.
Supporto dello streaming: puoi specificare se la pipeline supporta lo streaming e, in caso affermativo, se supporta la modalità exactly-once o at-least-once. Questi metadati consentono alla console Google Cloud di visualizzare le opzioni della pipeline pertinenti quando esegui il modello.

Per includere metadati aggiuntivi, crea un file JSON con i parametri dei metadati. Specifica questo file nel flag --metadata-file del comando gcloud dataflow flex-template build. I contenuti del file di metadati vengono uniti al file di specifica del modello. Per saperne di più, vedi Creare un modello flessibile.

Parametri dei metadati

Chiave parametro		Obbligatorio	Descrizione del valore
`name`		Sì	Il nome del modello.
`description`		No	Un breve paragrafo di testo che descrive il modello.
`streaming`		No	Se `true`, questo modello supporta lo streaming. Il valore predefinito è `false`.
`supportsAtLeastOnce`		No	Se `true`, questo modello supporta l'elaborazione almeno una volta. Il valore predefinito è `false`. Imposta questo parametro su `true` se il modello è progettato per funzionare con la modalità flusso di dati Almeno una volta.
`supportsExactlyOnce`		No	Se `true`, questo modello supporta l'elaborazione "exactly-once". Il valore predefinito è `true`.
`defaultStreamingMode`		No	La modalità flusso di dati predefinita per i modelli che supportano sia la modalità "at least once" sia la modalità "exactly-once". Utilizza uno dei seguenti valori: `"AT_LEAST_ONCE"`, `"EXACTLY_ONCE"`. Se non specificata, la modalità di streaming predefinita è esattamente una volta.
`parameters`		No	Un array di parametri aggiuntivi utilizzati dal modello. Per impostazione predefinita, viene utilizzato un array vuoto.
	`name`	Sì	Il nome del parametro utilizzato nel modello.
	`label`	Sì	Una stringa leggibile utilizzata nella console Google Cloud per etichettare il parametro.
	`helpText`	Sì	Un breve paragrafo di testo che descrive il parametro.
	`isOptional`	No	`false` se il parametro è obbligatorio e `true` se è facoltativo. Se non viene impostato un valore, `isOptional` ha come valore predefinito `false`. Se non includi questa chiave di parametro per i metadati, questi diventano un parametro obbligatorio.
	`regexes`	No	Un array di espressioni regolari POSIX-egrep in formato stringa utilizzato per convalidare il valore del parametro. Ad esempio, `["^[a-zA-Z][a-zA-Z0-9]+"]` è una singola espressione regolare che verifica che il valore inizi con una lettera e contenga uno o più caratteri. Per impostazione predefinita, viene utilizzato un array vuoto.

File di metadati di esempio

Java

{
  "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": [
        "[^:]+:[^.]+[.].+"
      ]
    }
  ]
}

Python

{
  "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": [
        "([^:]+:)?[^.]+[.].+"
      ]
    }
  ]
}

Puoi scaricare i file di metadati per i modelli forniti da Google dalla directory dei modelli Dataflow.

Variabili di ambiente

Quando crei un modello flessibile, specifica le seguenti variabili di ambiente nel flag --env del comando gcloud dataflow flex-template build. Se utilizzi un'immagine personalizzata, imposta queste variabili di ambiente nel Dockerfile.

Java

ENV	Descrizione	Obbligatorio
`FLEX_TEMPLATE_JAVA_MAIN_CLASS`	Specifica la classe Java da eseguire per avviare il modello flessibile.	SÌ
`FLEX_TEMPLATE_JAVA_CLASSPATH`	Specifica la posizione dei file di classe.	SÌ
`FLEX_TEMPLATE_JAVA_OPTIONS`	Specifica le opzioni Java da trasmettere durante l'avvio del modello flessibile.	NO

Specifica FLEX_TEMPLATE_JAVA_MAIN_CLASS e FLEX_TEMPLATE_JAVA_CLASSPATH nel Dockerfile.

Python

ENV	Descrizione	Obbligatorio
`FLEX_TEMPLATE_PYTHON_PY_FILE`	Specifica il file Python da eseguire per avviare il modello flessibile.	SÌ
`FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE`	Specifica il file dei requisiti con le dipendenze della pipeline. Per saperne di più, consulta la sezione Dipendenze PyPI nella documentazione di Apache Beam.	NO
`FLEX_TEMPLATE_PYTHON_SETUP_FILE`	Specifica il percorso del file `setup.py` del pacchetto della pipeline. Per ulteriori informazioni, consulta la sezione Multiple File Dependencies nella documentazione di Apache Beam.	NO
`FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES`	Specifica i pacchetti non disponibili pubblicamente. Per informazioni sull'utilizzo di pacchetti aggiuntivi, leggi Dipendenze locali o non PyPI.	NO
`FLEX_TEMPLATE_PYTHON_PY_OPTIONS`	Specifica le opzioni Python da trasmettere durante l'avvio del modello flessibile.	NO

Specifica FLEX_TEMPLATE_PYTHON_PY_FILE nel Dockerfile.

Per gestire le dipendenze della pipeline, imposta le variabili nel Dockerfile, ad esempio le seguenti:

FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE
FLEX_TEMPLATE_PYTHON_PY_OPTIONS
FLEX_TEMPLATE_PYTHON_SETUP_FILE
FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES

Ad esempio, le seguenti variabili di ambiente sono impostate nel tutorial Streaming nel modello Python Flex su GitHub:

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

Vai

ENV	Descrizione	Obbligatorio
`FLEX_TEMPLATE_GO_BINARY`	Specifica il file binario Go da eseguire.	SÌ

Specifica FLEX_TEMPLATE_GO_BINARY nel Dockerfile.

Immagini dei modelli flessibili

Un modello flessibile include un'immagine container che avvia la pipeline Dataflow. Quando esegui un job Flex Template, il servizio Dataflow scarica l'immagine container da Artifact Registry e avvia il container. Il container è responsabile dell'avvio del job Dataflow.

Google gestisce un insieme di immagini di base per i modelli flessibili che puoi utilizzare. Tuttavia, se la pipeline richiede un'immagine container personalizzata, ti consigliamo di utilizzare la stessa immagine per il modello flessibile. In questo modo, il launcher del modello Flex contiene le stesse dipendenze del container runtime della pipeline.

Immagini container personalizzate

Per creare un'immagine Flex Template personalizzata, includi i seguenti passaggi nel Dockerfile:

Copia il binario di avvio del modello flessibile da una delle immagini di base fornite da Google nella tua immagine. Il programma binario di avvio si trova nel seguente percorso:

Java
/opt/google/dataflow/java_template_launcher

Python
/opt/google/dataflow/python_template_launcher

Vai
/opt/google/dataflow/go_template_launcher
Copia gli artefatti necessari per avviare il job della pipeline, ad esempio file Python, file JAR o file binari Go.
Imposta le variabili di ambiente elencate in Variabili di ambiente.

L'esempio seguente mostra un Dockerfile per una pipeline Python:

# Flex Template base image. Used here to get the launcher binary.
FROM gcr.io/dataflow-templates-base/IMAGE_NAME:TAG as template_launcher

# Apache Beam SDK image. This is the base image for the pipeline job.
FROM apache/beam_python3.10_sdk:2.69.0

# Customize the image for your pipeline.
# [...]

# Configure the Flex Template.
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 di versione per l'immagine di base elencata in Immagini di base per i modelli flessibili. Per una maggiore stabilità e una migliore risoluzione dei problemi, evita di utilizzare latest. ma blocca un tag di versione specifico.

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

Crea un modello flessibile

Per creare un modello flessibile, utilizza il comando gcloud dataflow flex-template build. Questo comando crea i seguenti artefatti:

Il file di specifica del modello, archiviato in Cloud Storage
L'immagine container del launcher, archiviata in Artifact Registry

Utilizzare un'immagine di base fornita da Google

Per eseguire un modello flessibile utilizzando un'immagine di base fornita da Google, esegui questo comando:

Java

gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG" \
  --sdk-language "JAVA" \
  --flex-template-base-image "BASE_IMAGE" \
  --metadata-file "METADATA_FILE" \
  --jar "JAR_FILE" \
  --env "FLEX_TEMPLATE_JAVA_MAIN_CLASS=JAVA_MAIN_CLASS"

Sostituisci quanto segue:

BUCKET_NAME: il nome di un bucket Cloud Storage in cui archiviare il file di specifica del modello
TEMPLATE_FILE_NAME: il nome del file di specifica del modello da creare. Esempio: my_template.json
LOCATION: la posizione del repository Artifact Registry
PROJECT_ID: l' Google Cloud ID progetto
REPOSITORY: il nome del repository Artifact Registry
IMAGE: il nome dell'immagine container del modello flessibile
TAG: il tag per l'immagine del container del modello flessibile
<pBASE_IMAGE: the base image to use. Specify one of the following: A predefined label, such as "JAVA17". For more information, see the documentation for the --flex-template-base-image flag. The full gcr.io path to a specific container version, in the following format: gcr.io/dataflow-templates-base/IMAGE:TAG.


  
    METADATA_FILE: il percorso locale di un file metafile. Per saperne di più,
    vedi Metadati
    del modello.
  

  
    JAR_FILE: il percorso locale del file JAR per il codice della pipeline. Se
    sono presenti più file JAR, formattali come un elenco separato da virgole o specificali in flag --jar separati.
  
  
    JAVA_MAIN_CLASS: il nome della classe Java da eseguire. Per ulteriori
    informazioni, vedi Variabili di ambiente.


 Python 





  



gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG" \
  --sdk-language "PYTHON" \
  --flex-template-base-image "BASE_IMAGE" \
  --metadata-file "METADATA_FILE" \
  --py-path "PYTHON_FILE_PATH" \
  --env "FLEX_TEMPLATE_PYTHON_PY_FILE=PYTHON_FILE"


Sostituisci quanto segue:

  
    BUCKET_NAME: il nome di un bucket Cloud Storage in cui archiviare il file di specifica del modello
  
  
    TEMPLATE_FILE_NAME: il nome del file di specifica del modello da
    creare. Esempio: my_template.json
  
  
    LOCATION: la posizione del repository Artifact Registry
  
  
    PROJECT_ID: l' Google Cloud ID progetto
  
  
    REPOSITORY: il nome del repository Artifact Registry
  
  
    IMAGE: il nome dell'immagine container del modello flessibile
  
  
    TAG: il tag per l'immagine del container del modello flessibile
  
  
    <pBASE_IMAGE: the base image to use. Specify one of the following:
    
      
        A predefined label, such as "PYTHON3". For more information, see the documentation
        for the 
        --flex-template-base-image flag.
      
      
        The full gcr.io path to a specific container version, in the following format:
        gcr.io/dataflow-templates-base/IMAGE:TAG.
      
    
  

  
    METADATA_FILE: il percorso locale di un file metafile. Per ulteriori informazioni,
    consulta la sezione Metadati
    del modello.
  

  
    PYTHON_FILE_PATH: il percorso locale dei file Python per la pipeline e di tutti i relativi file dipendenti. Puoi specificare più percorsi come elenco separato da virgole o come
    flag --py-path separati.
  
  
    PYTHON_FILE: il file Python da eseguire. Per maggiori informazioni, vedi
    Variabili di ambiente.
  


 Vai 





  



gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG" \
  --sdk-language "GO" \
  --flex-template-base-image "BASE_IMAGE" \
  --metadata-file "METADATA_FILE" \
  --go-binary-path="GO_FILE_PATH" \
  --env "FLEX_TEMPLATE_GO_BINARY=GO_BINARY"


Sostituisci quanto segue:

  
    BUCKET_NAME: il nome di un bucket Cloud Storage in cui archiviare il file di specifica del modello
  
  
    TEMPLATE_FILE_NAME: il nome del file di specifica del modello da
    creare. Esempio: my_template.json
  
  
    LOCATION: la posizione del repository Artifact Registry
  
  
    PROJECT_ID: l' Google Cloud ID progetto
  
  
    REPOSITORY: il nome del repository Artifact Registry
  
  
    IMAGE: il nome dell'immagine container del modello flessibile
  
  
    TAG: il tag per l'immagine del container del modello flessibile
  
  
    <pBASE_IMAGE: the base image to use. Specify one of the following:
    
      
        A predefined label, such as "GO". For more information, see the documentation
        for the 
        --flex-template-base-image flag.
      
      
        The full gcr.io path to a specific container version, in the following format:
        gcr.io/dataflow-templates-base/IMAGE:TAG.
      
    
  

  
    METADATA_FILE: il percorso locale di un file metafile. Per saperne di più,
    vedi Metadati
    del modello.
  

  
    GO_FILE_PATH: il percorso locale del file binario Go compilato per la pipeline
  
  
    GO_BINARY: il binario Go da eseguire. Per maggiori informazioni, vedi
    Variabili di ambiente.


Utilizza un'immagine personalizzata

Per eseguire un modello flessibile utilizzando un'immagine container personalizzata, esegui il comando seguente:

 Java 
gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image "CUSTOM_IMAGE" \
  --sdk-language "JAVA" \
  --metadata-file "METADATA_FILE"

 Python 
gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image "CUSTOM_IMAGE" \
  --sdk-language "PYTHON" \
  --metadata-file "METADATA_FILE"

 Vai 
gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image "CUSTOM_IMAGE" \
  --sdk-language "GO" \
  --metadata-file "METADATA_FILE"


Sostituisci quanto segue:


BUCKET_NAME: il nome di un bucket Cloud Storage in cui archiviare il file di specifica del modello.
TEMPLATE_FILE_NAME: il nome del file di specifica del modello. Esempio: my_template.json.
CUSTOM_IMAGE: la posizione del registro delle immagini dell'immagine personalizzata.
METADATA_FILE: il percorso locale di un
file metafile.


Dipendenze dei pacchetti per Python

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 Python che utilizza i modelli flessibili in
un ambiente che limita l'accesso a internet, devi pre-pacchettizzare le
dipendenze quando crei il modello.

Utilizza una delle seguenti opzioni per precompilare le dipendenze Python.


Utilizza un file requirements e pre-pacchettizza le dipendenze con il modello.
Struttura la pipeline come pacchetto e utilizza i pacchetti locali.
Utilizza un container personalizzato che preinstalla tutte le dipendenze.


Per istruzioni sulla gestione delle dipendenze delle pipeline in Java e Go,
consulta Gestire le dipendenze delle pipeline in Dataflow.

Utilizza un file requirements e pre-pacchettizza le dipendenze con il modello

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


Crea un file requirements.txt che elenca le dipendenze della pipeline.
COPY requirements.txt /template/
ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="/template/requirements.txt"

Installa le dipendenze nell'immagine del modello flessibile.
RUN pip install --no-cache-dir -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE

Scarica le dipendenze nella cache dei requisiti locali, che viene
trasferita ai worker Dataflow all'avvio del modello.
RUN pip download --no-cache-dir --dest /tmp/dataflow-requirements-cache -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE



Quando utilizzi questo approccio, le dipendenze del file requirements.txt vengono
installate sui worker Dataflow in fase di runtime. Un insight nella scheda dei consigli della console Google Cloud 
potrebbe segnalare questo comportamento. Per evitare di installare
le dipendenze in fase di runtime, utilizza un'immagine container personalizzata.

Di seguito è riportato un esempio di codice che utilizza un file requirements nel modello
flessibile.








  
  














  





  
    
  
  











  









  




  




  
# 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"]






























Strutturare la pipeline come pacchetto e utilizzare pacchetti locali

Quando utilizzi più file o moduli Python locali, struttura
la pipeline come pacchetto. La struttura del file potrebbe essere simile a quella
dell'esempio seguente:
main.py
pyproject.toml
setup.py
src/
  my_package/
    __init__.py
    my_custom_dofns_and_transforms.py
    my_pipeline_launcher.py
    other_utils_and_helpers.py

Posiziona il punto di ingresso di primo livello, ad esempio il file main.py,
nella directory principale. Inserisci il resto dei file in una cartella separata nella directory src, ad esempio my_package.
Aggiungi i file di configurazione del pacchetto alla directory principale con i dettagli e i requisiti del pacchetto.

pyproject.toml
[project]
name = "my_package"
version = "package_version"
dependencies = [
  # Add list of packages (and versions) that my_package depends on.
  # Example:
  "apache-beam[gcp]==2.54.0",
]

setup.py
  """An optional setuptools configuration stub for the pipeline package.

  Use pyproject.toml to define the package. Add this file only if you must
  use the --setup_file pipeline option or the
  FLEX_TEMPLATE_PYTHON_SETUP_FILE configuration option.
  """

  import setuptools
  setuptools.setup()


Per ulteriori informazioni su come configurare il pacchetto locale, consulta la sezione
Packaging Python Projects.
Quando importi moduli o file locali per la pipeline, utilizza il nome del pacchetto my_package come percorso di importazione.
from my_package import word_count_transform

Installa il pacchetto della pipeline nell'immagine del modello flessibile. Il Dockerfile del modello flessibile
potrebbe includere contenuti simili a quelli dell'esempio seguente:

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

# Copy pipeline, packages and requirements.
WORKDIR ${WORKDIR}
COPY main.py .
COPY pyproject.toml .
COPY setup.py .
COPY src src

# Install local package.
RUN pip install -e .



Quando utilizzi questo approccio, le dipendenze del file requirements.txt vengono
installate sui worker Dataflow in fase di runtime. Un insight nella scheda dei consigli della console Google Cloud 
potrebbe segnalare questo comportamento. Per evitare di installare le dipendenze in fase di runtime,
utilizza un'immagine container personalizzata.

Per un esempio che segue l'approccio consigliato, consulta l'esercitazione
Modello flessibile per una pipeline con dipendenze e un'immagine container personalizzata
su GitHub.

Utilizza un container personalizzato che preinstalli tutte le dipendenze

Per evitare l'installazione delle dipendenze in fase di runtime, utilizza container personalizzati.
Questa opzione è preferibile per le pipeline eseguite in ambienti senza accesso a internet.

Per utilizzare un container personalizzato:


Crea un'immagine container personalizzata che
preinstalli le dipendenze necessarie.
Preinstalla le stesse dipendenze nel Dockerfile del modello flessibile.

Per impedire l'installazione delle dipendenze in fase di runtime, non utilizzare le opzioni FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE o FLEX_TEMPLATE_PYTHON_SETUP_FILE nella configurazione del modello flessibile.

Un modello flessibile Dockerfile modificato potrebbe avere il seguente aspetto:
FROM gcr.io/dataflow-templates-base/python3-template-launcher-base
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/main.py"
COPY . /template
# If you use a requirements file, pre-install the requirements.txt.
RUN pip install --no-cache-dir -r /template/requirements.txt
# If you supply the pipeline in a package, pre-install the local package and its dependencies.
RUN pip install -e /template

Quando utilizzi questo approccio, esegui le seguenti operazioni:


crea l'immagine del modello flessibile
crea l'immagine container dell'SDK personalizzato
installare le stesse dipendenze in entrambe le immagini


In alternativa, per ridurre il numero di immagini da gestire, utilizza la tua immagine container personalizzata come immagine di base per il modello flessibile.
Se utilizzi l'SDK Apache Beam versione 2.49.0 o precedente,
aggiungi l'opzione pipeline --sdk_location=container nel launcher della pipeline.
Questa opzione indica alla pipeline di utilizzare l'SDK dal container personalizzato
anziché scaricarlo.
options = PipelineOptions(beam_args, save_main_session=True, streaming=True, sdk_location="container")

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 saperne di più, consulta
Utilizzare container personalizzati in Dataflow.


Utilizzare un registro Docker privato con i modelli flessibili

Puoi creare un'immagine del modello flessibile archiviata in un registro Docker privato se il registro privato utilizza HTTPS e ha un certificato valido.

Per utilizzare un'immagine di 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
segreto in uno dei seguenti formati:


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


Se utilizzi il secondo formato, poiché non specifica la versione,
Dataflow utilizza l'ultima versione.

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

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


  
    Parametro
    Descrizione
  
  
    
      image
    
    L'indirizzo del registro. Ad esempio:
      gcp.repository.example.com:9082/registry/example/image:latest.
    
  
  
    
      image-repository-username-secret-id
    
    L'ID secret di Secret Manager per il nome utente da autenticare
      nel registro privato. Ad esempio:
      projects/example-project/secrets/username-secret.
    
  
  
    
      image-repository-password-secret-id
    
    L'ID secret di Secret Manager per la password per l'autenticazione
      nel registro privato. Ad esempio:
      projects/example-project/secrets/password-secret/versions/latest.
    
  
  
    
      image-repository-cert-path
    
    L'URL Cloud Storage completo di un certificato autofirmato per il
      registro privato. Questo valore è obbligatorio solo se il registro utilizza un certificato autofirmato. Ad esempio:
      gs://example-bucket/self-signed.crt.
    
  


Ecco un esempio di comando Google Cloud CLI che crea un modello flessibile utilizzando un'immagine 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 un modello flessibile, devi sostituire i valori di esempio e
potresti dover specificare opzioni diverse o aggiuntive.

Passaggi successivi


Scopri come eseguire un modello flessibile.
Crea ed esegui un modello flessibile di esempio.
Per saperne di più sui modelli classici, sui modelli flessibili e sui relativi scenari di utilizzo, consulta Modelli Dataflow.
Per informazioni sulla risoluzione dei problemi relativi ai modelli flessibili, consulta Risolvere i problemi di timeout dei modelli flessibili.


Per ulteriori architetture di riferimento, diagrammi e best practice, esplora il Cloud Architecture Center.

Parametro	Descrizione
`image`	L'indirizzo del registro. Ad esempio: `gcp.repository.example.com:9082/registry/example/image:latest`.
`image-repository-username-secret-id`	L'ID secret di Secret Manager per il nome utente da autenticare nel registro privato. Ad esempio: `projects/example-project/secrets/username-secret`.
`image-repository-password-secret-id`	L'ID secret di Secret Manager per la password per l'autenticazione nel registro privato. Ad esempio: `projects/example-project/secrets/password-secret/versions/latest`.
`image-repository-cert-path`	L'URL Cloud Storage completo di un certificato autofirmato per il registro privato. Questo valore è obbligatorio solo se il registro utilizza un certificato autofirmato. Ad esempio: `gs://example-bucket/self-signed.crt`.

Utilizzare i modelli flessibili per pacchettizzare una pipeline Dataflow per il deployment Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Panoramica

Autorizzazioni obbligatorie

Metadati del modello

Parametri dei metadati

File di metadati di esempio

Java

Python

Variabili di ambiente

Java

Python

Vai

Immagini dei modelli flessibili

Immagini container personalizzate

Java

Python

Vai

Crea un modello flessibile

Utilizzare un'immagine di base fornita da Google

Java

Python

Vai

Utilizza un'immagine personalizzata

Java

Python

Vai

Dipendenze dei pacchetti per Python

Utilizza un file requirements e pre-pacchettizza le dipendenze con il modello

Strutturare la pipeline come pacchetto e utilizzare pacchetti locali

pyproject.toml

setup.py

Dockerfile

Utilizza un container personalizzato che preinstalli tutte le dipendenze

Utilizzare un registro Docker privato con i modelli flessibili

Passaggi successivi

Utilizzare i modelli flessibili per pacchettizzare una pipeline Dataflow per il deployment