Mengonfigurasi Template Flex

Halaman ini mendokumentasikan berbagai opsi konfigurasi Template Flex Dataflow, termasuk:

• Izin
• Variabel lingkungan Dockerfile
• Dependensi paket untuk Python
• Image Docker
• Opsi pipeline
• Lokasi sementara dan penyiapan

Untuk mengonfigurasi contoh Template Flex, lihat tutorial Template Flex.

Memahami izin Template Flex

Saat menggunakan Template Flex, Anda memerlukan tiga set izin:

• Izin untuk membuat resource
• Izin untuk membuat Template Flex
• Izin untuk menjalankan Template Flex

Izin untuk membuat resource

Untuk mengembangkan dan menjalankan pipeline Template Flex, Anda perlu membuat berbagai resource (misalnya, bucket staging). Untuk tugas pembuatan resource satu kali, Anda dapat menggunakan peran Pemilik dasar.

Izin untuk membuat Template Flex

Sebagai developer Template Flex, Anda perlu membuat template agar tersedia bagi pengguna. Build melibatkan penguploadan spesifikasi template ke bucket Cloud Storage dan penyediaan image Docker dengan kode dan dependensi yang diperlukan untuk menjalankan pipeline. Untuk membuat Template Fleksibel, Anda memerlukan akses baca dan tulis ke Cloud Storage serta akses Penulis Artifact Registry ke repositori Artifact Registry Anda. Anda dapat memberikan izin ini dengan menetapkan peran berikut:

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

Izin untuk menjalankan Template Flex

Saat Anda menjalankan Template Flex, Dataflow akan membuat tugas untuk Anda. Untuk membuat tugas, akun layanan Dataflow memerlukan izin berikut:

• dataflow.serviceAgent

Saat Anda pertama kali menggunakan Dataflow, layanan akan menetapkan peran ini untuk Anda, sehingga Anda tidak perlu memberikan izin ini.

Secara default, akun layanan Compute Engine digunakan untuk VM peluncur dan VM pekerja. Akun layanan memerlukan peran dan kemampuan berikut:

• Storage Object Admin (roles/storage.objectAdmin)
• Pelihat (roles/viewer)
• Dataflow Worker (roles/dataflow.worker)
• Akses baca dan tulis ke bucket penyiapan
• Akses baca ke image Template Flex

Untuk memberikan akses baca dan tulis ke bucket penyiapan, Anda dapat menggunakan peran Storage Object Admin (roles/storage.objectAdmin). Untuk mengetahui informasi selengkapnya, lihat Peran IAM untuk Cloud Storage.

Untuk memberikan akses baca ke image Template Flex, Anda dapat menggunakan peran Storage Object Viewer (roles/storage.objectViewer). Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi kontrol akses.

Tetapkan variabel lingkungan Dockerfile yang diperlukan

Jika Anda ingin membuat Dockerfile sendiri untuk tugas Template Flex, tentukan variabel lingkungan berikut:

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

Dependensi paket untuk Python

Saat pipeline Python Dataflow menggunakan dependensi tambahan, Anda mungkin perlu mengonfigurasi Template Flex untuk menginstal dependensi tambahan di VM pekerja Dataflow.

Saat menjalankan tugas Dataflow Python yang menggunakan Template Flex di lingkungan yang membatasi akses ke internet, Anda harus memaketkan terlebih dahulu dependensi saat membuat template.

Gunakan salah satu opsi berikut untuk mengemas terlebih dahulu dependensi Python.

Untuk mengetahui petunjuk tentang cara mengelola dependensi pipeline di pipeline Java dan Go, lihat Mengelola dependensi pipeline di Dataflow.

Gunakan file persyaratan dan kemas sebelumnya dependensi dengan template

Jika Anda menggunakan Dockerfile sendiri untuk menentukan image Template Flex, ikuti langkah-langkah berikut:

1. Buat file requirements.txt yang mencantumkan dependensi pipeline Anda.

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

2. Instal dependensi di image Template Flex.

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

3. Download dependensi ke cache persyaratan lokal, yang di-stage ke pekerja Dataflow saat template diluncurkan.

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

Saat Anda menggunakan pendekatan ini, dependensi dari file requirements.txt akan diinstal pada pekerja Dataflow saat runtime. Insight di tab rekomendasi Google Cloud konsol mungkin mencatat perilaku ini. Untuk menghindari penginstalan dependensi saat runtime, gunakan image container kustom.

Berikut adalah contoh kode yang menggunakan file persyaratan di Flex Template.

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

Menyusun pipeline sebagai paket dan menggunakan paket lokal

Saat Anda menggunakan beberapa file atau modul lokal Python, susun pipeline Anda sebagai paket. Struktur file mungkin terlihat seperti contoh berikut:

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

1. Tempatkan titik entri tingkat atas, misalnya, file main.py, di direktori root. Tempatkan file lainnya di folder terpisah di direktori src, misalnya, my_package.

2. Tambahkan file konfigurasi paket ke direktori root dengan detail dan persyaratan paket.

   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()
   

   Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi paket lokal, lihat Mengemas Project Python.

3. Saat Anda mengimpor modul atau file lokal untuk pipeline, gunakan nama paket my_package sebagai jalur impor.

   from my_package import word_count_transform
   

4. Instal paket pipeline Anda di image Template Flex. Dockerfile Template Fleksibel Anda mungkin menyertakan konten yang mirip dengan contoh berikut:

   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 .
   

Saat Anda menggunakan pendekatan ini, dependensi dari file requirements.txt akan diinstal pada pekerja Dataflow saat runtime. Insight di tab rekomendasi Google Cloud konsol mungkin mencatat perilaku ini. Untuk menghindari penginstalan dependensi saat runtime, gunakan image container kustom.

Untuk contoh yang mengikuti pendekatan yang direkomendasikan, lihat tutorial Template Fleksibel untuk pipeline dengan dependensi dan image container kustom di GitHub.

Menggunakan container kustom yang menginstal semua dependensi terlebih dahulu

Untuk menghindari penginstalan dependensi saat runtime, gunakan container kustom. Opsi ini lebih disukai untuk pipeline yang berjalan di lingkungan tanpa akses internet.

Ikuti langkah-langkah berikut untuk menggunakan container kustom:

1. Buat image container kustom yang menginstal terlebih dahulu dependensi yang diperlukan.

2. Lakukan pra-penginstalan dependensi yang sama di Dockerfile Template Flex.

   Untuk mencegah penginstalan dependensi saat runtime, jangan gunakan opsi FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE atau FLEX_TEMPLATE_PYTHON_SETUP_FILE dalam konfigurasi Template Fleksibel Anda.

   Dockerfile Flex Template yang diubah mungkin terlihat seperti contoh berikut:

   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
   

   Saat menggunakan pendekatan ini, Anda melakukan hal berikut:

   • buat image Template Flex
   • membangun image container SDK kustom
   • menginstal dependensi yang sama di kedua gambar

   Atau, untuk mengurangi jumlah image yang perlu dikelola, gunakan image container kustom Anda sebagai image dasar untuk Template Flex.

3. Jika Anda menggunakan Apache Beam SDK versi 2.49.0 atau yang lebih lama, tambahkan opsi pipeline --sdk_location=container di peluncur pipeline Anda. Opsi ini memberi tahu pipeline Anda untuk menggunakan SDK dari container kustom Anda, bukan mendownload SDK.

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

4. Tetapkan parameter sdk_container_image dalam perintah flex-template run. Contoh:

   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
   

   Untuk mengetahui informasi selengkapnya, lihat Menggunakan container kustom di Dataflow.

Memilih image dasar

Anda dapat menggunakan image dasar yang disediakan Google untuk mengemas image container template Anda menggunakan Docker. Pilih tag terbaru dari gambar dasar Template Fleksibel. Sebaiknya gunakan tag gambar tertentu, bukan latest. Image dasar dihosting di gcr.io/dataflow-templates-base.

Tentukan gambar dasar dalam format berikut:

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

Ganti kode berikut:

• IMAGE_NAME: gambar dasar yang disediakan Google
• TAG: nama versi untuk image dasar, yang ada dalam Referensi image dasar Template Fleksibel

Menggunakan image container kustom

Jika pipeline Anda menggunakan image container kustom, sebaiknya gunakan image kustom sebagai image dasar untuk image Docker Template Fleksibel Anda. Untuk melakukannya, salin biner peluncur Template Flex dari image dasar template yang disediakan Google ke image kustom Anda.

Contoh Dockerfile untuk gambar yang dapat digunakan sebagai image container SDK Kustom dan sebagai Template Flex, mungkin terlihat seperti berikut:

FROM gcr.io/dataflow-templates-base/IMAGE_NAME:TAG as template_launcher
FROM apache/beam_python3.10_sdk:2.66.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"

Ganti kode berikut:

• IMAGE_NAME: image dasar yang disediakan Google. Contoh: python311-template-launcher-base.
• TAG: tag versi untuk image dasar yang ada di referensi image dasar Template Fleksibel. Untuk stabilitas dan pemecahan masalah yang lebih baik, hindari penggunaan latest. Sebagai gantinya, sematkan ke tag versi tertentu.

Untuk contoh yang mengikuti pendekatan ini, lihat tutorial Template Fleksibel untuk pipeline dengan dependensi dan image container kustom.

Menggunakan gambar dari registry pribadi

Anda dapat membuat image Template Fleksibel yang disimpan di registry Docker pribadi, jika registry pribadi menggunakan HTTPS dan memiliki sertifikat yang valid.

Untuk menggunakan image dari registry pribadi, tentukan jalur ke image serta nama pengguna dan sandi untuk registry. Nama pengguna dan sandi harus disimpan di Secret Manager. Anda dapat memberikan secret dalam salah satu format berikut:

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

Jika Anda menggunakan format kedua, karena tidak menentukan versi, Dataflow akan menggunakan versi terbaru.

Jika registry menggunakan sertifikat yang ditandatangani sendiri, Anda juga perlu menentukan jalur ke sertifikat yang ditandatangani sendiri di Cloud Storage.

Tabel berikut menjelaskan opsi gcloud CLI yang dapat Anda gunakan untuk mengonfigurasi registry pribadi.

Berikut adalah contoh perintah Google Cloud CLI yang membangun Template Fleksibel menggunakan image di registry pribadi dengan sertifikat yang ditandatangani sendiri.

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

Untuk membuat Template Flex Anda sendiri, Anda perlu mengganti nilai contoh, dan Anda mungkin perlu menentukan opsi yang berbeda atau tambahan. Untuk mempelajari lebih lanjut, lihat referensi berikut:

• gcloud dataflow flex-template build
• Menggunakan Template Flex

Menentukan opsi pipeline

Untuk mengetahui informasi tentang opsi pipeline yang didukung langsung oleh Flex Templates, lihat Opsi pipeline.

Anda juga dapat menggunakan opsi pipeline Apache Beam secara tidak langsung. Jika Anda menggunakan file metadata.json untuk tugas Template Flex, sertakan opsi pipeline ini dalam file. File metadata ini harus mengikuti format di TemplateMetadata.

Jika tidak, saat Anda meluncurkan tugas Template Flex, teruskan opsi pipeline ini menggunakan kolom parameter.

Untuk opsi eksperimental runtime atau opsi pipeline runtime umum yang tidak diekspos secara eksplisit dalam metadata template, teruskan opsi ini menggunakan kolom additional-experiments atau additional-pipeline-options.

{
  "jobName": "my-flex-template-job",
  "parameters": {
    "option_defined_in_metadata": "value"
  },
  "environment": {
    "additionalExperiments": [
      "use_runner_v2"
    ],
    "additionalPipelineOptions": {
      "common_pipeline_option": "value"
    }
  }
}

Saat menggunakan Template Flex, Anda dapat mengonfigurasi beberapa opsi pipeline selama inisialisasi pipeline, tetapi opsi pipeline lainnya tidak dapat diubah. Jika argumen command line yang diperlukan oleh Template Flex ditimpa, tugas dapat mengabaikan, mengganti, atau membuang opsi pipeline yang diteruskan oleh peluncur template. Tugas mungkin gagal diluncurkan, atau tugas yang tidak menggunakan Template Fleksibel mungkin diluncurkan. Untuk mengetahui informasi selengkapnya, lihat Gagal membaca file tugas.

Selama inisialisasi pipeline, jangan ubah opsi pipeline berikut:

Memblokir kunci SSH project dari VM yang menggunakan kunci SSH berbasis metadata

Anda dapat mencegah VM menerima kunci SSH yang disimpan dalam metadata project dengan memblokir kunci SSH project dari VM. Gunakan flag additional-experiments dengan opsi layanan block_project_ssh_keys:

--additional-experiments=block_project_ssh_keys

Untuk mengetahui informasi selengkapnya, lihat Opsi layanan Dataflow.

Metadata

Anda dapat memperluas template dengan metadata tambahan sehingga parameter kustom divalidasi saat template dijalankan. Jika Anda ingin membuat metadata untuk template, ikuti langkah-langkah berikut:

1. Buat file metadata.json menggunakan parameter di Parameter metadata.

   Untuk melihat contoh, lihat Contoh file metadata.

2. Simpan file metadata di Cloud Storage dalam folder yang sama dengan template.

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

Memahami lokasi penyiapan dan lokasi sementara

Google Cloud CLI menyediakan opsi --staging-location dan --temp-location saat Anda menjalankan template fleksibel. Demikian pula, Dataflow REST API menyediakan kolom stagingLocation dan tempLocation untuk FlexTemplateRuntimeEnvironment.

Untuk Template Flex, lokasi penyiapan adalah URL Cloud Storage yang menjadi tujuan penulisan file selama langkah penyiapan peluncuran template. Dataflow membaca file yang di-staging ini untuk membuat grafik template. Lokasi sementara adalah URL Cloud Storage tempat file sementara ditulis selama langkah eksekusi.

Memperbarui tugas Template Flex

Contoh permintaan berikut menunjukkan cara memperbarui tugas streaming template menggunakan metode projects.locations.flexTemplates.launch. Jika Anda ingin menggunakan gcloud CLI, lihat Memperbarui pipeline yang ada.

Jika Anda ingin memperbarui template klasik, gunakan projects.locations.templates.launch sebagai gantinya.

1. Ikuti langkah-langkah untuk membuat tugas streaming dari Template Flex. Kirim permintaan POST HTTP berikut dengan nilai yang diubah:

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

   • Ganti PROJECT_ID dengan project ID Anda.
   • Ganti REGION dengan region Dataflow tugas yang Anda perbarui.
   • Ganti JOB_NAME dengan nama persis tugas yang ingin Anda perbarui.
   • Tetapkan parameters ke daftar key-value pair Anda. Parameter yang tercantum bersifat khusus untuk contoh template ini. Jika Anda menggunakan template kustom, ubah parameter sesuai kebutuhan. Jika Anda menggunakan template contoh, ganti variabel berikut.
     • Ganti SUBSCRIPTION_NAME dengan nama langganan Pub/Sub Anda.
     • Ganti DATASET dengan nama set data BigQuery Anda.
     • Ganti TABLE_NAME dengan nama tabel BigQuery Anda.
   • Ganti STORAGE_PATH dengan lokasi Cloud Storage file template. Lokasi harus diawali dengan gs://.

2. Gunakan parameter environment untuk mengubah setelan lingkungan. Untuk mengetahui informasi selengkapnya, lihat FlexTemplateRuntimeEnvironment.

3. Opsional: Untuk mengirim permintaan menggunakan curl (Linux, macOS, atau Cloud Shell), simpan permintaan ke file JSON, lalu jalankan perintah berikut:

   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
   

   Ganti FILE_PATH dengan jalur ke file JSON yang berisi isi permintaan.

4. Gunakan antarmuka pemantauan Dataflow untuk memverifikasi bahwa tugas baru dengan nama yang sama telah dibuat. Tugas ini memiliki status Diperbarui.

Batasan

Batasan berikut berlaku untuk tugas Flex Templates:

• Anda harus menggunakan image dasar yang disediakan Google untuk mengemas container menggunakan Docker. Untuk mengetahui daftar image yang berlaku, lihat Image dasar Template Fleksibel.
• Program yang membuat pipeline harus keluar setelah run dipanggil agar pipeline dapat dimulai.
• waitUntilFinish (Java) dan wait_until_finish (Python) tidak didukung.

Langkah berikutnya

• Untuk mengetahui lebih lanjut Template Klasik, Template Flex, dan skenario kasus penggunaannya, lihat Template Dataflow.
• Untuk mengetahui informasi pemecahan masalah Template Flex, lihat Memecahkan masalah waktu tunggu habis Template Flex.
• Untuk mengetahui lebih banyak tentang arsitektur referensi, diagram, dan praktik terbaik lainnya, jelajahi Pusat Arsitektur Cloud.