建立 Dataproc 自訂映像檔

您可以透過含有預先安裝套件的自訂映像檔建立 Dataproc 叢集。本頁說明如何建立自訂映像檔，並在 Dataproc 叢集上安裝。

使用注意事項和限制

  • 自訂映像檔的生命週期：為確保叢集收到最新的服務更新和錯誤修正，使用自訂映像檔建立叢集時，必須在自訂映像檔建立日期起算的 365 天內完成。請注意，使用自訂映像檔建立的現有叢集可以無限期執行。

    如要使用特定自訂映像檔建立叢集，且時間超過 365 天，可能需要使用自動化功能。詳情請參閱「使用過期的自訂映像檔建立叢集」。

  • 僅限 Linux：本文的操作說明僅適用於 Linux 作業系統。未來推出的 Dataproc 版本可能會支援其他作業系統。

  • 支援的基本映像檔：建立自訂映像檔時，必須從 Dataproc 基本映像檔開始。支援下列基本映像檔： Debian、Rocky Linux 和 Ubuntu。

    • 基礎映像檔適用情形：在Dataproc 版本資訊中發布的新映像檔，在發布日期後一週內，都無法做為自訂映像檔的基礎。

  • 使用選用元件：

    無論自訂映像檔使用哪個基本映像檔，您都必須在建立叢集時列出或選取選用元件。

    範例：Google Cloud CLI 叢集建立指令：

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

    建立叢集時，如果未指定元件名稱，系統會刪除選用元件，包括任何自訂 OS 套件和設定。

  • 使用代管自訂映像檔：如果您使用其他專案中代管的自訂映像檔，專案中的 Dataproc 服務代理程式服務帳戶必須對主專案中的映像檔具有 compute.images.get 權限。如要授予這項權限，請將主機映像檔的 roles/compute.imageUser 角色授予專案的 Dataproc 服務代理人服務帳戶 (請參閱「在機構內共用自訂映像檔」)。

  • 使用安全啟動 MOK (機器擁有者金鑰) Secret：如要使用 Dataproc 自訂映像檔啟用安全啟動，請按照下列步驟操作：

    1. 啟用 Secret Manager API (secretmanager.googleapis.com)。Dataproc 會使用 Secret Manager 服務產生及管理金鑰配對。

    2. 產生自訂映像檔時，請將 --service-account="SERVICE_ACCOUNT" 旗標新增至 generate_custom_image.py 指令。注意：您必須在專案中授予服務帳戶 Secret Manager 檢視者角色 (roles/secretmanager.viewer)，並在公開和私密密鑰中授予 Secret Manager 存取者角色 (roles/secretmanager.secretAccessor)。

      如需更多資訊和範例，請參閱 GitHub 上的 GoogleCloudDataproc/custom-images 存放區中 examples/secure-boot 目錄內的 README.md 和其他檔案。

      如要停用安全啟動：預設情況下，Dataproc 自訂映像檔指令碼會在從 Dataproc 叢集執行時，使用 Secret Manager 產生及管理金鑰配對。如果您不想搭配自訂映像檔使用安全啟動，請在產生自訂映像檔時，將 --trusted-cert="" (空旗標值) 加入 generate_custom_image.py 指令。

事前準備

請務必先設定專案，再產生自訂圖片。

設定專案

  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. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init

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

    Go to project selector

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

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

    Enable the APIs

  11. Install the Google Cloud CLI.

  12. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init
  14. 安裝 Python 3.11 以上版本
  15. 準備自訂指令碼，安裝自訂套件和/或更新設定，例如： 
      #! /usr/bin/bash
  apt-get -y update
  apt-get install python-dev
  apt-get install python-pip
  pip install numpy

    16. 在專案中建立 Cloud Storage bucket

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

      Go to Buckets

    2. Click Create.
    3. On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
      1. In the Get started section, do the following:
        • Enter a globally unique name that meets the bucket naming requirements.
        • To add a bucket label, expand the Labels section (), click Add label, and specify a key and a value for your label.
      2. In the Choose where to store your data section, do the following:
        1. Select a Location type.
        2. Choose a location where your bucket's data is permanently stored from the Location type drop-down menu.
        3. To set up cross-bucket replication, select Add cross-bucket replication via Storage Transfer Service and follow these steps:

          Set up cross-bucket replication

          1. In the Bucket menu, select a bucket.

          2. In the Replication settings section, click Configure to configure settings for the replication job.

            The Configure cross-bucket replication pane appears.

            • To filter objects to replicate by object name prefix, enter a prefix that you want to include or exclude objects from, then click Add a prefix.
            • To set a storage class for the replicated objects, select a storage class from the Storage class menu. If you skip this step, the replicated objects will use the destination bucket's storage class by default.
            • Click Done.
      3. In the Choose how to store your data section, do the following:
        1. Select a default storage class for the bucket or Autoclass for automatic storage class management of your bucket's data.
        2. To enable hierarchical namespace, in the Optimize storage for data-intensive workloads section, select Enable hierarchical namespace on this bucket.
      4. In the Choose how to control access to objects section, select whether or not your bucket enforces public access prevention, and select an access control method for your bucket's objects.
      5. In the Choose how to protect object data section, do the following:
        • Select any of the options under Data protection that you want to set for your bucket.
          • To enable soft delete, click the Soft delete policy (For data recovery) checkbox, and specify the number of days you want to retain objects after deletion.
          • To set Object Versioning, click the Object versioning (For version control) checkbox, and specify the maximum number of versions per object and the number of days after which the noncurrent versions expire.
          • To enable the retention policy on objects and buckets, click the Retention (For compliance) checkbox, and then do the following:
            • To enable Object Retention Lock, click the Enable object retention checkbox.
            • To enable Bucket Lock, click the Set bucket retention policy checkbox, and choose a unit of time and a length of time for your retention period.
        • To choose how your object data will be encrypted, expand the Data encryption section (), and select a Data encryption method.
    4. Click Create.

    生成自訂圖像

    您可以使用 Python 程式 generate_custom_image.py 建立 Dataproc 自訂映像檔。

    運作方式

    generate_custom_image.py 程式會使用指定的 Dataproc 基本映像檔啟動臨時的 Compute Engine VM 執行個體，然後在 VM 執行個體中執行自訂指令碼，安裝自訂套件和/或更新設定。自訂指令碼完成後，系統會關閉 VM 執行個體，並從 VM 執行個體磁碟建立 Dataproc 自訂映像檔。建立自訂映像檔後，臨時 VM 就會遭刪除。自訂映像檔會儲存於系統之中，可以用來建立 Dataproc 叢集。

    generate_custom_image.py 程式會使用 gcloud CLI 在 Compute Engine 上執行多步驟工作流程。

    執行程式碼

    您可以在 GitHub 的「Dataproc 自訂映像檔」中建立檔案分支或複製檔案。

    接著，執行 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：自訂映像檔的輸出名稱。

    • --dataproc-version：自訂映像檔中使用的 Dataproc 映像檔版本。使用 x.y.z-os 或 x.y.z-rc-os 格式指定版本， 例如「2.0.69-debian10」。

    • --customization-script：指令碼的本機路徑；工具將會執行此指令碼來安裝您的自訂套件或執行其他自訂內容。此指令碼只會在用來建立自訂映像檔的臨時 VM 上，以 Linux 開機指令碼的形式執行。您可以針對使用自訂映像檔建立叢集時想要執行的其他初始化動作，指定不同的初始化指令碼。

      跨專案映像檔：如果自訂映像檔用於在不同專案中建立叢集，映像檔中儲存的 gcloud 或 gsutil 指令快取可能會導致錯誤。如要避免這個問題，請在自訂指令碼中加入下列指令，清除快取憑證。

      rm -r /root/.gsutil /root/.config/gcloud

    • --zone：Compute Engine 區域，generate_custom_image.py 將會在此區域內建立臨時 VM，以用來建立您的自訂映像檔。

    • --gcs-bucket：URI，格式為 gs://BUCKET_NAME，指向您的 Cloud Storage 值區。generate_custom_image.py 會將記錄檔寫入這個 bucket。

    選用旗標

    • --family：自訂圖片的圖片系列。映像檔系列用於將類似的映像檔歸類在一起，並可在建立叢集時做為指標，指向系列中最新的映像檔。例如：custom-2-2-debian12。
    • --no-smoke-test：此為選用標記，可停用針對新建立的自訂映像檔進行的冒煙測試。冒煙測試會使用新建構的映像檔來建立 Dataproc 測試叢集、執行小型工作，然後在測試結尾刪除叢集。系統依預設會執行冒煙測試，以確認新建構的自訂映像檔能夠建立可作用的 Dataproc 叢集。使用 --no-smoke-test 旗標停用此步驟可加速自訂映像檔建構程序，但不建議您這樣做。
    • --subnet：用於建立 VM 的子網路，該 VM 會建構自訂 Dataproc 映像檔。如果專案屬於共用虛擬私有雲，請務必指定完整子網路網址，格式如下：projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET。

    • --optional-components：只有在使用 2.3 以上版本的基礎映像檔時，才能使用這個標記。選用元件清單，例如 SOLR、RANGER、TRINO、DOCKER、FLINK、HIVE_WEBHCAT、ZEPPELIN、HUDI、ICEBERG 和 PIG (PIG 可做為映像檔版本 2.3 以上的選用元件)，可安裝在映像檔中。

      範例：Google Cloud CLI 叢集建立指令：

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

    如要查看可用的選用標記清單，請參閱 GitHub 上的「Optional Arguments」(選用引數)。

    如果 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 指定映像檔，系統一律會選擇映像檔系列中最新的映像檔。

    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. 「Images details」(映像檔詳細資料) 頁面隨即開啟。按一下「對等 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

    使用 dataproc clusters create 指令搭配 --image 標記，以透過自訂映像檔建立 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。

    範例：使用自訂映像檔建立標準 Dataproc 叢集 (一個主要節點及兩個工作站節點) 的 REST 要求。

    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. 在「版本控管」部分，按一下「變更」。 選取「Custom Image」分頁標籤，選擇要用於 Dataproc 叢集的自訂映像檔，然後按一下「Select」。 系統將使用選取的自訂映像檔來佈建叢集的 VM。

    使用自訂映像檔覆寫 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

    此時應該已成功使用自訂映像檔建立叢集。