Crea immagini container personalizzate per Dataflow

Questo documento descrive come creare un'immagine container personalizzata per i job Dataflow.

Requisiti

Un'immagine del container personalizzato per Dataflow deve soddisfare i seguenti requisiti:

  • L'SDK Apache Beam e le dipendenze necessarie siano installati. I nostri suggerimenti iniziando con un'immagine SDK Apache Beam predefinita. Per ulteriori informazioni, consulta Selezionare un'immagine di base in questo documento.
  • Lo script /opt/apache/beam/boot deve essere eseguito come ultimo passaggio durante il container avvio automatico. Questo script inizializza l'ambiente worker e avvia l'SDK e il processo worker. Questo script è il valore ENTRYPOINT predefinito nelle immagini dell'SDK Apache Beam. Tuttavia, se utilizzi un'immagine di base diversa o se sostituisci il valore predefinito ENTRYPOINT, devi eseguire lo script esplicitamente. Per maggiori informazioni informazioni, consulta Modificare il punto di ingresso container in documento.
  • L'immagine del contenitore deve supportare l'architettura delle VM worker per il 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

  1. Verifica che la versione dell'SDK Apache Beam installato supporti Runner v2 e la versione in lingua. Per ulteriori informazioni, consulta Installare l'SDK Apache Beam.

  2. Per testare l'immagine container localmente, devi avere installato Docker. Per ulteriori informazioni, consulta la pagina Ottenere Docker.

  3. Crea un repository Artifact Registry. Specifica il formato dell'immagine Docker. Devi disporre almeno del ruolo di autore di Artifact Registry per il 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.

  4. 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 come parte delle release di Apache Beam Docker Hub.

usa 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

In questo esempio viene usato Java 8 con l'SDK Apache Beam versione 2.59.0.

FROM apache/beam_java8_sdk:2.59.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 la versione 2.59.0 dell'SDK Apache Beam.

FROM apache/beam_python3.10_sdk:2.59.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 un 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.59.0.

FROM apache/beam_go_sdk:2.59.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 immagini Apache Beam predefinite (come la versione o le patch del sistema operativo), utilizza creazione multifase e il processo di sviluppo. 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 impostare questo punto di ingresso, i worker Dataflow non avviano correttamente.

L'esempio seguente mostra un Dockerfile che copia i file SDK Apache Beam:

Java

FROM openjdk:8

# Copy files from official SDK image, including script/dependencies.
COPY --from=apache/beam_java8_sdk:2.59.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.59.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.59.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. L'installazione dell'SDK Apache Beam nell'immagine garantisce che l'immagine abbia le dipendenze SDK necessarie e riduce il tempo 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.59.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 lo 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.59.0

COPY script.sh path/to/my/script.sh
ENTRYPOINT [ "path/to/my/script.sh" ]

Python

FROM apache/beam_python3.10_sdk:2.59.0

COPY script.sh path/to/my/script.sh
ENTRYPOINT [ "path/to/my/script.sh" ]

Vai

FROM apache/beam_go_sdk:2.59.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 compilare il file ed eseguirne il push nel repository Artifact Registry, esegui il 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: la regione in cui eseguire il deployment del job Dataflow. Il valore dell'attributo REGION 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 Dockerfile.
  • TAG: il tag immagine. Specifica sempre un controllo delle versioni l'SHA o il tag del contenitore. Non utilizzare il tag :latest o un tag mutabile.

Preinstalla le dipendenze Python

Questa sezione riguarda le pipeline Python.

Quando avvii un job Dataflow in Python, puoi specificare ulteriori le dipendenze utilizzando l'opzione --requirements_file o --extra_packages in runtime. Per ulteriori informazioni, vedi Gestione delle dipendenze della pipeline Python. Dipendenze aggiuntive sono installate in ogni worker Dataflow containerizzato. Quando il job viene avviato per la prima volta e durante la scalabilità automatica, la dipendenza l'installazione porta spesso a un elevato utilizzo della CPU e a un lungo periodo di riscaldamento worker Dataflow appena avviati.

Per evitare installazioni ripetitive delle dipendenze, puoi pre-creare un'immagine container dell'SDK Python personalizzata 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 nell'ambiente Python predefinito (globale) 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, consulta la sezione Problemi comuni.

Preinstallazione con un Dockerfile

Per aggiungere dipendenze aggiuntive direttamente al container personalizzato Python, utilizza i seguenti comandi:

FROM apache/beam_python3.10_sdk:2.59.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 al momento dell'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 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 contenitore 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 precreare un container con dipendenze Python aggiuntive quando invii un utilizza le seguenti opzioni di pipeline:

  • --prebuild_sdk_container_engine=[cloud_build | local_docker]. Quando questo flag è impostato, Apache Beam genera un container personalizzato e installa tutti di dipendenze specificate da --requirements_file e --extra_packages le opzioni di CPU e memoria disponibili. 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 l'installazione locale di Docker per creare il container.

  • --docker_registry_push_url=IMAGE_PATH. Sostituisci IMAGE_PATH con una cartella Artifact Registry.

  • --sdk_location=container. Questa opzione impedisce ai worker di scaricare l'SDK al momento del lancio del job. L'SDK viene invece recuperato direttamente dall'immagine del contenitore.

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 dell'immagine del container dell'SDK utilizza l'immagine passata utilizzando l'opzione della 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 container dell'SDK Python predefinita in un altro job con le stesse dipendenze e 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 le opzioni di dipendenza --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 mirror PyPi privato e non può essere recuperato da un job Cloud Build remoto, prova a utilizzare l'opzione Docker locale o a creare il container utilizzando un Dockerfile.

  • Se il job Cloud Build non riesce con docker exit code 137, significa che il job di compilazione ha esaurito la memoria, possibly due to the size of the dependencies being installed. Usa Cloud Build più grande del tipo di macchina worker 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 avviano un container personalizzato. Se il container crea la propria istanza per installare le dipendenze, queste vengono ignorate. Questo comportamento può causare errori come i seguenti:

    ModuleNotFoundError: No module named '<dependency name>'

    Per evitare questo problema, installa le dipendenze nell'ambiente Python predefinito (globale). Come soluzione alternativa, disattiva questo comportamento in Beam 2.48.0 e versioni successive impostando la seguente variabile di ambiente nell'immagine del contenitore:

    ENV RUN_PYTHON_SDK_IN_DEFAULT_ENVIRONMENT=1

Passaggi successivi