使用 Flex 範本封裝 Dataflow 管道來用於部署

本頁說明如何為 Dataflow 管道建立彈性範本。您可以透過 Flex 範本封裝 Apache Beam 管道程式碼，這樣就能在沒有開發環境的情況下執行管道。建立 Flex 範本後，只要具備適當權限，就能以 Dataflow 工作形式執行管道。

如需建立及執行彈性範本的端對端教學課程，請參閱「建構及執行範例彈性範本」。

總覽

彈性範本包含下列元件：

• 儲存在 Artifact Registry 中的容器映像檔。 容器負責啟動 Dataflow 工作。

• 儲存在 Cloud Storage 中的 JSON 規格檔案。這個檔案包含容器映像檔的指標和其他中繼資料。

建立彈性範本前，請先使用 Apache Beam SDK 編寫管道程式碼。詳情請參閱使用 Apache Beam 建構管道。

建構管道的程式必須在呼叫 run 後結束，管道才會開始執行。請勿呼叫 waitUntilFinish (Java) 或 wait_until_finish (Python)，因為這些函式會封鎖 Flex 範本，導致無法執行。

所需權限

如要取得建構彈性範本所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

• 儲存空間管理員 (roles/storage.admin)
• Cloud Build 編輯器 (roles/cloudbuild.builds.editor)
• Artifact Registry 寫入者 (roles/artifactregistry.writer)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

範本中繼資料

您可以視需要提供範本的其他中繼資料，包括：

• 管道參數：宣告管道使用的任何自訂管道選項。提交 Flex 範本工作時，Dataflow 會驗證參數。如果您使用Google Cloud 控制台執行範本，「從範本建立工作」對話方塊會包含中繼資料中宣告的管道參數。

• 串流支援：您可以指定管道是否支援串流，如果支援，則指定是否支援「正好一次」模式或「至少一次」模式。這項中繼資料可讓 Google Cloud 控制台在您執行範本時，顯示相關管道選項。

如要加入其他中繼資料，請建立含有中繼資料參數的 JSON 檔案。 在 gcloud dataflow flex-template build 指令的 --metadata-file 旗標中指定這個檔案。中繼資料檔案的內容會併入範本規格檔案。詳情請參閱建構 Flex 範本。

中繼資料參數

參數鍵		必填	值說明
name		是	範本的名稱。
description		否	用來說明範本的一小段文字。
streaming		否	如果 true，這個範本支援串流。預設值為 false。
supportsAtLeastOnce		否	如果 true，這個範本支援至少一次處理。預設值為 false。如果範本的設計是搭配至少一次串流模式使用，請將這個參數設為 true。
supportsExactlyOnce		否	如果 true，這個範本支援僅須處理一次。預設值為 true。
defaultStreamingMode		否	如果範本同時支援「至少一次」和「僅一次」模式，預設會採用「至少一次」模式。請使用下列其中一個值："AT_LEAST_ONCE"、"EXACTLY_ONCE"。如未指定，預設串流模式為「恰好一次」。
parameters		否	範本使用的其他參數陣列。預設會使用空陣列。
	name	是	範本中使用的參數名稱。
	label	是	使用者可理解的字串，用於在 Google Cloud 控制台中標記參數。
	helpText	是	用來說明參數的一小段文字。
	isOptional	否	如果參數為必要，則為 false；如果參數為選用，則為 true。除非設定值，否則 isOptional 預設為 false。 如果中繼資料未包含這個參數鍵，中繼資料就會成為必要參數。
	regexes	否	字串形式的 POSIX-egrep 規則運算式陣列，用於驗證參數的值。舉例來說，["^[a-zA-Z][a-zA-Z0-9]+"] 是單一規則運算式，可驗證開頭為一個字母、後續有一或多個字元的值。預設為空陣列。

中繼資料檔案範例

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

您可以從 Dataflow 範本目錄下載 Google 提供的範本中繼資料檔案。

注意： 在 metadata.json 檔案中變更啟動參數，可能會導致工作忽略、覆寫或捨棄範本啟動器傳遞的管道選項。工作可能無法啟動，或啟動未使用彈性範本的工作。詳情請參閱「指定管道選項」和「無法讀取工作檔案」。

環境變數

建構 Flex 範本時，請在 gcloud dataflow flex-template build 指令的 --env 旗標中指定下列環境變數。如果您使用自訂映像檔，請在 Dockerfile 中設定這些環境變數。

Java

ENV	說明	必填
FLEX_TEMPLATE_JAVA_MAIN_CLASS	指定要執行的 Java 類別，以便啟動 Flex 範本。	是
FLEX_TEMPLATE_JAVA_CLASSPATH	指定類別檔案的位置。	是
FLEX_TEMPLATE_JAVA_OPTIONS	指定啟動 Flex 範本時要傳遞的 Java 選項。	否

在 Dockerfile 中指定 FLEX_TEMPLATE_JAVA_MAIN_CLASS 和 FLEX_TEMPLATE_JAVA_CLASSPATH。

Python

ENV	說明	必填
FLEX_TEMPLATE_PYTHON_PY_FILE	指定要執行的 Python 檔案，以啟動彈性範本。	是
FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE	指定包含管道依附元件的需求檔案。 詳情請參閱 Apache Beam 說明文件中的「PyPI 依附元件」。	否
FLEX_TEMPLATE_PYTHON_SETUP_FILE	指定管道套件 `setup.py` 檔案的路徑。 詳情請參閱 Apache Beam 說明文件中的「多重檔案相依性」。	否
FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES	指定不公開的套件。如要瞭解如何使用額外套件，請參閱「本機或非 PyPI 依附元件」。	否
FLEX_TEMPLATE_PYTHON_PY_OPTIONS	指定啟動 Flex 範本時要傳遞的 Python 選項。	否

在 Dockerfile 中指定 FLEX_TEMPLATE_PYTHON_PY_FILE。

如要管理管道依附元件，請在 Dockerfile 中設定變數，例如：

• FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE
• FLEX_TEMPLATE_PYTHON_PY_OPTIONS
• FLEX_TEMPLATE_PYTHON_SETUP_FILE
• FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES

舉例來說，GitHub 的「在 Python Flex 範本教學課程中串流」會設定下列環境變數：

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

Go

ENV	說明	必填
FLEX_TEMPLATE_GO_BINARY	指定要執行的 Go 二進位檔。	是

在 Dockerfile 中指定 FLEX_TEMPLATE_GO_BINARY。

Flex 範本映像檔

彈性範本包含啟動 Dataflow 管道的容器映像檔。執行彈性範本作業時，Dataflow 服務會從 Artifact Registry 下載容器映像檔，並啟動容器。容器負責啟動 Dataflow 工作。

Google 維護一組可供使用的彈性範本基本映像檔。不過，如果管道需要自訂容器映像檔，建議您對彈性範本使用相同映像檔。這樣一來，Flex 範本啟動器就會包含與管道執行階段容器相同的依附元件。

自訂容器映像檔

如要建立自訂彈性範本映像檔，請在 Dockerfile 中加入下列步驟：

• 從 Google 提供的其中一個基本映像檔，將 Flex 範本啟動器二進位檔複製到您的映像檔。啟動器二進位檔位於下列路徑：

  Java

  /opt/google/dataflow/java_template_launcher

  Python

  /opt/google/dataflow/python_template_launcher

  Go

  /opt/google/dataflow/go_template_launcher

• 複製啟動管道工作所需的構件，例如 Python 檔案、JAR 檔案或 Go 二進位檔。

• 設定「環境變數」一節中列出的環境變數。

以下範例顯示 Python 管道的 Dockerfile：

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

更改下列內容：

• IMAGE_NAME：Google 提供的基礎圖片。例如： python311-template-launcher-base。
• TAG：Flex 範本基本映像檔中列出的基本映像檔版本標記。為提升穩定性及方便排解問題，請避免使用 latest。請改為固定在特定版本標記。

如需採用這種做法的教學課程，請參閱「Flex 範本：適用於含有依附元件和自訂容器映像檔的管道」。

建立 Flex 範本

如要建構 Flex 範本，請使用 gcloud dataflow flex-template build 指令。這項指令會建立下列構件：

• 儲存在 Cloud Storage 中的範本規格檔案
• 啟動器容器映像檔 (儲存在 Artifact Registry 中)

使用 Google 提供的基本映像檔

如要使用 Google 提供的基本映像檔執行彈性範本，請執行下列指令：

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"

更改下列內容：

• BUCKET_NAME：Cloud Storage 值區的名稱，用於儲存範本規格檔案
• TEMPLATE_FILE_NAME：要建立的範本規格檔案名稱。範例：my_template.json
• LOCATION：Artifact Registry 存放區的位置
• PROJECT_ID： Google Cloud 專案 ID
• REPOSITORY：Artifact Registry 存放區的名稱
• IMAGE：Flex 範本容器映像檔的名稱
• TAG：Flex 範本容器映像檔的標記
• <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：中繼檔案的本機路徑。詳情請參閱範本中繼資料。
• JAR_FILE：管道程式碼 JAR 檔案的本機路徑。如有數個 JAR 檔案，請將其格式設為以半形逗號分隔的清單，或在個別 --jar 標記中指定檔案。
• JAVA_MAIN_CLASS：要執行的 Java 類別名稱。詳情請參閱「環境變數」。

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"

更改下列內容：

• BUCKET_NAME：Cloud Storage 值區的名稱，用於儲存範本規格檔案
• TEMPLATE_FILE_NAME：要建立的範本規格檔案名稱。範例：my_template.json
• LOCATION：Artifact Registry 存放區的位置
• PROJECT_ID： Google Cloud 專案 ID
• REPOSITORY：Artifact Registry 存放區的名稱
• IMAGE：Flex 範本容器映像檔的名稱
• TAG：Flex 範本容器映像檔的標記
• <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：中繼檔案的本機路徑。詳情請參閱範本中繼資料。
• PYTHON_FILE_PATH：管道的 Python 檔案本機路徑，以及所有依附檔案。您可以透過逗號分隔清單或個別 --py-path 標記的形式指定多個路徑。
• PYTHON_FILE：要執行的 Python 檔案。詳情請參閱「環境變數」。

Go

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"

更改下列內容：

• BUCKET_NAME：Cloud Storage 值區的名稱，用於儲存範本規格檔案
• TEMPLATE_FILE_NAME：要建立的範本規格檔案名稱。範例：my_template.json
• LOCATION：Artifact Registry 存放區的位置
• PROJECT_ID： Google Cloud 專案 ID
• REPOSITORY：Artifact Registry 存放區的名稱
• IMAGE：Flex 範本容器映像檔的名稱
• TAG：Flex 範本容器映像檔的標記
• <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：中繼檔案的本機路徑。詳情請參閱範本中繼資料。
• GO_FILE_PATH：管道編譯 Go 二進位檔的本機路徑
• GO_BINARY：要執行的 Go 二進位檔。詳情請參閱「環境變數」。

使用自訂映像檔

如要使用自訂容器映像檔執行彈性範本，請執行下列指令：

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"

Go

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

更改下列內容：

• BUCKET_NAME：用於儲存範本規格檔案的 Cloud Storage 值區名稱。

• TEMPLATE_FILE_NAME：範本規格檔案的名稱。範例：my_template.json。

• CUSTOM_IMAGE：自訂映像檔的映像檔登錄位置。

• METADATA_FILE：中繼檔案的本機路徑。

Python 的套件依附元件

如果 Dataflow Python 管道使用其他依附元件，您可能需要設定彈性範本，在 Dataflow worker VM 上安裝其他依附元件。

在限制網際網路存取的環境中，執行使用 Flex 範本的 Python Dataflow 工作時，您必須在建立範本時預先封裝相依性。

請使用下列其中一種方式預先封裝 Python 依附元件。

• 使用需求檔案，並預先將依附元件與範本封裝在一起。
• 將管道架構為套件，並使用本機套件。
• 使用預先安裝所有依附元件的自訂容器。

如需管理 Java 和 Go 管道中管道依附元件的操作說明，請參閱「在 Dataflow 中管理管道依附元件」。

使用需求檔案，並預先將依附元件與範本封裝在一起

如果您使用自己的 Dockerfile 定義彈性範本映像檔，請按照下列步驟操作：

1. 建立 requirements.txt 檔案，列出管道依附元件。

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

2. 在 Flex 範本映像檔中安裝依附元件。

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

3. 將相依性檔案下載到本機需求快取，範本啟動時，這些檔案會暫存到 Dataflow 工作站。

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

使用這種方法時，系統會在執行階段將 requirements.txt 檔案中的依附元件安裝到 Dataflow 工作站。您可能會在 Google Cloud 控制台 的「最佳化建議」分頁中看到這類洞察資訊。如要避免在執行階段安裝依附元件，請使用自訂容器映像檔。

以下程式碼範例會在彈性範本中使用需求檔案。

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

將管道架構為套件，並使用本機套件

使用多個 Python 本機檔案或模組時，請將管線建構為套件。檔案結構可能如下列範例所示：

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. 將頂層進入點 (例如 main.py 檔案) 放在根目錄中。將其餘檔案放在 src 目錄的獨立資料夾中，例如 my_package。

2. 在根目錄中新增套件設定檔，並提供套件詳細資料和需求條件。

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

   如要進一步瞭解如何設定本機套件，請參閱「封裝 Python 專案」。

3. 為管道匯入本機模組或檔案時，請使用 my_package 套件名稱做為匯入路徑。

   from my_package import word_count_transform
   

4. 在 Flex 範本映像檔中安裝管道套件。您的 Flex 範本 Dockerfile 可能包含類似下列範例的內容：

   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 .
   

使用這種方法時，系統會在執行階段將 requirements.txt 檔案中的依附元件安裝到 Dataflow 工作站。您可能會在 Google Cloud 控制台 的「最佳化建議」分頁中看到這類洞察資訊。如要避免在執行階段安裝依附元件，請使用自訂容器映像檔。

如需採用建議做法的範例，請參閱 GitHub 中的具有依附元件和自訂容器映像檔的管道彈性範本教學課程。

使用預先安裝所有依附元件的自訂容器

如要避免在執行階段安裝依附元件，請使用自訂容器。如果管道在無法存取網際網路的環境中執行，建議使用這個選項。

如要使用自訂容器，請按照下列步驟操作：

1. 建立自訂容器映像檔，預先安裝必要依附元件。

2. 在 Flex 範本 Dockerfile 中預先安裝相同的依附元件。

   如要避免在執行階段安裝依附元件，請勿在 Flex 範本設定中使用 FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE 或 FLEX_TEMPLATE_PYTHON_SETUP_FILE 選項。

   修改後的彈性範本 Dockerfile 可能如下所示：

   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
   

   使用這個方法時，請執行下列操作：

   • 建構 Flex 範本映像檔
   • 建構自訂 SDK 容器映像檔
   • 在兩個映像檔中安裝相同的依附元件

   或者，如要減少維護的映像檔數量，請將自訂容器映像檔做為 Flex 範本的基本映像檔。

3. 如果您使用 Apache Beam SDK 2.49.0 以下版本，請在管道啟動器中新增 --sdk_location=container 管道選項。這個選項會指示管道使用自訂容器中的 SDK，而非下載 SDK。

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

4. 在 flex-template run 指令中設定 sdk_container_image 參數。例如：

   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
   

   詳情請參閱「在 Dataflow 中使用自訂容器」。

搭配 Flex 範本使用私密 Docker 登錄檔

如果私人登錄檔使用 HTTPS 並具有有效憑證，您可以建構儲存在私人 Docker 登錄檔中的彈性範本映像檔。

如要使用私人登錄檔中的映像檔，請指定映像檔的路徑，以及登錄檔的使用者名稱和密碼。使用者名稱和密碼必須儲存在 Secret Manager。你可以透過下列其中一種格式提供密碼：

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

如果您使用第二種格式，由於未指定版本，Dataflow 會使用最新版本。

如果登錄檔使用自行簽署的憑證，您也需要在 Cloud Storage 中指定自行簽署憑證的路徑。

下表說明可用於設定私人登錄檔的 gcloud CLI 選項。

參數	說明
image	登錄地址。例如： gcp.repository.example.com:9082/registry/example/image:latest。
image-repository-username-secret-id	用於向私有登錄檔驗證的使用者名稱 Secret Manager 密鑰 ID。例如： projects/example-project/secrets/username-secret。
image-repository-password-secret-id	用於向私人登錄檔驗證的密碼，其 Secret Manager 密碼 ID。例如： projects/example-project/secrets/password-secret/versions/latest。
image-repository-cert-path	私人登錄檔的自簽憑證完整 Cloud Storage 網址。如果登錄檔使用自行簽署的憑證，則必須提供這個值。例如： gs://example-bucket/self-signed.crt。

以下是 Google Cloud CLI 指令範例，可使用私人登錄檔中的映像檔和自行簽署的憑證，建構彈性範本。

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

如要建構自己的 Flex 範本，請替換範例值，並視需要指定其他或額外選項。

後續步驟

• 瞭解如何執行 Flex 範本。
• 建構並執行範例 Flex 範本。
• 如要進一步瞭解傳統範本、Flex 範本及其使用案例情境，請參閱「Dataflow 範本」。
• 如需 Flex 範本疑難排解資訊，請參閱「排解 Flex 範本逾時問題」。
• 如需更多參考架構、圖表和最佳做法，請前往 Cloud Architecture Center。