配置 Flex 模板

本页面介绍 Dataflow Flex 模板的权限、所需的 Dockerfile 环境变量和支持的流水线选项。

如要配置示例 Flex 模板，请参阅 Flex 模板教程。

了解 Flex 模板权限

使用 Flex 模板时，需要注意以下三组权限：

  • 创建资源的权限
  • 构建 Flex 模板的权限
  • 运行 Flex 模板的权限

创建资源的权限

要开发和运行 Flex 模板流水线，您需要创建各种资源（例如暂存存储分区）。对于一次性资源创建任务，您可以使用基本 Owner 角色。

构建 Flex 模板的权限

作为 Flex 模板的开发者，您需要构建模板，以将其提供给用户。构建涉及将模板规范上传到 Cloud Storage 存储分区，以及使用运行流水线所需的代码和依赖项预配 Docker 映像。要构建 Flex 模板，您需要 Cloud Storage 的读写权限，以及 Container Registry 的读写权限。您可以通过分配以下角色来授予这些权限：

  • Storage Admin (roles/storage.admin)
  • Cloud Build Editor (roles/cloudbuild.builds.editor)

注意：您还可以使用 Artifact Registry 存储映像。如需了解 Artifact Registry 权限，请参阅配置访问权限控制。

运行 Flex 模板的权限

当您运行 Flex 模板时，Dataflow 会为您创建一个作业。要创建作业，Dataflow 服务帐号需要以下权限：

  • dataflow.serviceAgent

首次使用 Dataflow 时，服务会为您分配此角色，因此您无需采取任何操作来授予上述权限。

默认情况下，Compute Engine 服务帐号用于启动器虚拟机和工作器虚拟机。该服务帐号需要以下角色和权限：

  • Storage Object Admin (roles/storage.objectAdmin)
  • Viewer (roles/viewer)
  • Dataflow Worker (roles/dataflow.worker)
  • 暂存存储分区的读写权限
  • Flex 模板映像的读取权限

如需授予暂存存储分区的读写权限，您可以使用 Storage Object Admin (roles/storage.objectAdmin) 角色。如需了解详情，请参阅 Cloud Storage 的 IAM 角色。

如需授予 Flex 模板映像的读取权限，您可以使用 Storage Object Viewer (roles/storage.objectViewer) 角色。如需了解详情，请参阅配置访问权限控制。

设置所需的 Dockerfile 环境变量

如果要为 Flex 模板作业创建自己的 Docker 文件，您必须指定以下环境变量：

Java

您必须在 Dockerfile 中指定 FLEX_TEMPLATE_JAVA_MAIN_CLASS 和 FLEX_TEMPLATE_JAVA_CLASSPATH。

ENV 说明 必需
FLEX_TEMPLATE_JAVA_MAIN_CLASS 指定启动 Flex 模板要运行的 Java 类。 是
FLEX_TEMPLATE_JAVA_CLASSPATH 指定类文件的位置。 是
FLEX_TEMPLATE_JAVA_OPTIONS 指定启动 Flex 模板时要传递的 Java 选项。 否

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

例如，我们在 Streaming in Python Flex 模板教程中设置了以下环境变量：

ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="${WORKDIR}/requirements.txt"
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="${WORKDIR}/streaming_beam.py"
ENV 说明 必需
FLEX_TEMPLATE_PYTHON_PY_FILE 指定启动 Flex 模板要运行的 Python 文件。 是
FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE 指定用于安装启动依赖项的要求文件。如果您指定了 FLEX_TEMPLATE_PYTHON_SETUP_FILE，请勿设置此变量。 否
FLEX_TEMPLATE_PYTHON_SETUP_FILE 指定用于安装启动依赖项的设置文件。如需了解如何使用设置文件，请参阅多个文件依赖项。 否
FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES

指定不公开提供的软件包。如需了解如何使用额外的软件包，请参阅本地或非 PyPI 依赖项。

 否
FLEX_TEMPLATE_PYTHON_PY_OPTIONS 指定启动 Flex 模板时要传递的 Python 选项。 否

选择基础映像

您可以使用 Google 提供的基础映像来使用 Docker 打包模板容器映像。从 Flex 模板基础映像中选择最新标记。建议使用特定的图片代码（而非 latest）。

请按以下格式指定基础映像：

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

请替换以下内容：

使用自定义容器映像

如果您的流水线使用自定义容器映像，我们建议将此自定义映像用作 Flex 模板 Docker 映像的基础映像。为此，请将 Google 提供的模板启动器映像中的 Flex 模板启动器二进制文件复制到您的自定义映像。示例 Dockerfile：

FROM gcr.io/dataflow-templates-base/IMAGE_NAME:TAG as template_launcher
FROM USER_CUSTOM_IMAGE

COPY --from=template_launcher /opt/google/dataflow/python_template_launcher /opt/google/dataflow/python_template_launcher

ARG WORKDIR=/dataflow/template
RUN mkdir -p ${WORKDIR}
WORKDIR ${WORKDIR}

COPY streaming_beam.py .

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

ENTRYPOINT ["/opt/google/dataflow/python_template_launcher"]

创建新的 Dockerfile，将 Flex 模板启动器映像指定为父级映像，并添加任何自定义内容。如需详细了解如何编写 Dockerfile，请参阅编写 Dockerfile 的最佳做法。 如需了解详情，请参阅使用自定义容器指南

请替换以下内容：

  • IMAGE_NAME：Google 提供的启动器映像。这些二进制文件是针对 Debian GNU/Linux 操作系统构建的。
  • TAG：启动器映像的版本名称，请参阅 Flex 模板启动器映像参考。避免使用 latest 并固定到特定版本标记，以获得更好的稳定性和问题排查。
  • USER_CUSTOM_IMAGE：您的自定义容器映像

指定流水线选项

如需了解 Flex 模板直接支持的流水线选项，请参阅流水线选项。

您还可以间接使用任何 Apache Beam 流水线选项。如果您为 Flex 模板作业使用 metadata.json 文件，请在该文件中添加以下流水线选项。此元数据文件必须遵循 TemplateMetadata 中的格式。如需查看 metadata.json 文件的示例，请参阅流式 SQL Flex 模板示例。

否则，在启动 Flex 模板作业时，请使用参数字段传递这些流水线选项。

API

使用 parameters 字段添加流水线选项。

gcloud

使用 parameters 标志添加流水线选项。

传递 List 或 Map 类型的参数时，可能需要在 YAML 文件中定义参数并使用 flags-file。如需查看此方法的示例，请参阅此解决方案中的“创建包含参数的文件”步骤。

了解暂存位置和临时位置

Google Cloud CLI 会在您运行 Flex 模板时提供 --staging-location 和 --temp-location 选项。类似地，Dataflow REST API 为 FlexTemplateRuntimeEnvironment 提供了 stagingLocation 和 tempLocation 字段。

对于 Flex 模板，暂存位置是在启动模板的暂存步骤中将文件写入的 Cloud Storage 网址。Dataflow 会读取这些暂存文件以创建模板图。临时位置是在执行步骤中将临时文件写入的 Cloud Storage 网址。

后续步骤