使用開機後指令碼

本指南說明如何在 Colab Enterprise 中使用開機後指令碼。本指南也會說明如何設定環境變數，以搭配啟動後指令碼使用。

總覽

您可以透過開機後指令碼，在 Colab Enterprise 執行階段啟動程序完成後執行工作，例如安裝特定套件，或是對執行階段的 VM 進行特定變更。

如要在 Colab Enterprise 使用開機後指令碼，請在建立執行階段範本時指定開機後指令碼。接著，當您根據該執行階段範本建立執行階段時，開機後指令碼會在啟動程序結束時執行。

開機後指令碼位置

開機後指令碼 URI 可以是下列任一項目：

Cloud Storage URI：例如 gs://BUCKET_NAME/SCRIPT_FILE_NAME。如果開機後指令碼儲存在 Cloud Storage 中，您必須使用已啟用使用者憑證的執行階段。這是因為 Colab Enterprise 會使用您的使用者憑證存取 Cloud Storage bucket。
HTTPS 網址：例如： https://example.com/FOLDER_NAME/SCRIPT_FILE_NAME。使用 Google Cloud 控制台建立執行階段範本時，系統不支援使用 HTTPS 網址。

執行開機指令碼後的操作

您可以指定開機後指令碼的行為。請參閱下表：

行為	說明
執行一次 (`RUN_ONCE`)	預設值，Colab Enterprise 只會在建立執行階段時執行一次開機後指令碼。
每次啟動時執行 (`RUN_EVERY_START`)	每次啟動後，Colab Enterprise 都會執行開機後指令碼。舉例來說，如果閒置關機功能停止執行階段，當執行階段重新啟動時，Colab Enterprise 會再次執行開機後指令碼。
每次啟動時下載並執行 (`DOWNLOAD_AND_RUN_EVERY_START`)	每次啟動時，Colab Enterprise 都會從來源重新下載開機後指令碼，然後執行該指令碼。

環境變數

您可以在執行階段範本中指定環境變數，並在啟動後指令碼中參照這些變數。

舉例來說，您可以使用環境變數設定配額專案。您可以使用 GOOGLE_CLOUD_QUOTA_PROJECT 將配額專案設為特定專案 ID，這是用戶端程式庫中常用的變數。 Google Cloud

如要搭配環境變數使用開機後指令碼，請參閱「建立含有開機後指令碼和環境變數的執行階段範本」。

追蹤變更並復原開機後指令碼

如要追蹤開機後指令碼的變更，並還原特定版本的開機後指令碼，請將開機後指令碼儲存在已啟用物件版本管理的 Cloud Storage 值區中。物件版本管理功能會將刪除的物件保留為非現行版本，這些物件仍可存取，直到明確移除為止。

如要指定開機後指令碼版本，請在建立執行階段範本時，將 #GENERATION_NUMBER 新增至開機後指令碼的 URI，例如 gs://BUCKET_NAME/FOLDER_NAME/FILE_NAME.py#GENERATION_NUMBER。如要進一步瞭解物件版本管理和產生編號，請參閱「物件版本管理」。

使用 Google Cloud 控制台建立執行階段範本時，系統不支援為開機後指令碼指定產生版本編號。

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Dataform, and Compute Engine APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Dataform, and Compute Engine APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

必要的角色

如要取得在 Colab Enterprise 中建立執行階段範本所需的權限，請要求管理員授予您專案的 Colab Enterprise 管理員 (roles/aiplatform.colabEnterpriseAdmin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

一或多個必要角色包含 dataform.repositories.list 權限。在專案中獲授 dataform.repositories.list 權限或「程式碼建立者」(roles/dataform.codeCreator) 角色的使用者，可以使用 Dataform API 或 Dataform 指令列介面 (CLI)，列出該專案中的程式碼資產名稱。使用 BigQuery Studio 的非管理員只能查看自己建立或與自己共用的程式碼資產。

建立使用開機後指令碼的執行階段範本

如要建立使用開機後指令碼的執行階段範本，可以使用 Google Cloud 控制台、Google Cloud CLI 或 REST API。

控制台

如要建立使用開機後指令碼的執行階段範本，請按照下列步驟操作：

前往 Google Cloud 控制台的 Colab Enterprise「執行階段範本」頁面。

前往「執行階段範本」
按一下「新增範本」。

系統會顯示「建立新的執行階段範本」對話方塊。
在「執行階段基本資訊」部分，輸入「顯示名稱」。
在「Region」(區域) 選單中，選取要建立執行階段範本的區域。
在「Environment」(環境) 區段的「Post-startup script」(開機後指令碼) 欄位中，按一下「Browse」(瀏覽)，然後前往 Cloud Storage 中的開機後指令碼。詳情請參閱「啟動後指令碼位置」。
在開機後指令碼網址下方，選取開機後指令碼的行為。預設行為為「執行一次」。詳情請參閱「啟動後指令碼行為」。
在「網路和安全性」部分，確認已選取「啟用使用者憑證」。
完成對話方塊的其餘部分，然後按一下「建立」。

執行階段範本會顯示在「執行階段範本」分頁的清單中。

gcloud

使用下列任何指令資料之前，請先替換以下項目：

DISPLAY_NAME：執行階段範本的顯示名稱。
PROJECT_ID：您的專案 ID。
REGION：您要執行階段範本的區域。
POST_STARTUP_SCRIPT_URI：開機後指令碼的 URI。詳情請參閱「啟動後指令碼位置」。
POST_STARTUP_SCRIPT_BEHAVIOR：開機後指令碼的行為。請參閱「執行開機指令碼後的操作」。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" \
    --project=PROJECT_ID \
    --region=REGION \
    --machine-type=e2-standard-4 \
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI \
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR

Windows (PowerShell)

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" `
    --project=PROJECT_ID `
    --region=REGION `
    --machine-type=e2-standard-4 `
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI `
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR

Windows (cmd.exe)

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" ^
    --project=PROJECT_ID ^
    --region=REGION ^
    --machine-type=e2-standard-4 ^
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI ^
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR

如要進一步瞭解如何透過指令列建立執行階段範本，請參閱 gcloud CLI 說明文件。

REST

使用任何要求資料之前，請先修改下列項目的值：

REGION：您要執行階段範本的區域。
PROJECT_ID：您的專案 ID。
DISPLAY_NAME：執行階段範本的顯示名稱。
POST_STARTUP_SCRIPT_URI：開機後指令碼的 URI。詳情請參閱「啟動後指令碼位置」。
POST_STARTUP_SCRIPT_BEHAVIOR：開機後指令碼的行為。請參閱「執行開機指令碼後的操作」。

HTTP 方法和網址：

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates

JSON 要求內文：

{
  "displayName": "DISPLAY_NAME",
  "machineSpec": {
    "machineType": "e2-standard-4"
  },
  softwareConfig: {
    postStartupScriptConfig: {
      postStartupScriptUrl: "POST_STARTUP_SCRIPT_URI",
      postStartupScriptBehavior: "POST_STARTUP_SCRIPT_BEHAVIOR"
    },
  },
  "networkSpec": {
    "enableInternetAccess": true
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates"

PowerShell

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates" | Select-Object -Expand Content

如果成功，回應主體會包含 Operation 的執行個體。

詳情請參閱 notebookRuntimeTemplates.create REST API 說明文件。

建立執行階段

建立使用開機後指令碼的執行階段範本後，請根據該範本建立執行階段。執行階段會啟動，並根據指定的行為執行開機後指令碼。請參閱「建立執行階段」。

建立含有開機後指令碼和環境變數的執行階段範本

如要建立使用開機後指令碼和環境變數的執行階段範本，可以使用 Google Cloud 控制台、Google Cloud CLI 或 REST API。

控制台

如要建立使用開機後指令碼和環境變數的執行階段範本，請按照下列步驟操作：

前往 Google Cloud 控制台的 Colab Enterprise「執行階段範本」頁面。

前往「執行階段範本」
按一下「新增範本」。

系統會顯示「建立新的執行階段範本」對話方塊。
在「執行階段基本資訊」部分，輸入「顯示名稱」。
在「Region」(區域) 選單中，選取要建立執行階段範本的區域。
在「Environment」(環境) 區段的「Post-startup script」(開機後指令碼) 欄位中，按一下「Browse」(瀏覽)，然後前往 Cloud Storage 中的開機後指令碼。詳情請參閱「啟動後指令碼位置」。
在開機後指令碼網址下方，選取開機後指令碼的行為。預設行為為「執行一次」。詳情請參閱「啟動後指令碼行為」。
如要新增環境變數，請按一下「Add env variable」(新增環境變數)，然後輸入「Key」(鍵) 和「Value」(值) 配對。如要新增更多環境變數，請重複這個步驟。
在「網路和安全性」部分，確認已選取「啟用使用者憑證」。
完成對話方塊中的其餘步驟，然後按一下「建立」。

執行階段範本會顯示在「執行階段範本」分頁的清單中。

gcloud

使用下列任何指令資料之前，請先替換以下項目：

DISPLAY_NAME：執行階段範本的顯示名稱。
PROJECT_ID：您的專案 ID。
REGION：您要執行階段範本的區域。
POST_STARTUP_SCRIPT_URI：開機後指令碼的 URI。詳情請參閱「啟動後指令碼位置」。
POST_STARTUP_SCRIPT_BEHAVIOR：開機後指令碼的行為。請參閱「執行開機指令碼後的操作」。
ENV_VARIABLE_NAME：要為執行階段設定的環境變數名稱。
ENV_VARIABLE_VALUE：要為執行階段設定的環境變數值。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" \
    --project=PROJECT_ID \
    --region=REGION \
    --machine-type=e2-standard-4 \
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI \
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR \
    --set-env-vars=ENV_VARIABLE_NAME=ENV_VARIABLE_VALUE

Windows (PowerShell)

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" `
    --project=PROJECT_ID `
    --region=REGION `
    --machine-type=e2-standard-4 `
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI `
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR `
    --set-env-vars=ENV_VARIABLE_NAME=ENV_VARIABLE_VALUE

Windows (cmd.exe)

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" ^
    --project=PROJECT_ID ^
    --region=REGION ^
    --machine-type=e2-standard-4 ^
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI ^
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR ^
    --set-env-vars=ENV_VARIABLE_NAME=ENV_VARIABLE_VALUE

如要進一步瞭解如何透過指令列建立執行階段範本，請參閱 gcloud CLI 說明文件。

REST

使用任何要求資料之前，請先修改下列項目的值：

REGION：您要執行階段範本的區域。
PROJECT_ID：您的專案 ID。
DISPLAY_NAME：執行階段範本的顯示名稱。
POST_STARTUP_SCRIPT_URI：開機後指令碼的 URI。詳情請參閱「啟動後指令碼位置」。
POST_STARTUP_SCRIPT_BEHAVIOR：開機後指令碼的行為。請參閱「執行開機指令碼後的操作」。
ENV_VARIABLE_NAME：要為執行階段設定的環境變數名稱。
ENV_VARIABLE_VALUE：要為執行階段設定的環境變數值。

HTTP 方法和網址：

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates

JSON 要求內文：

{
  "displayName": "DISPLAY_NAME",
  "machineSpec": {
    "machineType": "e2-standard-4"
  },
  softwareConfig: {
    postStartupScriptConfig: {
      postStartupScriptUrl: "POST_STARTUP_SCRIPT_URI",
      postStartupScriptBehavior: "POST_STARTUP_SCRIPT_BEHAVIOR"
    },
    "env": [
      {
        "name": "ENV_VARIABLE_NAME",
        "value": "ENV_VARIABLE_VALUE"
      }
    ]
  },
  "networkSpec": {
    "enableInternetAccess": true
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates"

PowerShell

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates" | Select-Object -Expand Content

如果成功，回應主體會包含 Operation 的執行個體。

詳情請參閱 notebookRuntimeTemplates.create REST API 說明文件。

建立執行階段

最佳做法

在 Colab Enterprise 中使用開機後指令碼時，請考慮下列最佳做法：

控管執行階段範本的存取權：為避免開機後指令碼設定遭到不當變更，請使用 IAM 角色和權限，控管哪些使用者可以建立及更新執行階段範本。
控管指令碼存取權：為避免有人對啟動後指令碼檔案進行不必要的變更，請使用 IAM 角色和權限，控管指令碼儲存所在 Cloud Storage bucket 的存取權。
使用物件版本管理：如要追蹤開機後指令碼的變更，並確保執行階段範本使用特定版本的指令碼，請將開機後指令碼儲存在已啟用物件版本管理的 Cloud Storage bucket 中。然後在建立執行階段範本時，將產生號碼納入指令碼路徑。例如：gs://BUCKET_NAME/OBJECT_NAME1#GENERATION_NUMBER1詳情請參閱「追蹤啟動後指令碼的變更並復原」。
防止資料外洩：如果貴機構有這項需求，可以使用 VPC Service Controls 防止資料外洩。

限制

在 Colab Enterprise 中使用開機後指令碼時，請注意下列限制：

如要根據包含開機後指令碼且已啟用 EUC 的執行階段範本建立執行階段，您必須是該執行階段的擁有者。舉例來說，管理員無法使用 REST API 為其他使用者建立執行階段，並使用開機後指令碼。
系統不支援透過啟動後指令碼傳遞環境變數。您必須按照本指南所述，在軟體設定中指定環境變數。
如要使用 Cloud Storage 中的開機後指令碼，您必須使用已啟用使用者憑證的執行階段，且使用者憑證必須有權存取 Cloud Storage bucket。
如果您使用 Google Cloud 控制台建立執行階段範本，啟動後指令碼必須位於 Cloud Storage 中。使用 Google Cloud 控制台建立執行階段範本時，系統不支援其他位置的開機後指令碼。
使用 Google Cloud 控制台建立執行階段範本時，系統不支援為開機後指令碼指定產生號碼。

後續步驟

建立執行階段並連線。
如要管理執行階段，請參閱「管理執行階段」。
進一步瞭解執行階段和執行階段範本。