Requisiti
Un'immagine del container personalizzato per Dataflow deve soddisfare i seguenti requisiti:
- L'SDK Apache Beam e le dipendenze necessarie sono installati. I nostri suggerimenti iniziando con un'immagine SDK Apache Beam predefinita. Per ulteriori informazioni, vedi Seleziona un'immagine di base in questo documento.
- Lo script
/opt/apache/beam/boot
deve essere eseguito come ultimo passaggio durante l'avvio del container. Questo script inizializza l'ambiente di lavoro e avvia il processo di lavoro SDK. Questo script è il valoreENTRYPOINT
predefinito nelle immagini dell'SDK Apache Beam. Tuttavia, se utilizzi un'immagine di base diversa o se sostituisci laENTRYPOINT
per impostazione predefinita, devi eseguire lo script in modo esplicito. Per ulteriori informazioni, consulta Modificare il punto di contatto del contenitore in questo documento. - L'immagine container deve supportare l'architettura delle VM worker per del job Dataflow. Se prevedi di utilizzare il container personalizzato su ARM per le VM, consigliamo di creare un'immagine con più architetture. Per ulteriori informazioni, consulta Creare un'immagine contenitore multi-architettura.
Prima di iniziare
Verifica che la versione dell'SDK Apache Beam installato supporti Runner v2 e la versione in lingua. Per maggiori informazioni le informazioni, vedi Installa l'SDK Apache Beam.
Per testare l'immagine container in locale, devi aver installato Docker. Per ulteriori informazioni, consulta la pagina Ottenere Docker.
Crea un repository Artifact Registry. Specifica il formato dell'immagine Docker. Devi avere almeno Accesso in Writer ad Artifact Registry nel repository.
Per creare un nuovo repository, esegui Comando
gcloud artifacts repositories create
:gcloud artifacts repositories create REPOSITORY \ --repository-format=docker \ --location=REGION \ --async
Sostituisci quanto segue:
- REPOSITORY: un nome per il repository. I nomi dei repository devono essere univoci per ogni località di un progetto.
- REGION: la regione da del tuo job Dataflow. Seleziona una regione Dataflow vicina a quella in cui esegui i comandi. Il valore deve essere un nome di regione valido. Per ulteriori informazioni su regioni e località, consulta Località di Dataflow.
In questo esempio viene utilizzato il flag
--async
. Il comando viene restituito immediatamente, senza attendere il completamento dell'operazione.Per configurare Docker per autenticare le richieste per Artifact Registry, esegui il Comando
gcloud auth configure-docker
:gcloud auth configure-docker REGION-docker.pkg.dev
Il comando aggiorna la configurazione Docker. Ora puoi connetterti con Artifact Registry nel tuo progetto Google Cloud per eseguire il push delle immagini.
Seleziona un'immagine di base
Ti consigliamo di iniziare con un'immagine SDK Apache Beam come container di base. dell'immagine. Queste immagini vengono rilasciate nell'ambito delle release di Apache Beam su Docker Hub.
Utilizzare un'immagine di base Apache Beam
Per utilizzare un'immagine dell'SDK Apache Beam come immagine di base, specifica l'immagine del contenitore nell'istruzione FROM
e poi aggiungi le tue personalizzazioni.
Java
Questo esempio utilizza Java 8 con la versione 2.60.0 dell'SDK Apache Beam.
FROM apache/beam_java8_sdk:2.60.0
# Make your customizations here, for example:
ENV FOO=/bar
COPY path/to/myfile ./
La versione runtime del container personalizzato deve corrispondere al runtime di cui
per avviare la pipeline. Ad esempio, se avvii la pipeline da un ambiente Java 11 locale, la riga FROM
deve specificare un ambiente Java 11:apache/beam_java11_sdk:...
.
Python
Questo esempio utilizza Python 3.10 con l'SDK Apache Beam versione 2.60.0.
FROM apache/beam_python3.10_sdk:2.60.0
# Make your customizations here, for example:
ENV FOO=/bar
COPY path/to/myfile ./
La versione di runtime del contenitore personalizzato deve corrispondere a quella che utilizzerai per avviare la pipeline. Ad esempio, se avvii la pipeline da una
nell'ambiente Python 3.10 locale, la riga FROM
deve specificare un ambiente Python 3.10:
apache/beam_python3.10_sdk:...
.
Vai
In questo esempio viene utilizzato Go con l'SDK Apache Beam versione 2.60.0.
FROM apache/beam_go_sdk:2.60.0
# Make your customizations here, for example:
ENV FOO=/bar
COPY path/to/myfile ./
Utilizza un'immagine di base personalizzata
Se vuoi utilizzare un'immagine di base diversa o devi modificare qualche aspetto delle immagini Apache Beam predefinite (ad esempio la versione del sistema operativo o le patch), utilizza un processo di costruzione a più fasi. Copia gli artefatti necessari da un'immagine di base Apache Beam predefinita.
Imposta ENTRYPOINT
in modo da eseguire lo script /opt/apache/beam/boot
, che inizializza l'ambiente di lavoro e avvia il processo di lavoro dell'SDK. Se
non imposti questo punto di contatto, i worker Dataflow non si avviano
correttamente.
L'esempio seguente mostra un Dockerfile che copia i file dall'SDK Apache Beam:
Java
FROM openjdk:8
# Copy files from official SDK image, including script/dependencies.
COPY --from=apache/beam_java8_sdk:2.60.0 /opt/apache/beam /opt/apache/beam
# Set the entrypoint to Apache Beam SDK launcher.
ENTRYPOINT ["/opt/apache/beam/boot"]
Python
FROM python:3.10-slim
# Install SDK.
RUN pip install --no-cache-dir apache-beam[gcp]==2.60.0
# Verify that the image does not have conflicting dependencies.
RUN pip check
# Copy files from official SDK image, including script/dependencies.
COPY --from=apache/beam_python3.10_sdk:2.60.0 /opt/apache/beam /opt/apache/beam
# Set the entrypoint to Apache Beam SDK launcher.
ENTRYPOINT ["/opt/apache/beam/boot"]
Questo esempio presuppone le dipendenze necessarie (in questo caso Python 3.10 e pip
)
sono state installate sull'immagine di base esistente. Installazione di Apache Beam
L'SDK nell'immagine garantisce che quest'ultima abbia le dipendenze SDK necessarie.
e riduce i tempi di avvio del worker.
Importante: la versione dell'SDK specificata in
le istruzioni RUN
e COPY
devono corrispondere alla versione utilizzata per avviare la pipeline.
Vai
FROM golang:latest
# Copy files from official SDK image, including script/dependencies.
COPY --from=apache/beam_go_sdk:2.60.0 /opt/apache/beam /opt/apache/beam
# Set the entrypoint to Apache Beam SDK launcher.
ENTRYPOINT ["/opt/apache/beam/boot"]
Modifica l'entry point del contenitore
Se il container esegue uno script personalizzato durante l'avvio, lo script deve
terminano con l'esecuzione di /opt/apache/beam/boot
. Argomenti passati da
Il Dataflow durante l'avvio del container deve essere passato al valore predefinito
script di avvio. L'esempio seguente mostra uno script di avvio personalizzato che chiama il metodo
script di avvio predefinito:
#!/bin/bash
echo "This is my custom script"
# ...
# Pass command arguments to the default boot script.
/opt/apache/beam/boot "$@"
Nel Dockerfile, imposta ENTRYPOINT
per chiamare il tuo script:
Java
FROM apache/beam_java8_sdk:2.60.0
COPY script.sh path/to/my/script.sh
ENTRYPOINT [ "path/to/my/script.sh" ]
Python
FROM apache/beam_python3.10_sdk:2.60.0
COPY script.sh path/to/my/script.sh
ENTRYPOINT [ "path/to/my/script.sh" ]
Vai
FROM apache/beam_go_sdk:2.60.0
COPY script.sh path/to/my/script.sh
ENTRYPOINT [ "path/to/my/script.sh" ]
Crea ed esegui il push dell'immagine
Puoi usare Cloud Build o Docker per creare la tua immagine container ed eseguirne il push in un repository Artifact Registry.
Cloud Build
Per creare il file ed eseguirne il push nel repository Artifact Registry, esegui
Comando gcloud builds submit
:
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/FILE_NAME:TAG .
Docker
docker build . --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/FILE_NAME:TAG
docker push REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/FILE_NAME:TAG
Sostituisci quanto segue:
REGION
: il valore regione in cui eseguire il deployment del job Dataflow. Il valore dell'attributoREGION
deve essere un nome di regione valido.PROJECT_ID
: il nome del progetto o il nome utente.REPOSITORY
: il nome del repository di immagini.FILE_NAME
: il nome del tuo Dockerfile.TAG
: il tag immagine. Specifica sempre un tag o un SHA del contenitore con versione. Non utilizzare il tag:latest
o un tag modificabile.
Preinstalla le dipendenze Python
Questa sezione riguarda le pipeline Python.
Quando avvii un job Dataflow Python, puoi specificare dipendenze aggiuntive utilizzando l'opzione --requirements_file
o --extra_packages
in fase di esecuzione. Per ulteriori informazioni, vedi
Gestione delle dipendenze della pipeline Python.
Dipendenze aggiuntive sono installate in ogni worker Dataflow
containerizzato. All'avvio del job e durante la scalabilità automatica, l'installazione delle dipendenze spesso comporta un elevato utilizzo della CPU e un lungo periodo di riscaldamento su tutti i worker Dataflow appena avviati.
Per evitare installazioni ripetitive delle dipendenze, puoi pre-creare un file Python personalizzato Immagine container SDK con le dipendenze preinstallate. Puoi eseguire questo passaggio in fase di compilazione utilizzando un Dockerfile o in fase di esecuzione quando invii il job.
I worker creano un nuovo ambiente Python virtuale all'avvio del container. Per questo motivo, installa le dipendenze nel file Python (globale) predefinito anziché creare un ambiente virtuale. Se attivi un ambiente virtuale nell'immagine del contenitore, questo ambiente potrebbe non essere attivato all'avvio del job. Per ulteriori informazioni, vedi Problemi comuni.
Preinstallazione con un Dockerfile
Per aggiungere ulteriori dipendenze direttamente al tuo container personalizzato Python, utilizza la classe seguenti comandi:
FROM apache/beam_python3.10_sdk:2.60.0
COPY requirements.txt .
# Pre-install Python dependencies. For reproducibile builds,
# supply all of the dependencies and their versions in a requirements.txt file.
RUN pip install -r requirements.txt
# You can also install individual dependencies.
RUN pip install lxml
# Pre-install other dependencies.
RUN apt-get update \
&& apt-get dist-upgrade \
&& apt-get install -y --no-install-recommends ffmpeg
Invia il job con le opzioni della pipeline --sdk_container_image
e --sdk_location
.
L'opzione --sdk_location
impedisce il download dell'SDK all'avvio del job.
L'SDK viene recuperato direttamente dall'immagine del contenitore.
L'esempio seguente esegue la
wordcount
pipeline di esempio:
python -m apache_beam.examples.wordcount \
--input=INPUT_FILE \
--output=OUTPUT_FILE \
--project=PROJECT_ID \
--region=REGION \
--temp_location=TEMP_LOCATION \
--runner=DataflowRunner \
--experiments=use_runner_v2 \
--sdk_container_image=IMAGE_URI
--sdk_location=container
Sostituisci quanto segue:
- INPUT_FILE: un file di input per la pipeline
- OUTPUT_FILE: un percorso in cui scrivere l'output
- PROJECT_ID: l'ID del progetto Google Cloud
- REGION: il valore region di cui eseguire il deployment il tuo job Dataflow
- TEMP_LOCATION: il percorso di Cloud Storage per la gestione intermedia dei file temporanei dei job di Dataflow
- IMAGE_URI: l'URI dell'immagine del container personalizzato
Crea preventivamente un'immagine container quando invii il job
La pre-creazione di un'immagine container ti consente di preinstallare le dipendenze della pipeline prima dell'avvio del job. Non è necessario creare un'immagine container personalizzata.
Per predefinire un container con dipendenze Python aggiuntive quando invii un job, utilizza le seguenti opzioni di pipeline:
--prebuild_sdk_container_engine=[cloud_build | local_docker]
. Quando questo flag è impostato, Apache Beam genera un contenitore personalizzato e installa tutte le dipendenze specificate dalle opzioni--requirements_file
e--extra_packages
. Questo flag supporta i seguenti valori:cloud_build
. Utilizza Cloud Build per creare il container. L'API Cloud Build deve essere attivata nel tuo progetto.local_docker
. Utilizza la tua installazione Docker locale per creare il container.
--docker_registry_push_url=IMAGE_PATH
. SostituisciIMAGE_PATH
con una cartella Artifact Registry.--sdk_location=container
. Questa opzione impedisce ai worker di scaricare l'SDK all'avvio del job. L'SDK viene recuperato direttamente l'immagine container.
L'esempio seguente utilizza Cloud Build per precompilare l'immagine:
python -m apache_beam.examples.wordcount \
--input=INPUT_FILE \
--output=OUTPUT_FILE \
--project=PROJECT_ID \
--region=REGION \
--temp_location=TEMP_LOCATION \
--runner=DataflowRunner \
--disk_size_gb=DISK_SIZE_GB \
--experiments=use_runner_v2 \
--requirements_file=./requirements.txt \
--prebuild_sdk_container_engine=cloud_build \
--docker_registry_push_url=IMAGE_PATH \
--sdk_location=container
La funzionalità di pre-build richiede l'SDK Apache Beam per Python versione 2.25.0 o successiva.
Il flusso di lavoro di pre-creazione di un'immagine container dell'SDK utilizza l'immagine trasmessa utilizzando
Opzione pipeline --sdk_container_image
come immagine di base. Se l'opzione non è
predefinita, per impostazione predefinita viene utilizzata un'immagine Apache Beam come immagine di base.
Puoi riutilizzare un'immagine del contenitore dell'SDK Python predefinita in un altro job con le stesse dipendenze e la stessa versione dell'SDK.
Per riutilizzare l'immagine, passa l'URL dell'immagine container predefinita all'altro job utilizzando l'opzione della pipeline --sdk_container_image
. Rimuovi la dipendenza
opzioni --requirements_file
, --extra_packages
e --setup_file
.
Se non prevedi di riutilizzare l'immagine, eliminala al termine del job. Puoi eliminare l'immagine con la CLI gcloud o nelle pagine di Artifact Registry nella console Google Cloud.
Se l'immagine è archiviata in Artifact Registry, utilizza il comando
artifacts docker images delete
:
gcloud artifacts docker images delete IMAGE --delete-tags
Problemi comuni
Se il tuo job ha dipendenze Python aggiuntive da un mirroring PyPi privato e non è possibile eseguire il pull da un job Cloud Build remoto, prova a utilizzare l'opzione Docker locale oppure prova a creare il tuo container utilizzando un Dockerfile.
Se il job Cloud Build ha esito negativo con
docker exit code 137
, il job di build ha esaurito la memoria, potenzialmente a causa delle dimensioni delle dipendenze installate. Utilizza un tipo di macchina worker Cloud Build più grande passando--cloud_build_machine_type=machine_type
, dove machine_type è una delle seguenti opzioni:n1-highcpu-8
n1-highcpu-32
e2-highcpu-8
e2-highcpu-32
Per impostazione predefinita, Cloud Build utilizza il tipo di macchina
e2-medium
.In Apache Beam 2.44.0 e versioni successive, i worker creano un ambiente virtuale quando avviando un container personalizzato. Se il container crea la propria per installare le dipendenze, queste vengono ignorate. Questo può causare errori quali:
ModuleNotFoundError: No module named '<dependency name>'
Per evitare questo problema, installa le dipendenze nel file Python (globale) predefinito completamente gestito di Google Cloud. Come soluzione alternativa, disattiva questo comportamento in Beam 2.48.0 e in un secondo momento impostando la seguente variabile di ambiente nell'immagine container:
ENV RUN_PYTHON_SDK_IN_DEFAULT_ENVIRONMENT=1
Passaggi successivi
- Per ulteriori informazioni sulla scrittura di Dockerfile, consulta Best practice per la scrittura di Dockerfile.
- Scopri come eseguire un job Dataflow in un contenitore personalizzato.