初始化動作

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

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

GitHub 存放區
Cloud Storage：位於區域性 gs://goog-dataproc-initialization-actions-REGION 公開 bucket 中

重要事項與規範

請勿建立參照 gs://goog-dataproc-initialization-actions-REGION 公開 bucket 中初始化動作的正式版叢集。這些指令碼僅供參考，且會與進行中的 GitHub 存放區變更保持同步，因此更新這些指令碼可能會導致叢集建立作業中斷。請改為將公開 bucket 中的初始化動作複製到已設定版本的 Cloud Storage bucket 資料夾，如下列範例所示：
```
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 初始化動作同步到對公開 bucket 做出的變更，或同步到 GitHub 存放區初始化動作)，請建立新的 (最好是命名為版本) 資料夾，以便接收更新後的初始化動作。如果您改為就地更新初始化動作，新節點 (例如自動配置器新增的節點) 會執行就地更新的初始化動作，而不是在現有節點上執行的舊版初始化動作。這類初始化動作差異可能會導致叢集節點不一致或損毀。
初始化動作會以 root 使用者的身分執行，因此您不需要使用 sudo。
在初始化動作中使用絕對路徑。
在初始化動作中使用工作行，指明指令碼的解讀方式 (例如 #!/bin/bash 或 #!/usr/bin/python)。
如果初始化動作以非零的結束代碼結尾，叢集建立作業將回報「錯誤」狀態。如要對初始化動作進行偵錯，請使用 SSH 連線至叢集的 VM 執行個體，然後檢查記錄檔。在您修正初始化動作的問題之後，請刪除該叢集，然後再重新建立。
如果您只使用內部 IP 位址建立 Dataproc 叢集，就無法利用初始化動作透過網際網路存取 github.com，除非您先設定路徑來引導流量通過 Cloud NAT 或 Cloud VPN。如果您無法存取網際網路，可以啟用 Private Google Access，並將工作依附元件放在 Cloud Storage 中。叢集節點可利用內部 IP 從 Cloud Storage 下載依附元件。
您可以使用 Dataproc 自訂映像檔設定工作依附元件，而不用透過初始化動作來進行。
初始化處理：
- 2.0 之前的映像檔叢集：
  - 主要執行個體：如要允許在主要執行個體上執行的初始化動作將檔案寫入 HDFS，主要節點初始化動作必須等到 HDFS 可寫入時才會啟動 (也就是 HDFS 退出安全模式，且至少有兩個 HDFS DataNode 加入時)。
  - worker：如果您將 dataproc:dataproc.worker.custom.init.actions.mode 叢集屬性設為 RUN_BEFORE_SERVICES，每個 worker 都會先執行初始化動作，再啟動 HDFS datanode 和 YARN nodemanager daemon。由於 Dataproc 要等到 HDFS 可寫入時，才會執行主要初始化動作 (這需要執行 2 個 HDFS datanode Daemon)，因此設定這個屬性可能會增加叢集建立時間。
- 2.0 以上的映像檔叢集：
  - 主要節點：主要節點初始化動作可能會在 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 datanode 和 YARN nodemanager Daemon。由於 Dataproc 不會等待 HDFS 可寫入資料，就執行主要初始化動作，因此主要和 worker 初始化動作會同時執行。
- 建議：
  - 使用中繼資料判斷節點的角色，以便在節點上有條件地執行初始化動作 (請參閱「使用叢集中繼資料」)。
  - 將初始化動作的副本分支到 Cloud Storage bucket，確保穩定性 (請參閱「初始化動作的使用方式」)。
  - 從網際網路下載時新增重試機制，有助於提高初始化動作穩定性。

使用初始化動作

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

透過 Google Cloud 控制台
使用 gcloud CLI
利用 Dataproc clusters.create API，以程式輔助方式建立叢集 (請參閱 NodeInitializationAction)

Gcloud 指令

使用 gcloud dataproc clusters create 指令建立叢集時，請用 --initialization-actions 旗標指定一或多個以半形逗號分隔的初始化執行檔或指令碼 Cloud Storage 位置 (URI)。注意：系統不支援在初始「gs://」後方的 Cloud Storage 位置 URI 中使用多個連續的「/」，例如「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 叢集屬性，在節點管理員和 datanode Daemon 啟動「之前」，對主要 worker 執行初始化動作。

讓 Google Cloud 控制台建構叢集建立要求：您可以在 Dataproc 的「Create a cluster」(建立叢集) 頁面左側面板的底部，按一下「Equivalent REST or command line」(對等 REST 或指令列) 連結，讓 Google Cloud 控制台建構對等 API REST 要求或 gcloud 工具指令 (注意： Google Cloud 控制台不會加入 REST API executionTimeout 欄位或 Google Cloud CLI --initialization-action-timeout 旗標)。

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 bucket 位置。按一下「Browse」(瀏覽)，開啟 Google Cloud 控制台的 Cloud Storage 瀏覽器頁面，選取指令碼或可執行的檔案。接著按一下「Add Initialization Action」(新增初始化動作)，新增每個檔案。

將引數傳遞至初始化動作

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)

節點選取

如果您只想讓主要執行個體、驅動程式或 worker 節點執行初始化動作，可以在執行檔或指令碼中新增簡單的節點選取邏輯。

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 bucket 位置：

#!/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 會對所有節點執行這個指令碼，而根據指令碼的節點選取邏輯，Dataproc 會將 Jar 檔下載到主要執行個體節點。然後，已提交的工作就能使用預先準備的 Jar 檔：

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