Halaman ini diterjemahkan oleh Cloud Translation API.

Mem-build image container kustom untuk Dataflow

Dokumen ini menjelaskan cara membuat image container kustom untuk tugas Dataflow.

Persyaratan

Image container kustom untuk Dataflow harus memenuhi persyaratan berikut:

Apache Beam SDK dan dependensi yang diperlukan telah diinstal. Sebaiknya mulai dengan image Apache Beam SDK default. Untuk informasi selengkapnya, lihat Memilih image dasar dalam dokumen ini.
Skrip /opt/apache/beam/boot harus berjalan sebagai langkah terakhir selama startup penampung. Skrip ini menginisialisasi lingkungan pekerja dan memulai proses pekerja SDK. Skrip ini adalah ENTRYPOINT default dalam image Apache Beam SDK. Namun, jika Anda menggunakan image dasar yang berbeda, atau jika Anda mengganti ENTRYPOINT default, Anda harus menjalankan skrip secara eksplisit. Untuk informasi selengkapnya, lihat Mengubah titik entri penampung dalam dokumen ini.
Image container Anda harus mendukung arsitektur VM pekerja untuk tugas Dataflow Anda. Jika Anda berencana menggunakan penampung kustom di VM ARM, sebaiknya build image multi-arsitektur. Untuk mengetahui informasi selengkapnya, lihat Mem-build image container multi-arsitektur.

Sebelum memulai

Pastikan versi Apache Beam SDK yang diinstal mendukung Runner v2 dan versi bahasa Anda. Untuk informasi selengkapnya, lihat Menginstal Apache Beam SDK.
Untuk menguji image container secara lokal, Anda harus menginstal Docker. Untuk mengetahui informasi selengkapnya, lihat Mendapatkan Docker.
Buat repositori Artifact Registry. Tentukan format image Docker. Anda harus memiliki setidaknya akses Artifact Registry Writer ke repositori.

Untuk membuat repositori baru, jalankan perintah gcloud artifacts repositories create:
```
gcloud artifacts repositories create REPOSITORY \
  --repository-format=docker \
  --location=REGION \
  --async
```
Ganti kode berikut:
- REPOSITORY: nama untuk repositori Anda. Nama repositori harus unik untuk setiap lokasi dalam project.
- REGION: region tempat men-deploy tugas Dataflow Anda. Pilih region Dataflow yang dekat dengan tempat Anda menjalankan perintah. Nilainya harus berupa nama wilayah yang valid. Untuk mengetahui informasi selengkapnya tentang region dan lokasi, lihat Lokasi Dataflow.
Contoh ini menggunakan flag --async. Perintah akan segera ditampilkan, tanpa menunggu operasi selesai.
Untuk mengonfigurasi Docker guna mengautentikasi permintaan untuk Artifact Registry, jalankan perintah gcloud auth configure-docker:
```
gcloud auth configure-docker REGION-docker.pkg.dev
```
Perintah ini memperbarui konfigurasi Docker Anda. Sekarang Anda dapat terhubung dengan Artifact Registry di project Google Cloud untuk mengirim image.

Memilih image dasar

Sebaiknya mulailah dengan image Apache Beam SDK sebagai image penampung dasar. Image ini dirilis sebagai bagian dari rilis Apache Beam ke Docker Hub.

Menggunakan image dasar Apache Beam

Untuk menggunakan image Apache Beam SDK sebagai image dasar, tentukan image penampung dalam petunjuk FROM, lalu tambahkan penyesuaian Anda sendiri.

Java

Contoh ini menggunakan Java 8 dengan Apache Beam SDK versi 2.61.0.

FROM apache/beam_java8_sdk:2.61.0

# Make your customizations here, for example:
ENV FOO=/bar
COPY path/to/myfile ./

Versi runtime penampung kustom harus cocok dengan runtime yang akan Anda gunakan untuk memulai pipeline. Misalnya, jika Anda akan memulai pipeline dari lingkungan Java 11 lokal, baris FROM harus menentukan lingkungan Java 11: apache/beam_java11_sdk:....

Python

Contoh ini menggunakan Python 3.10 dengan Apache Beam SDK versi 2.61.0.

FROM apache/beam_python3.10_sdk:2.61.0

# Make your customizations here, for example:
ENV FOO=/bar
COPY path/to/myfile ./

Versi runtime penampung kustom harus cocok dengan runtime yang akan Anda gunakan untuk memulai pipeline. Misalnya, jika Anda akan memulai pipeline dari lingkungan Python 3.10 lokal, baris FROM harus menentukan lingkungan Python 3.10: apache/beam_python3.10_sdk:....

Go

Contoh ini menggunakan Go dengan Apache Beam SDK versi 2.61.0.

FROM apache/beam_go_sdk:2.61.0

# Make your customizations here, for example:
ENV FOO=/bar
COPY path/to/myfile ./

Menggunakan image dasar kustom

Jika Anda ingin menggunakan image dasar yang berbeda, atau perlu mengubah beberapa aspek image Apache Beam default (seperti versi OS atau patch), gunakan proses build multi-tahap. Salin artefak yang diperlukan dari image dasar Apache Beam default.

Tetapkan ENTRYPOINT untuk menjalankan skrip /opt/apache/beam/boot, yang melakukan inisialisasi lingkungan pekerja dan memulai proses pekerja SDK. Jika Anda tidak menetapkan titik entri ini, pekerja Dataflow tidak akan dimulai dengan benar.

Contoh berikut menunjukkan Dockerfile yang menyalin file dari Apache Beam SDK:

Java

FROM openjdk:8

# Copy files from official SDK image, including script/dependencies.
COPY --from=apache/beam_java8_sdk:2.61.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.61.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.61.0 /opt/apache/beam /opt/apache/beam

# Set the entrypoint to Apache Beam SDK launcher.
ENTRYPOINT ["/opt/apache/beam/boot"]

Contoh ini mengasumsikan bahwa dependensi yang diperlukan (dalam hal ini, Python 3.10 dan pip) telah diinstal di image dasar yang ada. Menginstal Apache Beam SDK ke dalam image memastikan bahwa image memiliki dependensi SDK yang diperlukan dan mengurangi waktu startup pekerja.

Penting: Versi SDK yang ditentukan dalam petunjuk RUN dan COPY harus cocok dengan versi yang digunakan untuk meluncurkan pipeline.

Go

FROM golang:latest

# Copy files from official SDK image, including script/dependencies.
COPY --from=apache/beam_go_sdk:2.61.0 /opt/apache/beam /opt/apache/beam

# Set the entrypoint to Apache Beam SDK launcher.
ENTRYPOINT ["/opt/apache/beam/boot"]

Mengubah titik entri penampung

Jika container Anda menjalankan skrip kustom selama startup container, skrip harus berakhir dengan menjalankan /opt/apache/beam/boot. Argumen yang diteruskan oleh Dataflow selama startup penampung harus diteruskan ke skrip booting default. Contoh berikut menunjukkan skrip startup kustom yang memanggil skrip booting default:

#!/bin/bash

echo "This is my custom script"
# ...

# Pass command arguments to the default boot script.
/opt/apache/beam/boot "$@"

Di Dockerfile, tetapkan ENTRYPOINT untuk memanggil skrip Anda:

Java

FROM apache/beam_java8_sdk:2.61.0

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

Python

FROM apache/beam_python3.10_sdk:2.61.0

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

Go

FROM apache/beam_go_sdk:2.61.0

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

Mem-build dan mengirim image

Anda dapat menggunakan Cloud Build atau Docker untuk mem-build image container dan mengirimkannya ke repositori Artifact Registry.

Cloud Build

Untuk mem-build file dan mendorongnya ke repositori Artifact Registry, jalankan perintah 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

Ganti kode berikut:

REGION: region tempat men-deploy tugas Dataflow Anda. Nilai variabel REGION harus berupa nama wilayah yang valid.
PROJECT_ID: nama project atau nama pengguna.
REPOSITORY: nama repositori image.
FILE_NAME: nama Dockerfile Anda.
TAG: tag gambar. Selalu tentukan tag atau SHA penampung berversi. Jangan gunakan tag :latest atau tag yang dapat diubah.

Menginstal dependensi Python terlebih dahulu

Bagian ini berlaku untuk pipeline Python.

Saat meluncurkan tugas Dataflow Python, Anda dapat menentukan dependensi tambahan menggunakan opsi --requirements_file atau --extra_packages saat runtime. Untuk mengetahui informasi selengkapnya, lihat Mengelola Dependensi Pipeline Python. Dependensi tambahan diinstal di setiap penampung pekerja Dataflow. Saat tugas pertama kali dimulai dan selama penskalaan otomatis, penginstalan dependensi sering kali menyebabkan penggunaan CPU yang tinggi dan periode pemanasan yang lama di semua pekerja Dataflow yang baru dimulai.

Untuk menghindari penginstalan dependensi berulang, Anda dapat mem-build sebelumnya image container SDK Python kustom dengan dependensi yang sudah diinstal sebelumnya. Anda dapat melakukan langkah ini saat build dengan menggunakan Dockerfile, atau saat runtime saat Anda mengirimkan tugas.

Pekerja membuat lingkungan virtual Python baru saat memulai penampung. Oleh karena itu, instal dependensi ke lingkungan Python (global) default, bukan membuat lingkungan virtual. Jika Anda mengaktifkan lingkungan virtual di image container, lingkungan ini mungkin tidak diaktifkan saat tugas dimulai. Untuk mengetahui informasi selengkapnya, lihat Masalah umum.

Pra-penginstalan menggunakan Dockerfile

Untuk menambahkan dependensi tambahan langsung ke penampung kustom Python, gunakan perintah berikut:

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

Kirim tugas Anda dengan opsi pipeline --sdk_container_image dan --sdk_location. Opsi --sdk_location mencegah SDK didownload saat tugas Anda diluncurkan. SDK diambil langsung dari image container.

Contoh berikut menjalankan contoh pipeline wordcount:

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

Ganti kode berikut:

INPUT_FILE: file input untuk pipeline
OUTPUT_FILE: jalur untuk menulis output
PROJECT_ID: project ID Google Cloud
REGION: region tempat deployment tugas Dataflow Anda
TEMP_LOCATION: jalur Cloud Storage untuk Dataflow guna melakukan staging file tugas sementara
IMAGE_URI: URI image container kustom

Mem-build image container sebelumnya saat mengirimkan tugas

Mem-build image container sebelumnya memungkinkan Anda menginstal dependensi pipeline terlebih dahulu sebelum memulai tugas. Anda tidak perlu mem-build image container kustom.

Untuk mem-build container terlebih dahulu dengan dependensi Python tambahan saat Anda mengirimkan tugas, gunakan opsi pipeline berikut:

--prebuild_sdk_container_engine=[cloud_build | local_docker]. Jika tanda ini ditetapkan, Apache Beam akan membuat penampung kustom dan menginstal semua dependensi yang ditentukan oleh opsi --requirements_file dan --extra_packages. Flag ini mendukung nilai berikut:
- cloud_build. Gunakan Cloud Build untuk mem-build container. Cloud Build API harus diaktifkan di project Anda.
- local_docker. Gunakan penginstalan Docker lokal untuk mem-build container.
--docker_registry_push_url=IMAGE_PATH. Ganti IMAGE_PATH dengan folder Artifact Registry.
--sdk_location=container. Opsi ini mencegah pekerja mendownload SDK saat tugas Anda diluncurkan. Sebagai gantinya, SDK diambil langsung dari image penampung.

Contoh berikut menggunakan Cloud Build untuk mem-build image terlebih dahulu:

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

Fitur pra-build memerlukan Apache Beam SDK untuk Python versi 2.25.0 atau yang lebih baru.

Alur kerja pra-pembuatan image container SDK menggunakan image yang diteruskan menggunakan opsi pipeline --sdk_container_image sebagai image dasar. Jika opsi ini tidak ditetapkan, secara default image Apache Beam akan digunakan sebagai image dasar.

Anda dapat menggunakan kembali image container Python SDK bawaan dalam tugas lain dengan dependensi dan versi SDK yang sama. Untuk menggunakan kembali image, teruskan URL image container bawaan ke tugas lain menggunakan opsi pipeline --sdk_container_image. Hapus opsi dependensi --requirements_file, --extra_packages, dan --setup_file.

Jika Anda tidak berencana menggunakan kembali gambar, hapus gambar tersebut setelah tugas selesai. Anda dapat menghapus image dengan gcloud CLI atau di halaman Artifact Registry di konsol Google Cloud.

Jika image disimpan di Artifact Registry, gunakan perintah artifacts docker images delete:

   gcloud artifacts docker images delete IMAGE --delete-tags

Masalah umum

Jika tugas Anda memiliki dependensi Python tambahan dari mirror PyPi pribadi dan tidak dapat diambil oleh tugas Cloud Build jarak jauh, coba gunakan opsi docker lokal atau coba build container menggunakan Dockerfile.
Jika tugas Cloud Build gagal dengan docker exit code 137, tugas build kehabisan memori, yang mungkin disebabkan oleh ukuran dependensi yang diinstal. Gunakan jenis mesin pekerja Cloud Build yang lebih besar dengan meneruskan --cloud_build_machine_type=machine_type, dengan machine_type adalah salah satu opsi berikut:
- n1-highcpu-8
- n1-highcpu-32
- e2-highcpu-8
- e2-highcpu-32
Secara default, Cloud Build menggunakan jenis mesin e2-medium.
Di Apache Beam 2.44.0 dan yang lebih baru, pekerja membuat lingkungan virtual saat memulai penampung kustom. Jika penampung membuat lingkungan virtualnya sendiri untuk menginstal dependensi, dependensi tersebut akan dihapus. Perilaku ini dapat menyebabkan error seperti berikut:

ModuleNotFoundError: No module named '<dependency name>'

Untuk menghindari masalah ini, instal dependensi ke lingkungan Python default (global). Sebagai solusi, nonaktifkan perilaku ini di Beam 2.48.0 dan versi lebih baru dengan menetapkan variabel lingkungan berikut di image container Anda:

ENV RUN_PYTHON_SDK_IN_DEFAULT_ENVIRONMENT=1

Langkah selanjutnya

Untuk mengetahui informasi selengkapnya tentang cara menulis Dockerfile, lihat Praktik terbaik untuk menulis Dockerfile.
Pelajari cara Menjalankan tugas Dataflow dalam penampung kustom.