跳至主要内容

后端类型: gcs

将状态存储为 Google Cloud Storage (GCS) 上预先存在的存储桶中的可配置前缀中的对象。存储桶必须在配置后端之前存在。

此后端支持 状态锁定。

示例配置​

代码块
terraform {
  backend "gcs" {
    bucket  = "tf-state-prod"
    prefix  = "tofu/state"
  }
}

数据源配置​

代码块
data "terraform_remote_state" "foo" {
  backend = "gcs"
  config = {
    bucket  = "tofu-state"
    prefix  = "prod"
  }
}

resource "local_file" "foo" {
  content  = data.terraform_remote_state.foo.outputs.greeting
  filename = "${path.module}/outputs.txt"
}

身份验证​

对存储桶的 IAM 更改 最终是一致的，并且可能需要长达几分钟才能生效。OpenTofu 将返回 403 错误，直到它最终一致。

在您的工作站上运行 OpenTofu。​

如果您在您的工作站上使用 OpenTofu，您需要安装 Google Cloud SDK 并使用 用户应用程序默认凭据 进行身份验证。

用户 ADC 会 过期，您可以通过运行 gcloud auth application-default login 来刷新它们。

在 Google Cloud 上运行 OpenTofu​

如果您在 Google Cloud 上运行 OpenTofu，您可以将该实例或集群配置为使用 Google 服务帐户。这将允许 OpenTofu 对 Google Cloud 进行身份验证，而无需在单独的凭据/身份验证文件中进行烘焙。确保 VM/集群的范围设置为 cloud-platform。

在 Google Cloud 之外运行 OpenTofu​

如果您在 Google Cloud 之外运行 OpenTofu，请生成一个服务帐户密钥并将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为服务帐户密钥的路径。OpenTofu 将使用该密钥进行身份验证。

模拟服务帐户​

OpenTofu 可以模拟 Google 服务帐户，如 此处 所述。必须提供有效的凭据，如前一部分所述，并且该身份必须在您要模拟的服务帐户上具有 roles/iam.serviceAccountTokenCreator 角色。

加密​

客户提供的加密密钥​

要开始，请按照以下指南操作：使用客户提供的加密密钥

如果您要从后端配置中删除客户提供的密钥或更改为不同的客户提供的密钥，OpenTofu 无法自动执行状态迁移，因此需要手动干预。这种干预是必要的，因为 Google 不存储客户提供的加密密钥，发送到 Cloud Storage API 的任何请求都必须提供它们（请参阅 客户提供的加密密钥）。在状态迁移时，后端配置将丢失旧密钥的详细信息，OpenTofu 无法在迁移过程中使用该密钥。

客户管理的加密密钥 (Cloud KMS)​

要开始使用，请遵循以下指南：使用客户管理的加密密钥

如果您想要从后端配置中移除客户管理的密钥，或更改为不同的客户管理密钥，OpenTofu *可以* 管理状态迁移，无需人工干预。这是因为 GCP 存储客户管理的加密密钥，并在状态迁移过程中可以访问。但是，这些更改直到状态迁移后，状态文件上第一次写入操作发生后才会完全生效。在状态迁移后的第一次写入操作中，文件将使用旧密钥解密，然后使用新的加密方法写入。此方法等同于客户提供的加密密钥部分中描述的重写操作。由于第一次写入状态对于状态迁移至关重要，因此您应该在使用该密钥加密的任何状态文件（或文件）更新之前，不要删除旧的 KMS 密钥。

由于解密在 GCS 内自动完成，因此不需要在请求中发送客户管理密钥来从 GCS 存储桶中读取文件。这意味着，如果您使用terraform_remote_state 数据源访问 KMS 加密的 state，则不需要在数据源的config对象中指定 KMS 密钥。

配置变量​

支持以下配置选项

  • bucket - (必填) GCS 存储桶的名称。此名称必须是全局唯一的。有关更多信息，请参阅存储桶命名指南。
  • credentials / GOOGLE_BACKEND_CREDENTIALS / GOOGLE_CREDENTIALS - (可选) Google Cloud Platform 帐户凭据在 JSON 格式中的本地路径。如果未设置，路径将使用Google 应用程序默认凭据。提供的凭据必须在存储桶上具有存储对象管理员角色。警告：如果您也使用 Google Cloud Platform 提供程序，它也会获取GOOGLE_CREDENTIALS环境变量。
  • impersonate_service_account / GOOGLE_BACKEND_IMPERSONATE_SERVICE_ACCOUNT / GOOGLE_IMPERSONATE_SERVICE_ACCOUNT - (可选) 用于访问状态存储桶的模拟服务帐户。您必须在该帐户上具有roles/iam.serviceAccountTokenCreator角色才能成功模拟。如果您使用委托链，则可以使用impersonate_service_account_delegates字段指定该链。
  • impersonate_service_account_delegates - (可选) 模拟服务帐户的委托链，如此处所述。
  • access_token - (可选) 从 Google 授权服务器获得的临时 [OAuth 2.0 访问令牌]，即用于对 GCP API 进行身份验证的 HTTP 请求的Authorization: Bearer令牌。这是credentials的替代方案。如果同时指定了这两个字段，则将使用access_token而不是credentials字段。
  • prefix - (可选) 存储桶内的 GCS 前缀。工作区的名命状态存储在一个名为<prefix>/<name>.tfstate的对象中。
  • encryption_key / GOOGLE_ENCRYPTION_KEY - (可选) 在读取和写入存储桶中的状态文件时使用的 32 字节 base64 编码的“客户提供的加密密钥”。有关更多信息，请参阅客户提供的加密密钥。
  • kms_encryption_key / GOOGLE_KMS_ENCRYPTION_KEY - (可选) 在读取和写入存储桶中的状态文件时使用的 Cloud KMS 密钥（“客户管理的加密密钥”）。格式应为projects/{{project}}/locations/{{location}}/keyRings/{{keyRing}}/cryptoKeys/{{name}}。有关更多信息，包括 IAM 要求，请参阅客户管理的加密密钥。
  • storage_custom_endpoint / GOOGLE_BACKEND_STORAGE_CUSTOM_ENDPOINT / GOOGLE_STORAGE_CUSTOM_ENDPOINT - (可选) 包含三个部分的 URL：协议、指向私有服务连接端点的 DNS 名称以及 Cloud Storage API 的路径（/storage/v1/b，参见此处）。您可以使用服务目录自动创建的 DNS 名称，也可以使用您自定义的 DNS 名称。例如，如果您创建一个名为xyz的端点，并且想要使用自动创建的 DNS 名称，则应将字段值设置为https://storage-xyz.p.googleapis.com/storage/v1/b。有关使用 OpenTofu 创建私有服务连接端点的帮助，请参阅本指南。