使用 Terraform 建立由使用者管理的筆記本執行個體

Vertex AI Workbench 使用者自管筆記本已淘汰。2025 年 4 月 14 日起，我們將停止支援由使用者管理的筆記本，並移除建立這類筆記本執行個體的功能。現有執行個體仍可正常運作，但無法取得修補程式、更新和升級。如要繼續使用 Vertex AI Workbench，建議您將使用者管理的筆記本執行個體遷移至 Vertex AI Workbench 執行個體。

在本教學課程中，您將瞭解如何建立 Terraform 設定檔，並在 Vertex AI 中以服務帳戶模式佈建使用者管理的筆記本執行個體。

請使用下列工具完成本教學課程中的步驟：

• Terraform CLI：Cloud Shell 已預先安裝 Terraform。您不需要另外安裝 Terraform，即可使用 Terraform CLI 指令。

• Cloud Shell 編輯器：使用 Cloud Shell 編輯器建立及管理 Terraform 設定檔，並管理資料夾結構。

• Cloud Shell 終端機：使用 Cloud Shell 終端機執行下列 Terraform CLI 指令，例如 terraform init、terraform plan、terraform apply 和 terraform destroy。

事前準備

使用 Terraform 建構 Vertex AI 資源的基礎架構前，請先設定 Google Cloud 專案和開發環境。本節也會說明如何啟用 Vertex AI API，Terraform 會使用這項 API 與專案中的資源互動。

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.

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

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

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

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

必要的角色

如果您是專案建立者，則您在專案中擁有擁有者 (roles/owner) IAM 角色，其中包含所有必要權限。跳到下一個區段。 如果您不是專案建立者，請繼續閱讀本節內容。

如要取得必要權限，使用 Terraform 建立 Vertex AI Workbench 使用者管理的筆記本執行個體，請要求管理員將專案的下列 IAM 角色授予您：

• Notebooks 管理員 (roles/notebooks.admin) 可在 Vertex AI Workbench 中建立及刪除執行個體。
• 服務帳戶使用者 (roles/iam.serviceAccountUser)，可做為服務帳戶執行作業。本教學課程未指定服務帳戶，因此使用者管理的筆記本執行個體會使用預設的 Compute Engine 服務帳戶。
• 服務使用情形消費者 (roles/serviceusage.serviceUsageConsumer)：可檢查服務狀態和作業，以及使用專案資源的配額和帳單。

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

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

建立資料夾結構和 Terraform 設定檔

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 在 Cloud Shell 終端機中執行下列指令，將主目錄設為現用目錄：
   

   cd

3. 執行下列指令，建立名為 terraform 的新資料夾：
   

   mkdir terraform

4. 啟動 Cloud Shell 編輯器。
5. 在「Explorer」窗格中，在 terraform 資料夾上按一下滑鼠右鍵，然後點選「New File」。
6. 輸入 main.tf 做為檔案名稱，然後按一下「OK」。

在 Terraform 設定檔中定義基礎架構

1. 在 Cloud Shell 編輯器中開啟 main.tf 檔案。

2. 在下列 Terraform 設定範例中，將 PROJECT_NAME 和 LOCATION 預留位置替換為實際值，然後將範例複製到 main.tf 檔案：

   resource "google_project_service" "notebooks" {
     provider           = google
     service            = "notebooks.googleapis.com"
     disable_on_destroy = false
   }
   
   resource "google_notebooks_instance" "basic_instance" {
     project      = "PROJECT_ID"
     name         = "notebooks-instance-basic"
     provider     = google
     location     = "LOCATION"
     machine_type = "e2-medium"
   
     vm_image {
       project      = "deeplearning-platform-release"
       image_family = "tf-ent-2-9-cu113-notebooks"
     }
   
     depends_on = [
       google_project_service.notebooks
     ]
   }
   

   • PROJECT_ID：輸入 Google Cloud 專案 ID。

   • LOCATION：輸入使用者自行管理的筆記本執行個體的區域和可用區。例如，us-west2-b。如要獲得最佳網路效能，請選取最靠近您的地理區域。請參閱這篇文章，瞭解可用的使用者管理筆記本位置。

3. 儲存 main.tf 檔案。

初始化包含 Terraform 設定檔的工作目錄

1. 如要開啟 Cloud Shell 終端機，請在 Cloud Shell 編輯器的工具列中，點選「Open Terminal」(開啟終端機)。

2. 在 Cloud Shell 終端機中執行下列指令，將 terraform 資料夾設為目前的工作目錄：

   cd ~/terraform
   

3. 執行下列指令：

   terraform init
   

4. Terraform 會初始化工作目錄。畫面會出現以下輸出結果：

   Terraform has been successfully initialized!
   
   You may now begin working with Terraform. Try running "terraform plan" to see
   any changes that are required for your infrastructure. All Terraform commands
   should now work.
   
   If you ever set or change modules or backend configuration for Terraform,
   rerun this command to reinitialize your working directory. If you forget, other
   commands will detect it and remind you to do so if necessary.

   注意： 每次更新 Terraform 工作目錄中的任何設定檔時，都必須執行 terraform init。

根據 Terraform 設定預覽執行計畫

Terraform 執行計畫會指出 Terraform 預計對 Vertex AI 基礎架構和服務進行的變更。

執行下列指令，查看 Terraform 執行計畫。

terraform plan

如果系統提示您授權 Cloud Shell，請按一下「Authorize」(授權)。 授權後，Cloud Shell 會預設使用使用者的憑證。

畫面會顯示類似以下的輸出：

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following
symbols:
  + create

Terraform will perform the following actions:

  # google_notebooks_instance.basic_instance will be created
  + resource "google_notebooks_instance" "basic_instance" {
      + create_time     = (known after apply)
      + id              = (known after apply)
      + labels          = (known after apply)
      + location        = "us-west2-b"
      + machine_type    = "e2-medium"
      + name            = "notebooks-instance-basic"
      + network         = (known after apply)
      + project         = "my_project"
      + proxy_uri       = (known after apply)
      + service_account = (known after apply)
      + state           = (known after apply)
      + subnet          = (known after apply)
      + update_time     = (known after apply)

      + shielded_instance_config {
          + enable_integrity_monitoring = (known after apply)
          + enable_secure_boot          = (known after apply)
          + enable_vtpm                 = (known after apply)
        }

      + vm_image {
          + image_family = "tf-ent-2-9-cu113-notebooks"
          + project      = "deeplearning-platform-release"
        }
    }

  # google_project_service.notebooks will be created
  + resource "google_project_service" "notebooks" {
      + disable_on_destroy = false
      + id                 = (known after apply)
      + project            = (known after apply)
      + service            = "notebooks.googleapis.com"
    }

Plan: 2 to add, 0 to change, 0 to destroy.

• my_project 表示您指定的 Google Cloud 專案 ID。

• us-west2-b 表示您指定的由使用者管理的筆記本執行個體所屬的區域和可用區。

套用執行計畫中提出的變更

1. 執行下列指令，將執行計畫中的變更套用至 Vertex AI 基礎架構，並建立使用者自行管理的筆記本執行個體：

   terraform apply
   

2. 畫面會顯示類似以下的輸出：

   Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following
   symbols:
     + create
   
   Terraform will perform the following actions:
   
     # google_notebooks_instance.basic_instance will be created
     + resource "google_notebooks_instance" "basic_instance" {
         + create_time     = (known after apply)
         + id              = (known after apply)
         + labels          = (known after apply)
         + location        = "us-west2-b"
         + machine_type    = "e2-medium"
         + name            = "notebooks-instance-basic"
         + network         = (known after apply)
         + project         = "my_project"
         + proxy_uri       = (known after apply)
         + service_account = (known after apply)
         + state           = (known after apply)
         + subnet          = (known after apply)
         + update_time     = (known after apply)
   
         + shielded_instance_config {
             + enable_integrity_monitoring = (known after apply)
             + enable_secure_boot          = (known after apply)
             + enable_vtpm                 = (known after apply)
           }
   
         + vm_image {
             + image_family = "tf-ent-2-9-cu113-notebooks"
             + project      = "deeplearning-platform-release"
           }
       }
   
     # google_project_service.notebooks will be created
     + resource "google_project_service" "notebooks" {
         + disable_on_destroy = false
         + id                 = (known after apply)
         + project            = (known after apply)
         + service            = "notebooks.googleapis.com"
       }
   
   Plan: 2 to add, 0 to change, 0 to destroy.
   
   Do you want to perform these actions?
     Terraform will perform the actions described above.
     Only 'yes' will be accepted to approve.
   
     Enter a value:
   

   • my_project 表示您指定的 Google Cloud 專案 ID。

   • us-west2-b 表示您指定的由使用者管理的筆記本執行個體所屬的區域和可用區。

3. 輸入 yes，然後按下 Enter 鍵。畫面會顯示類似以下的輸出：

   Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
   

查看由使用者管理的筆記本執行個體

前往 Google Cloud 控制台的「User-managed notebooks」頁面。

前往使用者自行管理的筆記本

表格中會列出名為「notebooks-instance-basic」的新筆記本。請注意，執行 terraform apply 後，新的使用者管理筆記本執行個體可能需要幾分鐘才能佈建完成。

清除專案所用資源

清除在本教學課程中建立的 Google Cloud 資源。如要避免部分資源產生非預期的費用，請按照下列步驟操作：

1. 在 Cloud Shell 終端機中執行下列指令，將 terraform 資料夾設為目前的工作目錄：

   cd ~/terraform
   

2. 如要刪除根據 Terraform 設定建立的 Vertex AI 資源，請執行下列指令：

   terraform destroy
   

3. 畫面會顯示類似以下的輸出：

   Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
     - destroy
   
   Terraform will perform the following actions:
   
     # google_notebooks_instance.basic_instance will be destroyed
     - resource "google_notebooks_instance" "basic_instance" {
         - create_time            = "2022-12-01T21:14:05.065893475Z" -> null
         - id                     = "projects/my_project/locations/us-west2-b/instances/notebooks-instance-basic" -> null
         - install_gpu_driver     = false -> null
         - labels                 = {
             - "goog-caip-notebook" = ""
           } -> null
         - location               = "us-west2-b" -> null
         - machine_type           = "e2-medium" -> null
         - name                   = "notebooks-instance-basic" -> null
         - network                = "https://www.googleapis.com/compute/v1/projects/my_project/global/networks/default" -> null
         - no_proxy_access        = false -> null
         - no_public_ip           = false -> null
         - project                = "my_project" -> null
         - service_account        = "[e-mail]" -> null
         - service_account_scopes = [] -> null
         - state                  = "PROVISIONING" -> null
         - subnet                 = "https://www.googleapis.com/compute/v1/projects/my_project/regions/us-west2/subnetworks/default" -> null
         - tags                   = [] -> null
         - update_time            = "2022-12-01T21:14:19.048432376Z" -> null
   
         - shielded_instance_config {
             - enable_integrity_monitoring = true -> null
             - enable_secure_boot          = false -> null
             - enable_vtpm                 = true -> null
           }
   
         - vm_image {
             - image_family = "tf-ent-2-9-cu113-notebooks" -> null
             - project      = "deeplearning-platform-release" -> null
           }
       }
   
     # google_project_service.notebooks will be destroyed
     - resource "google_project_service" "notebooks" {
         - disable_on_destroy = false -> null
         - id                 = "my_project/notebooks.googleapis.com" -> null
         - project            = "my_project" -> null
         - service            = "notebooks.googleapis.com" -> null
       }
   
   Plan: 0 to add, 0 to change, 2 to destroy.
   
   Do you really want to destroy all resources?
     Terraform will destroy all your managed infrastructure, as shown above.
     There is no undo. Only 'yes' will be accepted to confirm.
   
     Enter a value:
   

   • my_project 表示您指定的 Google Cloud 專案 ID。

   • us-west2-b 表示您指定的由使用者管理的筆記本執行個體所屬的區域和可用區。

4. 輸入 yes，然後按下 Enter 鍵。畫面會顯示類似以下的輸出：

   Destroy complete! Resources: 2 destroyed.
   

5. 如要確認使用者管理的筆記本執行個體已刪除，請前往「User-managed notebooks」(使用者管理的筆記本) 頁面。

   前往使用者自行管理的筆記本

6. 啟動 Cloud Shell 編輯器。

7. 如要刪除 terraform 資料夾及其內容，請在「檔案總管」窗格中，對 terraform 資料夾按一下滑鼠右鍵，然後點選「刪除」。

8. 系統提示時，按一下 [OK] (確定) 確認操作。

在 Vertex AI 中使用 Terraform 的其他方式

本教學課程只建立一個設定檔，並根據一個 Terraform 資源佈建基礎架構，向您展示如何使用 Terraform。您也可以透過下列方式使用 Terraform：

• 在同一個 Terraform 設定檔中新增多個 Terraform 資源。如需 Vertex AI 的 Terraform 資源清單，請參閱「適用於 Vertex AI 的 Terraform 資源」。

• 建立包含多個資料夾和 Terraform 設定檔的目錄結構。舉例來說，您可以為每種 Terraform 資源建立個別資料夾和 Terraform 設定檔。

後續步驟

• 在 Terraform 登錄檔中進一步瞭解 google_notebooks_instance Terraform 資源。

• 進一步瞭解使用者自行管理的筆記本和 Vertex AI Workbench。

• 在本機指令列介面上安裝 Terraform。

• 如要進一步瞭解 Terraform，請前往 Terraform 開發人員網站。

• 請參閱 Terraform 登錄中的 Terraform 資源說明文件。