了解 Trusted Cloud by S3NS API 和 Terraform

本指南旨在阐明 Terraform 如何与 Trusted Cloud by S3NS API 进行交互(同时区分公共 API 和私有 API),并解释 API 启用和资源导入等关键概念。了解这一点对于使用 Terraform 有效管理 Trusted Cloud by S3NS 资源并避免常见陷阱至关重要。

公开与私密 Trusted Cloud by S3NS API

Trusted Cloud by S3NS 服务公开了各种 API,可让应用和工具(例如 Terraform)与资源进行交互并管理资源。这些 API 大致分为两类:

公共 API

用途:这些是客户和工具用于创建、配置和管理 Trusted Cloud by S3NS 资源(例如,Compute Engine 实例、Cloud Storage 存储分区、BigQuery 数据集)。

公开程度:公开 API 具有完善的文档、已定义的 REST 端点,并且旨在供外部使用。这些 API 是 google Terraform 提供程序构建时所用的交互对象。

示例compute.googleapis.comstorage.googleapis.combigquery.googleapis.com

私有(内部)API

用途:这些 API 是 Trusted Cloud by S3NS 服务的内部 API,Google 本身使用这些 API 来实现其受管服务的内部运营、编排和配置。它们公开的功能不适合直接的客户互动或管理。

公开程度:私有 API 通常没有公开文档,没有稳定的外部端点,并且并非设计为可供 Terraform 等第三方工具直接访问。它们是服务的实现细节。

示例dataproc-control.googleapis.com 是 Dataproc 用于其运营控制平面的内部 API。客户不会直接与此 API 互动或管理此 API。

Terraform 中的 API 启用与资源导入

了解“启用 API”和“导入资源”之间的区别是有效将 Terraform 与 Trusted Cloud by S3NS搭配使用的基础。

启用 API

  • 含义:在 Trusted Cloud by S3NS中“启用 API”是指为您的项目激活特定的 Trusted Cloud by S3NS 服务。这会授予您的项目使用相应服务的功能并创建由该服务管理的资源所需的权限和访问权限。

Terraform 上下文:在 Terraform 中,这通常使用 google_project_service 资源来完成。此资源用于验证指定的公共 API(例如,compute.googleapis.com)已为您的 Trusted Cloud by S3NS 项目启用。

用途:启用 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 资源专用于管理可公开访问的 Trusted Cloud by S3NS API 的启用状态。它不适用于内部或专用 API,也无法与这些 API 搭配使用。尝试将其用于私有 API 会导致错误,因为这些 API 不会通过公共 API Surface 公开以进行此类管理。

导入资源

含义:在 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
```

解决有关私有 API 的疑虑(例如,dataproc-control.googleapis.com)

客户有时会在日志或文档中看到对私有 API(例如 Dataproc 的 dataproc-control.googleapis.com)的引用,并想知道是否需要使用 Terraform 启用或导入这些 API。

无需客户操作:如果某个 API 被标识为私有或内部 Trusted Cloud by S3NS API,您无需使用 google_project_service 显式启用该 API,也无需尝试使用 Terraform 导入该 API。

内部管理:这些 API 对于Trusted Cloud by S3NS 服务的内部运行至关重要。它们由 Google 自动管理,不适合通过公开工具进行直接客户互动或管理。

对 Service Usage 没有影响:您无法使用 Terraform“导入”或明确管理此类私有 API,这不会影响您使用关联的 Trusted Cloud by S3NS 服务(例如,即使您不管理 dataproc-control.googleapis.com,Dataproc 也能正常运行。必要的内部 API 交互由 Google 处理。

专注于公共 API:使用 Terraform 管理 Trusted Cloud by S3NS 资源时,您应仅专注于启用和配置与您打算预配的服务和资源对应的公共 API

总结

通过了解公共 API 和私有 API 之间的明确区别,以及 Terraform 中“启用”API 与“导入”资源的具体角色,您可以有效地管理 Trusted Cloud by S3NS 基础架构。请勿尝试显式管理或导入私有 Trusted Cloud by S3NS API;它们是由 Google 处理的内部组件。 Trusted Cloud by S3NS将 Terraform 配置重点放在公开的 API 及其相应资源上。