如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

使用 Terraform 管理服务账号

为工作负载创建仅具备必要权限的非人类身份,并在 Terraform 之外签发 API 密钥。

OpenAI 服务账号是归属于某个项目的非人类身份。您可以使用 Terraform 创建不带默认角色的服务账号,定义一组最小权限,再通过组将这些权限分配给服务账号。服务账号的 API 密钥应在 Terraform 之外通过管理 API 创建和管理。

本指南介绍配置服务账号的典型流程:

  1. 创建服务账号,不分配默认项目角色,也不生成 API 密钥。
  2. 通过组分配自定义项目角色,仅授予工作负载所需的权限。
  3. 创建限定权限范围的 API 密钥,并将其存入密钥管理器。

开始之前

完成 Terraform 提供程序设置,将管理员 API 密钥导出为环境变量 OPENAI_ADMIN_KEY,并将现有项目的 ID 导出为环境变量 PROJECT_ID。

请在测试组织中评估服务账号的创建、导入、替换和删除操作。

创建不带默认角色的服务账号

使用 Terraform 创建服务账号:

resource "openai_project_service_account" "application" {
  project_id = "proj_123"
  name       = "example-application-development-service-account"
}

output "service_account_id" {
  value = openai_project_service_account.application.service_account_id
}

将 proj_123 替换为该服务账号将归属的现有项目的 ID。

提供程序只创建服务账号身份,不生成 API 密钥,也不分配默认项目角色。Terraform 将服务账号 ID 和其他非敏感元数据保存在状态中。此时,服务账号没有任何项目权限。

按最小权限原则分配权限

定义一个自定义项目角色,仅包含工作负载所需的权限。创建一个组,将服务账号加入该组,然后为组分配角色。以下示例允许组成员创建响应:

resource "openai_project_role" "application" {
  project_id  = openai_project_service_account.application.project_id
  role_name   = "Application response writer"
  description = "Allows the application to create responses"
  permissions = ["api.responses.write"]
}

resource "openai_group" "application_access" {
  name = "example-application-development-access"
}

resource "openai_group_user" "application" {
  group_id = openai_group.application_access.group_id
  user_id  = openai_project_service_account.application.id
}

resource "openai_project_group_role" "application_access" {
  project_id = openai_project_service_account.application.project_id
  group_id   = openai_group.application_access.group_id
  role_id    = openai_project_role.application.role_id
}

openai_project_role 资源定义最小权限集,openai_group_user 将服务账号加入组,openai_project_group_role 将角色分配给该组。加入该组的每个服务账号都会继承同一个项目角色。请将 api.responses.write 替换为您的工作负载所需且已获批准的最小权限集。有关通过组管理项目访问权限的更多信息,请参阅项目与访问权限。

检查并应用配置:

terraform plan
terraform apply

如果自定义项目角色已提供工作负载所需的权限,请勿分配内置的 member 或 owner 角色。仅授予已获批准的权限集中的权限。

创建限定权限范围的 API 密钥

应用 Terraform 配置后,通过创建项目服务账号 API 密钥端点创建 API 密钥。API 只返回一次完整的密钥值,因此请在发出请求前设置文件权限掩码,限制对新建响应文件的访问:

SERVICE_ACCOUNT_ID="$(terraform output -raw service_account_id)"
umask 077

curl -X POST \
  "https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts/$SERVICE_ACCOUNT_ID/api_keys" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production App",
    "scopes": ["api.responses.write"]
  }' \
  --output service-account-api-key.json

选择满足工作负载需求的最小权限范围。API 密钥的权限范围可以进一步限制服务账号的权限,但不能授予超出其项目角色的权限。

将 value 字段的值从 service-account-api-key.json 直接传入经批准的密钥管理流程,请勿打印该值。待密钥管理器存储并验证密钥后,删除响应文件:

rm service-account-api-key.json

只要 service-account-api-key.json 仍然存在,就应将其作为机密文件处理。请勿提交该文件,也不要将密钥写入 Terraform 配置、通过 Terraform 输出公开密钥,或将密钥作为 Terraform 变量传递。

API 参考提供了响应结构和不同编程语言的示例。支持工作负载身份联合的工作负载可以使用同一个服务账号和最小权限角色,无需创建 API 密钥。

导入现有服务账号

Terraform 创建的服务账号无需导入。要让 Terraform 接管在其外部创建的服务账号,请使用该账号现有的项目 ID 和名称声明资源:

resource "openai_project_service_account" "application" {
  project_id = "proj_123"
  name       = "example-application-development-service-account"
}

在按常规流程应用配置之前,先导入现有身份:

SERVICE_ACCOUNT_ID="<existing-service-account-id>"

terraform import \
  openai_project_service_account.application \
  "$PROJECT_ID/$SERVICE_ACCOUNT_ID"

terraform plan

导入后的第一个计划应显示服务账号无需变更。如果计划显示需要替换服务账号,请先调整配置中的名称和项目,使其与现有账号一致,然后再应用配置。

导入操作不会恢复或存储 API 密钥,不会更改服务账号现有的项目角色,也不会导入其组成员关系。如果您希望 Terraform 管理现有的 openai_project_role、openai_group、openai_group_user 和 openai_project_group_role 资源,请声明并导入这些资源。工作负载仍会从密钥管理器读取现有密钥。

请先导入服务账号,再应用资源声明。如果先应用声明,Terraform 会创建另一个服务账号,而不会接管现有身份。

恢复或轮换凭据

只有创建 API 密钥时的响应包含完整密钥值。之后查询项目 API 密钥时,返回值的部分内容会被遮盖,因此无法找回丢失的密钥。

要在不中断工作负载的情况下替换丢失或需要轮换的凭据,请按以下步骤操作:

  1. 将新服务账号声明为新的 openai_project_service_account 资源,并使用与旧账号不同的 Terraform 资源名称。
  2. 应用配置,创建新服务账号。
  3. 使用 openai_group_user 将新账号加入现有组,使其继承具备最小权限的项目角色。
  4. 通过管理 API 为新账号创建 API 密钥,并按经批准的密钥管理流程存储密钥。
  5. 部署新密钥,并确认工作负载使用新账号时能正常运行。
  6. 从 Terraform 配置中移除旧的 openai_project_service_account 资源及其对应的 openai_group_user 资源。保留新服务账号仍在使用的角色、组以及组与角色的分配关系。
  7. 检查并应用删除旧服务账号及其组成员关系的计划,然后运行 terraform plan,确认结果显示无需变更。

删除 openai_project_service_account 资源会同时删除远程服务账号。务必对这项变更进行明确审核,尤其是旧凭据仍在用于处理请求时。

有关将其他现有资源纳入 Terraform 状态管理以及移除资源时的行为,请参阅导入与状态协调。

运行完整示例

前面的示例使用具体值分别说明了如何创建服务账号、分配角色和创建 API 密钥。完整配置使用变量指定各项目的值和权限,便于您在不同环境中复用配置。

将以下配置保存为 main.tf:

terraform {
  required_version = ">= 1.0"

  required_providers {
    openai = {
      source  = "openai/openai"
      version = ">= 1.0.0"
    }
  }
}

provider "openai" {}

variable "project_id" {
  type        = string
  description = "ID of the existing OpenAI project."
}

variable "service_account_name" {
  type        = string
  description = "Name of the application service account."
}

variable "project_role_permissions" {
  type        = list(string)
  description = "Least-privilege project permissions for the application."

  validation {
    condition     = length(var.project_role_permissions) > 0
    error_message = "Provide at least one approved project permission."
  }
}

resource "openai_project_service_account" "application" {
  project_id = var.project_id
  name       = var.service_account_name
}

resource "openai_project_role" "application" {
  project_id  = var.project_id
  role_name   = "Application API access"
  description = "Least-privilege permissions approved for the application"
  permissions = var.project_role_permissions
}

resource "openai_group" "application_access" {
  name = "${var.service_account_name}-access"
}

resource "openai_group_user" "application" {
  group_id = openai_group.application_access.group_id
  user_id  = openai_project_service_account.application.id
}

resource "openai_project_group_role" "application_access" {
  project_id = var.project_id
  group_id   = openai_group.application_access.group_id
  role_id    = openai_project_role.application.role_id
}

output "project_id" {
  value = var.project_id
}

output "service_account_id" {
  value = openai_project_service_account.application.service_account_id
}

output "group_id" {
  value = openai_group.application_access.group_id
}

output "project_role_id" {
  value = openai_project_role.application.role_id
}

创建 terraform.tfvars,填入现有项目的 ID、唯一的服务账号名称以及已获批准的最小项目权限集:

project_id           = "proj_123"
service_account_name = "example-application-development-service-account"

project_role_permissions = [
  "api.responses.write",
]

初始化 Terraform,然后检查并应用已保存的计划:

terraform init
terraform fmt
terraform validate
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan

第一个计划应列出五个待添加的资源:服务账号、该账号使用的自定义项目角色、组、组成员关系,以及组与角色的分配关系。再次运行 terraform plan,确认配置不会产生进一步变更。

在 Terraform 之外创建服务账号的 API 密钥:

PROJECT_ID="$(terraform output -raw project_id)"
SERVICE_ACCOUNT_ID="$(terraform output -raw service_account_id)"
umask 077

curl -X POST \
  "https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts/$SERVICE_ACCOUNT_ID/api_keys" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production App",
    "scopes": ["api.responses.write"]
  }' \
  --output service-account-api-key.json

将返回的 API 密钥值存入经批准的密钥管理器,然后删除 service-account-api-key.json。请勿在 Terraform 配置、状态或输出中存储密钥。