瞭解 Google Cloud API 和 Terraform

本指南旨在說明 Terraform 如何與 Google Cloud API 互動 (同時區分公開和私有 API)，並說明 API 啟用和資源匯入等重要概念。瞭解這些概念，才能有效使用 Terraform 管理 Google Cloud 資源，並避免常見的錯誤。

公開與私有 Google Cloud API

Google Cloud 服務會公開各種 API，讓應用程式和工具 (例如 Terraform) 能夠與資源互動及管理資源。這些 API 大致可分為兩類：

公開 API

用途：這些是客戶和工具建立、設定及管理資源的主要介面 (例如 Google Cloud Compute Engine 執行個體、Cloud Storage bucket、BigQuery 資料集)。

公開：公開 API 具有完善的文件，並定義了 REST 端點，供外部使用。這些 API 是 google Terraform 供應商建構時互動的對象。

示例：compute.googleapis.com、storage.googleapis.com、bigquery.googleapis.com。

私有 (內部) API

用途：這些 API 是 Google Cloud 服務的內部 API，Google 本身會使用這些 API，進行受管理服務的內部作業、協調及佈建。這些功能並非用於直接與顧客互動或管理。

曝光：私人 API 通常不會公開記錄，也沒有穩定的外部端點，且不適合由 Terraform 等第三方工具直接存取。這是服務的實作詳細資料。

範例： dataproc-control.googleapis.com 是 Dataproc 用於運算控制平面的內部 API。客戶不會直接與這個 API 互動或管理這個 API。

Terraform 中的 API 啟用與資源匯入

瞭解「啟用 API」和「匯入資源」之間的差異，是有效搭配使用 Terraform 和 Google Cloud的基本概念。

啟用 API

• 意義：在 Google Cloud中「啟用 API」時，您會為專案啟用特定 Google Cloud 服務。這會授予專案必要的權限和存取權，以便使用該服務的功能，並建立由該服務管理的資源。

Terraform 內容：在 Terraform 中，這通常是使用 google_project_service 資源完成。這項資源會驗證指定的公開 API (例如 compute.googleapis.com) 已為您的 Google Cloud 專案啟用。

用途：啟用 API 是建立或管理該服務所屬資源的先決條件。舉例來說，您必須先啟用 compute.googleapis.com，才能建立 google_compute_instance 資源。

範例 (Terraform)：

```hcl
resource "google_project_service" "compute_api" {
  project            = "your-gcp-project-id"
  service            = "compute.googleapis.com"
  disable_on_destroy = false
}
```

重要注意事項：google_project_service 資源專門用於管理公開存取 Google Cloud API 的啟用狀態。這個 API 不適用於內部或私人 API，也無法與這類 API 搭配使用。如果嘗試將其用於私有 API，就會發生錯誤，因為這些 API 不會透過公開 API 介面公開，以供這類管理作業使用。

匯入資源

意義：在 Terraform 中，「匯入」是指將現有雲端資源 (手動建立或透過 Terraform 以外的其他程序建立) 納入 Terraform 管理。匯入資源時，Terraform 會為該資源產生狀態項目，讓您使用 Terraform 設定管理資源的生命週期 (更新、刪除)。

Terraform 內容：這項作業可使用 terraform import 指令達成，或利用 Terraform 1.5 以上版本導入的 import 區塊達成。

用途：控管最初並非由 Terraform 佈建的資源。

範例 (Terraform CLI)：

```bash
terraform import google_compute_instance.my_instance projects/your-gcp-project-id/zones/us-central1-a/instances/my-vm
```

注意： 您「匯入」的是資源 (例如 google_compute_instance、google_storage_bucket、google_sql_database_instance)，而不是「API」本身。雖然 API 的啟用狀態是由 google_project_service 管理，但 API 本身並非資源，無法以與 VM 或 bucket 相同的方式「匯入」。如果專案已啟用公開 API，則可透過 google_project_service 資源管理其啟用狀態，並匯入 google_project_service 資源 (例如terraform import google_project_service.my_api projects/your-gcp-project-id/services/compute.googleapis.com)，但這與匯入產品專屬資源不同。

解決私人 API 的相關疑慮 (例如 dataproc-control.googleapis.com)

有時客戶會在記錄或說明文件中看到私人 API 的參照 (例如 Dataproc 的 dataproc-control.googleapis.com)，並想知道是否需要透過 Terraform 啟用或匯入這些 API。

不需要採取任何客戶行動：如果 API 屬於私有或內部 Google Cloud API，您不需要使用 google_project_service 明確啟用，也不需要嘗試使用 Terraform 匯入。

內部管理：這些 API 對於Google Cloud 服務的內部運作至關重要。這類資源由 Google 自動管理，不適合透過公開工具直接與客戶互動或管理。

不影響服務使用：您無法使用 Terraform「匯入」或明確管理這類私人 API，不會影響您使用相關 Google Cloud 服務 (例如 您不必管理 dataproc-control.googleapis.com，Dataproc 也能正常運作。Google 會處理必要的內部 API 互動。

專注於公開 API：使用 Terraform 管理 Google Cloud 資源時，您應只專注於啟用及設定與您要佈建的服務和資源相應的公開 API。

結論

瞭解公開和私有 API 的明確區別，以及在 Terraform 中「啟用」API 與「匯入」資源的特定角色，有助於有效管理基礎架構。請勿嘗試明確管理或匯入私有 API，因為這些是 Google 處理的內部元件。 Google Cloud Google Cloud Google Cloud 將 Terraform 設定的重點放在公開 API 和對應資源。