初始化動作

建立 Dataproc 叢集時，您可以在執行檔或指令碼中指定初始化動作，讓 Dataproc 在叢集設定完成後立即在 Dataproc 叢集中的所有節點上執行。初始化動作通常會設定工作依附元件 (例如安裝 Python 套件)，讓您在工作執行時不必安裝依附元件，就能將該工作提交給叢集。

您可以在下列位置找到初始化動作指令碼範例： 注意：Google 不支援這些範例。

重要考量事項和指南

  • 請勿建立參照 gs://goog-dataproc-initialization-actions-REGION 公開值區中的初始化動作的正式叢集。這些指令碼是做為參考導入作業。這些指令碼會與持續進行的 GitHub 存放區變更同步，因此更新這些指令碼可能會導致叢集建立作業中斷。請改為將初始化動作從公開值區複製到版本化 Cloud Storage 值區資料夾，如以下範例所示：

    REGION=COMPUTE_REGION
gcloud storage cp gs://goog-dataproc-initialization-actions-${REGION}/cloud-sql-proxy/cloud-sql-proxy.sh \
    gs://my-bucket/cloud-sql-proxy/v1.0/cloud-sql-proxy.sh
    接著，透過參照 Cloud Storage 中的副本建立叢集：
    gcloud dataproc clusters create CLUSTER_NAME \
    --region=${REGION} \
    --initialization-actions=gs://my-bucket/cloud-sql-proxy/v1.0/cloud-sql-proxy.sh \
    ...other flags...

  • 叢集建立期間，初始化動作會在每個節點上依序執行。在對叢集進行調度資源或自動調度資源時，這些指令也會在每個新增的節點上執行。

  • 更新初始化動作時 (例如，將 Cloud Storage 初始化動作同步至公開值區或 GitHub 存放區初始化動作的變更)，請建立新的資料夾 (建議使用版本名稱) 來接收更新的初始化動作。相反地，如果您在原地更新初始化動作，新節點 (例如由自動調整器新增的節點) 將執行更新後的原地初始化動作，而非在現有節點上執行的舊版初始化動作。這種初始化動作差異可能會導致叢集節點不一致或損壞。

  • 初始化動作會以 root 使用者的身分執行，您不必使用 sudo。

  • 在初始化動作中使用絕對路徑。

  • 在初始化動作中使用工作行，指明如何解讀指令碼 (例如 #!/bin/bash 或 #!/usr/bin/python)。

  • 如果初始化動作以非零的結束代碼結尾，叢集建立作業將會回報「錯誤」狀態。如要對初始化動作進行偵錯，請使用 SSH 連線至叢集的 VM 執行個體，然後檢查記錄。在您修正初始化動作的問題之後，請刪除該叢集，然後再重新建立。

  • 如果您只使用內部 IP 位址建立 Dataproc 叢集，就無法利用初始化動作存取 github.com，除非您先設定路徑來引導流量通過 Cloud NAT 或 Cloud VPN。如果您無法存取網際網路，可以啟用私人 Google 存取權，並且將工作依附元件放置在 Cloud Storage 中；叢集節點可以利用內部 IP 從 Cloud Storage 下載依附元件。

  • 您可以使用 Dataproc 自訂映像檔來設定工作依附元件，而不必透過初始化動作來進行。

  • 初始化處理：

    • 2.0 版前圖像叢集：
      • Master：如要讓初始化動作在主節點上執行，以便將檔案寫入 HDFS，必須等到 HDFS 可寫入 (也就是 HDFS 已退出安全模式，且至少有兩個 HDFS 資料節點已加入) 後，才會啟動主節點初始化動作。
      • Worker：如果您將 dataproc:dataproc.worker.custom.init.actions.mode 叢集屬性設為 RUN_BEFORE_SERVICES，每個 worker 都會在啟動 HDFS 資料節點和 YARN nodemanager 守護程序之前，執行初始化動作。由於 Dataproc 必須等到 HDFS 可寫入，才會執行主機初始化動作 (這項作業需要執行 2 個 HDFS 資料節點守護程)，因此設定這個屬性可能會增加叢集建立時間。

    • 2.0 以上圖片叢集：

      • Master：主節點初始化動作可能會在 HDFS 可寫入前執行。如果您執行初始化動作，將檔案暫存至 HDFS 或依賴 HDFS 相關服務 (例如 Ranger) 的可用性，請將 dataproc.master.custom.init.actions.mode 叢集屬性設為 RUN_AFTER_SERVICES。注意：由於這項屬性設定可能會增加叢集建立時間 (請參閱 2.0 版前圖像叢集 worker的叢集建立延遲說明)，因此請僅在必要時使用 (一般做法是依賴此屬性的預設 RUN_BEFORE_SERVICES 設定)。
      • Worker：dataproc:dataproc.worker.custom.init.actions.mode 叢集屬性已設為 RUN_BEFORE_SERVICES，且在建立叢集時無法傳遞至叢集 (您無法變更屬性設定)。每個 worker 都會在啟動 HDFS 資料節點和 YARN 節點管理器守護程序之前，執行初始化動作。由於 Dataproc 不會在執行主要初始化動作前等待 HDFS 可寫入，因此主要和工作站初始化動作會並行執行。

    • 建議：

      • 使用中繼資料判斷節點的角色，以便有條件地在節點上執行初始化動作 (請參閱「使用叢集中繼資料」)。
      • 將初始化動作的複本分支至 Cloud Storage 值區，以確保穩定性 (請參閱「如何使用初始化動作」)。
      • 從網際網路下載時新增重試，以協助穩定初始化動作。

使用初始化動作

無論您建立叢集的方法是下列何者，都可以指定叢集的初始化動作：

Gcloud 指令

當您利用 gcloud dataproc clusters create 指令建立叢集時，請用 --initialization-actions 標記來指定初始化執行檔或指令碼的 Cloud Storage 位置 (URI)，並以半形逗號分隔。注意：系統不支援在 Cloud Storage 位置 URI 中，初始「gs://」後方連續出現多個「/」的情況，例如「gs://bucket/my//object//name」。執行 gcloud dataproc clusters create --help 即可取得指令資訊。

gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --initialization-actions=Cloud Storage URI(s) (gs://bucket/...) \
    --initialization-action-timeout=timeout-value (default=10m) \
    ... other flags ...
注意事項：
  • 使用 --initialization-action-timeout 標記指定初始化動作的逾時期限，預設的逾時期限為 10 分鐘。如果初始化可執行檔或指令碼未在逾時期間結束前完成，Dataproc 就會取消初始化動作。
  • 使用 dataproc:dataproc.worker.custom.init.actions.mode 叢集屬性，在啟動節點管理員和資料節點 Daemon 之前，在主要工作站上執行初始化動作。

REST API

請在 ClusterConfig.initializationActions 陣列中，指定一或多個指令碼或執行檔，做為 clusters.create API 要求的一部分。

示例

POST /v1/projects/my-project-id/regions/us-central1/clusters/
{
  "projectId": "my-project-id",
  "clusterName": "example-cluster",
  "config": {
    "configBucket": "",
    "gceClusterConfig": {
      "subnetworkUri": "default",
      "zoneUri": "us-central1-b"
    },
    "masterConfig": {
      "numInstances": 1,
      "machineTypeUri": "n1-standard-4",
      "diskConfig": {
        "bootDiskSizeGb": 500,
        "numLocalSsds": 0
      }
    },
    "workerConfig": {
      "numInstances": 2,
      "machineTypeUri": "n1-standard-4",
      "diskConfig": {
        "bootDiskSizeGb": 500,
        "numLocalSsds": 0
      }
    },
    "initializationActions": [
      {
        "executableFile": "gs://cloud-example-bucket/my-init-action.sh"
      }
    ]
  }
}

控制台

  • 開啟 Dataproc「Create a cluster」(建立叢集) 頁面，然後選取「Customize cluster」(自訂叢集) 面板。
  • 在「Initialization actions」(初始化動作) 部分，請在「Executable file」(可執行檔案) 欄位中輸入每個初始化動作的 Cloud Storage 值區位置。按一下「Browse」，開啟 Google Cloud 控制台的 Cloud Storage「Browser」頁面，選取指令碼或可執行檔案。按一下「新增初始化動作」，即可新增各個檔案。

    • 將引數傳送給初始化動作

    Dataproc 會為叢集中執行的執行個體設定特殊中繼資料值。您可以設定自己的自訂中繼資料，以便將引數傳遞至初始化動作。

    gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --initialization-actions=Cloud Storage URI(s) (gs://bucket/...) \
    --metadata=name1=value1,name2=value2... \
    ... other flags ...

    初始化動作可以讀取中繼資料值，如下所示：

    var1=$(/usr/share/google/get_metadata_value attributes/name1)

    節點選取

    如果您想將初始化動作限制為主節點、驅動程式或工作節點，可以將簡單的節點選取邏輯新增至可執行檔或指令碼。

    ROLE=$(/usr/share/google/get_metadata_value attributes/dataproc-role)
if [[ "${ROLE}" == 'Master' ]]; then
  ... master specific actions ...
else if [[ "${ROLE}" == 'Driver' ]]; then
  ... driver specific actions ...
else
  ... worker specific actions ...
fi

    暫存二進位檔

    常見的叢集初始化情況是將工作二進位檔暫存在叢集，這樣您就不必在每次提交工作時暫存二進位檔。舉例來說，假設下列初始化指令碼儲存在 gs://my-bucket/download-job-jar.sh 中，也就是 Cloud Storage 值區位置：

    #!/bin/bash
ROLE=$(/usr/share/google/get_metadata_value attributes/dataproc-role)
if [[ "${ROLE}" == 'Master' ]]; then
  gcloud storage cp gs://my-bucket/jobs/sessionalize-logs-1.0.jar home/username
fi

    這個指令碼的位置可傳遞至 gcloud dataproc clusters create 指令：

    gcloud dataproc clusters create my-dataproc-cluster \
    --region=${REGION} \
    --initialization-actions=gs://my-bucket/download-job-jar.sh

    Dataproc 會在所有節點上執行這個指令碼，並根據指令碼的節點選取邏輯，將 JAR 下載至主節點。提交的工作就能使用預先排定的 JAR 檔案：

    gcloud dataproc jobs submit hadoop \
    --cluster=my-dataproc-cluster \
    --region=${REGION} \
    --jar=file:///home/username/sessionalize-logs-1.0.jar

    初始化動作範例

    您可以在 gs://goog-dataproc-initialization-actions-<REGION>、區域公開的 Cloud Storage 值區，以及 GitHub 存放區中，找到常用及其他的初始化動作指令碼範例。如要分享您的指令碼，請參閱 CONTRIBUTING.md 文件，然後提出提取要求。

    記錄

    系統會為 /var/log/dataproc-initialization-script-X.log 中的每個例項記錄執行每個初始化動作的輸出內容，其中 X 是每個後續初始化動作指令碼的起始於零的索引。舉例來說，如果叢集有兩個初始化動作，輸出內容就會記錄在 /var/log/dataproc-initialization-script-0.log 和 /var/log/dataproc-initialization-script-1.log 中。

    後續步驟

    探索 GitHub 初始化動作。