创建 Dataproc 自定义映像

Dataproc 集群可以预配包含用户预装软件包的自定义映像。本页介绍了如何创建自定义映像并将其安装到 Dataproc 集群上。

使用注意事项和限制

  • 自定义映像生命周期：为帮助确保集群接收最新服务更新和 bug 修复，使用自定义映像创建集群的时间限制为自自定义映像创建日期起 365 天。请注意，使用自定义映像创建的现有集群可以无限期运行。

    如果您想使用特定自定义映像在超过 365 天的时间段里创建集群，则可能需要使用自动化功能。如需了解详情，请参阅如何创建具有过期自定义映像的集群。

  • 仅限 Linux：本文档中的说明仅适用于 Linux 操作系统。未来的 Dataproc 版本可能会支持其他操作系统。

  • 支持的基础映像：自定义映像构建需要从 Dataproc 基础映像开始。支持以下基础映像：Debian、Rocky Linux 和 Ubuntu。

    • 基础映像可用性：在 Dataproc 版本说明中公布的新映像只有在公布之日后一周才能用作自定义映像的基础。

  • 使用可选组件：默认情况下，自定义映像会从其基础映像继承所有 Dataproc 可选组件（操作系统软件包和配置）。您可以自定义默认操作系统软件包版本和配置，但必须在创建集群时指定可选组件名称。

    集群创建命令示例： 

    gcloud dataproc clusters create --optional-components=COMPONENT_NAME \
    --image=CUSTOM_IMAGE_URI  \
     ... other flags

    如果您在创建集群时未指定组件名称，则系统会删除该可选组件（包括任何自定义操作系统软件包和配置）。

  • 使用托管自定义映像：如果您使用托管在其他项目中的自定义映像，则在您的项目中，Dataproc 服务代理服务账号必须具有宿主项目中映像的 compute.images.get 权限。为此，您可以将托管映像的 roles/compute.imageUser 角色授予您的项目的 Dataproc 服务代理服务账号（请参阅在组织内共享自定义映像）。

  • 使用安全启动 MOK（机器所有者密钥）密钥：如需使用 Dataproc 自定义映像启用安全启动，请执行以下操作：

    1. 启用 Secret Manager API (secretmanager.googleapis.com。Dataproc 使用 Secret Manager 服务生成和管理密钥对。

    2. 生成自定义映像时，请将 --service-account="SERVICE_ACCOUNT" 标志添加到 generate_custom_image.py 命令。注意：您必须向服务账号授予项目的 Secret Manager Viewer 角色 (roles/secretmanager.viewer)，以及对公钥和私钥的 Secret Manager Accessor 角色 (roles/secretmanager.secretAccessor)。

    如需了解详情并查看示例，请参阅 GitHub 上 GoogleCloudDataproc/custom-images 代码库的 examples/secure-boot 目录中的 README.md 和其他文件。

    停用安全启动：默认情况下，Dataproc 自定义映像脚本在从 Dataproc 集群运行时会使用 Secret Manager 生成和管理密钥对。如果您不想将安全启动与自定义映像搭配使用，请在生成自定义映像时向 generate_custom_image.py 命令添加 --trusted-cert=""（空标志值）。

准备工作

请务必先设置项目，然后再生成自定义映像。

设置项目

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Dataproc API, Compute Engine API, and Cloud Storage APIs.

    Enable the APIs

  5. Install the Google Cloud CLI.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  8. Make sure that billing is enabled for your Google Cloud project.

  9. Enable the Dataproc API, Compute Engine API, and Cloud Storage APIs.

    Enable the APIs

  10. Install the Google Cloud CLI.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init
  12. 安装 Python 3.11 或更高版本
  13. 准备安装自定义包和/或更新配置的自定义脚本，例如：
      #! /usr/bin/bash
  apt-get -y update
  apt-get install python-dev
  apt-get install python-pip
  pip install numpy

在项目中创建 Cloud Storage 存储分区

  1. In the Google Cloud console, go to the Cloud Storage Buckets page.

    Go to Buckets page

  2. Click Create bucket.
  3. On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
    • For Name your bucket, enter a name that meets the bucket naming requirements.
    • For Choose where to store your data, do the following:
      • Select a Location type option.
      • Select a Location option.
    • For Choose a default storage class for your data, select a storage class.
    • For Choose how to control access to objects, select an Access control option.
    • For Advanced settings (optional), specify an encryption method, a retention policy, or bucket labels.
  4. Click Create.

生成自定义映像

您将使用 Python 程序 generate_custom_image.py 来创建 Dataproc 自定义映像。

工作原理

generate_custom_image.py 程序启动指定 Dataproc 基础映像的临时 Compute Engine 虚拟机实例，然后在虚拟机实例中运行自定义脚本以安装自定义软件包和/或更新配置。自定义脚本完成后，它将关闭虚拟机实例，并从虚拟机实例磁盘创建 Dataproc 自定义映像。在创建自定义映像后，临时虚拟机将被删除。自定义映像已保存，可用于创建 Dataproc 集群。

generate_custom_image.py 程序使用 gcloud CLI 在 Compute Engine 上运行多步骤工作流。

运行代码

在 Dataproc 自定义映像上创建分支或克隆 GitHub 上的文件。

然后，运行 generate_custom_image.py 脚本以使 Dataproc 生成并保存您的自定义映像。

python3 generate_custom_image.py \
    --image-name=CUSTOM_IMAGE_NAME \
    [--family=CUSTOM_IMAGE_FAMILY_NAME] \
    --dataproc-version=IMAGE_VERSION \
    --customization-script=LOCAL_PATH \
    --zone=ZONE \
    --gcs-bucket=gs://BUCKET_NAME \
    [--no-smoke-test]

必要标志

  • --image-name：自定义映像的输出名称。注意：图片名称必须与正则表达式 [a-z](?:[-a-z0-9]{0,61}[a-z0-9]) 匹配，不得包含下划线或空格，且不得超过 64 个字符。
  • --dataproc-version：要在您的自定义映像中使用的 Dataproc 映像版本。以 x.y.z-os 或 x.y.z-rc-os 格式指定版本，例如“2.0.69-debian10”。
  • --customization-script：脚本的本地路径，该工具将运行此脚本以安装自定义软件包或执行其他自定义操作。此脚本仅在用于创建自定义映像的临时虚拟机上运行。您可以为使用自定义映像创建集群时要执行的其他初始化操作指定不同的初始化脚本。
  • --zone：Compute Engine 可用区，其中 generate_custom_image.py 将在该可用区创建用于创建自定义映像的临时虚拟机。
  • --gcs-bucket：URI，格式为 gs://BUCKET_NAME，指向您的 Cloud Storage 存储桶。generate_custom_image.py 会将日志文件写入此存储桶。

可选标志

  • --family：自定义映像的映像系列。映像系列用于将类似的映像组合在一起，可用于创建集群作为指向系列中最新映像的指针。例如 custom-2-2-debian12。
  • --no-smoke-test：这是一个可选标志，用于禁止对新构建的自定义映像进行冒烟测试。冒烟测试会使用新构建的映像创建 Dataproc 测试集群，运行小型作业，然后在测试结束时删除集群。默认情况下，系统将运行冒烟测试，以验证新构建的自定义映像是否可以创建正常运行的 Dataproc 集群。使用 --no-smoke-test 标志停用此步骤可加快自定义映像构建流程，但不建议使用。
  • --subnet：用于创建用于构建自定义 Dataproc 映像的虚拟机的子网。如果您的项目属于共享 VPC，您必须使用以下格式指定完整的子网网址：projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET。

如需查看其他可选标志的列表，请参阅 GithHub 上的可选参数。

如果 generate_custom_image.py 成功，自定义映像的 imageURI 将在终端窗口输出中显示（完整的 imageUri 以粗体显示如下）：

...
managedCluster:
    clusterName: verify-image-20180614213641-8308a4cd
    config:
      gceClusterConfig:
        zoneUri: ZONE
      masterConfig:
        imageUri: https://www.googleapis.com/compute/beta/projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME
...

INFO:__main__:Successfully built Dataproc custom image: CUSTOM_IMAGE_NAME
INFO:__main__:

#####################################################################
  WARNING: DATAPROC CUSTOM IMAGE 'CUSTOM_IMAGE_NAME'
           WILL EXPIRE ON 2018-07-14 21:35:44.133000.
#####################################################################

自定义映像版本标签（高级用法）

使用 Dataproc 的标准自定义映像工具时，该工具会在创建的自定义映像上设置 goog-dataproc-version 标签。该标签反映了 Dataproc 用于管理映像上的软件的功能和协议。

高级用法：如果您使用自己的进程创建自定义 Dataproc 映像，则必须将 goog-dataproc-version 标签手动添加到自定义映像，如下所示：

  1. 从用于创建自定义映像的基础 Dataproc 映像中提取 goog-dataproc-version 标签。

    gcloud compute images describe ${BASE_DATAPROC_IMAGE} \
    --project cloud-dataproc \
    --format="value(labels.goog-dataproc-version)"

  2. 在自定义映像上设置标签。 

    gcloud compute images add-labels IMAGE_NAME --labels=[KEY=VALUE,...]

使用自定义映像

您可以在创建 Dataproc 集群时指定自定义映像。自定义映像保存在 Cloud Compute 映像中，自创建之日起 365 天内可用于创建 Dataproc 集群（请参阅如何使用过期的自定义映像创建集群，以便在 365 天过期日期后使用自定义映像）。

自定义映像 URI

您将自定义映像的 imageUri 传递给集群创建操作。 该 URI 可以使用以下三种方法之一指定：

  1. 完整 URI：
    https://www.googleapis.com/compute/beta/projects/PROJECT_ID/global/images/`gs://`BUCKET_NAME`
  2. 部分 URI：projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME
  3. 简称：CUSTOM_IMAGE_NAME

自定义映像还可以通过其系列 URI 指定，该 URI 始终会选择映像系列中的最新映像。

  1. 完整 URI：
    https://www.googleapis.com/compute/beta/projects/PROJECT_ID/global/images/family/CUSTOM_IMAGE_FAMILY_NAME/var>
  2. 部分 URI：projects/PROJECT_ID/global/images/family/CUSTOM_IMAGE_FAMILY_NAME

如何查找自定义映像 URI

Google Cloud CLI

运行以下命令可列出自定义映像的名称。

gcloud compute images list

将自定义映像的名称传递到以下命令，以列出自定义映像的 URI (selfLink)。

gcloud compute images describe custom-image-name

输出代码段：

...
name: CUSTOM_IMAGE_NAME
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME
...

控制台

  1. 在 Google Cloud 控制台中打开 Compute Engine→Images 页面，然后点击映像名称。 您可以在 filter images 字段中插入查询，以限制显示的图片数量。
  2. 映像详情页面随即打开。点击 Equivalent REST。
  3. REST 响应列出了有关映像的其他信息，包括 selfLink（即映像 URI）。
    {
  ...
  "name": "my-custom-image",
  "selfLink": "projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME",
  "sourceDisk": ...,
  ...
}

使用自定义映像创建集群

使用 gcloud CLI、Dataproc API 或 Google Cloud 控制台创建集群，该集群包含使用自定义映像的主节点和工作器节点。

gcloud CLI

使用带有 --image 标志的 dataproc clusters create 命令来使用自定义映像创建 Dataproc 集群。

例如： 
gcloud dataproc clusters create CLUSTER-NAME \
    --image=CUSTOM_IMAGE_URI \
    --region=REGION \
    ... other flags ...

REST API

在 cluster.create API 请求所包含的 masterConfig、workerConfig 和 secondaryWorkerConfig 对象（若适用）的 InstanceGroupConfig.imageUri 字段中，您可以通过指定自定义映像 URI 来创建使用自定义映像的集群。

示例：使用 REST 请求创建一个使用自定义映像的标准 Dataproc 集群（包含一个主节点，两个工作器节点）。

POST /v1/projects/PROJECT_ID/regions/REGION/clusters/
{
  "clusterName": "CLUSTER_NAME",
  "config": {
    "masterConfig": {
      "imageUri": "projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME"
    },
    "workerConfig": {
      "imageUri": "projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME"
    }
  }
}

控制台

  1. 打开 Dataproc 创建集群页面。选中设置集群面板。
  2. 在版本控制部分中，点击更改。选择自定义映像标签页，选择要用于 Dataproc 集群的自定义映像，然后点击选择。 集群的虚拟机可配置选定的自定义映像。

使用自定义映像替换 Dataproc 集群属性

您可以使用自定义映像覆盖在创建集群期间设置的集群属性。如果您使用自定义映像创建集群，并且集群创建操作设置的属性值与自定义映像设置的值不同，则自定义映像设置的属性值将优先。

如需使用自定义映像设置集群属性，请执行以下操作：

  1. 在自定义映像自定义脚本中，在 /etc/google-dataproc 中创建一个 dataproc.custom.properties 文件，然后在该文件中设置集群属性值。

    • 示例 dataproc.custom.properties 文件：
    dataproc.conscrypt.provider.enable=VALUE
dataproc.logging.stackdriver.enable=VALUE
    • 用于替换两个集群属性的自定义脚本文件创建代码段示例：
    cat <<EOF >/etc/google-dataproc/dataproc.custom.properties
dataproc.conscrypt.provider.enable=true
dataproc.logging.stackdriver.enable=false
EOF

如何创建具有过期自定义映像的集群

默认情况下，自定义映像会在其创建之日起 365 天后到期。 您可以通过完成以下步骤来创建使用过期自定义映像的集群。

  1. 尝试使用过期的自定义映像或将在 10 天内过期的自定义映像创建 Dataproc 集群。

    gcloud dataproc clusters create CLUSTER-NAME \
    --image=CUSTOM-IMAGE-NAME \
    --region=REGION \
    ... other flags ...

  2. gcloud CLI 将发出包含集群 dataproc:dataproc.custom.image.expiration.token 属性名称和令牌值的错误消息。

dataproc:dataproc.custom.image.expiration.token=TOKEN_VALUE

将 TOKEN_VALUE 字符串复制到剪贴板。

  1. 使用 gcloud CLI 再次创建 Dataproc 集群，将复制的 TOKEN_VALUE 添加为集群属性。

    gcloud dataproc clusters create CLUSTER-NAME \
    --image=CUSTOM-IMAGE-NAME \
    --properties=dataproc:dataproc.custom.image.expiration.token=TOKEN_VALUE \
    --region=REGION \
    ... other flags ...

使用自定义映像创建集群应会成功。