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

使用 Terraform 管理项目和访问权限

创建项目并配置基于角色和组的访问控制。

按照本指南创建 OpenAI 项目,并设置可复用的访问控制。您将通过项目角色规定身份可在项目中执行哪些操作,将需要访问权限的身份加入组织组,再将该组与项目关联。

完成主要步骤后,您将得到一套可重复使用的配置,用于:

  • 为应用创建 OpenAI 项目。
  • 定义遵循最小权限原则的项目角色。
  • 为需要访问权限的身份创建组织组。
  • 通过项目角色向组授予项目访问权限。
  • 将现有组织用户加入组。

开始之前

完成 Terraform 提供程序设置,并将管理 API 密钥导出为环境变量 OPENAI_ADMIN_KEY。您还需要一名现有组织用户的 ID,以及已获准供应用使用的权限标识符。评估此流程时,请使用测试组织。

销毁 openai_project 时,项目会被归档,而不会被永久删除。项目一旦归档便无法恢复。

划定项目范围

为应用创建项目:

resource "openai_project" "application" {
  name = "example-application-development"
}

项目划定了应用的 API 用量、服务账号、速率限制、支出提醒和项目设置的管理范围。Terraform 通过 openai_project.application.project_id 提供生成的项目 ID。项目级资源可以引用此值,因此 Terraform 会先创建项目,再创建引用它的资源。

这个分步示例使用具体的项目名称。后面的完整示例改用变量,以便您在不同环境中复用配置。

定义项目权限

使用已获准供应用使用的权限创建项目角色:

resource "openai_project_role" "application" {
  project_id  = openai_project.application.project_id
  role_name   = "Application API access"
  description = "Permissions approved for this application"
  permissions = ["api.webhooks.read"]
}

openai_project_role 资源规定身份可以在项目中执行哪些操作。本示例授予读取 webhook 配置的权限。请将 api.webhooks.read 替换为已获准供您的应用使用的权限标识符,起初只授予应用所需的权限。

修改 permissions 会更新角色。应用变更之前,请运行 terraform plan,逐项核对要添加或移除的权限。

创建或复用组

如果需要由 Terraform 管理组的生命周期,请创建一个组织组:

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

组属于组织,可以跨项目复用。组名以 -access 结尾,表明加入该组即可获得访问权限,组名不只是团队名称。

如果现有组由其他系统管理,请通过数据源读取该组:

data "openai_group" "application_access" {
  group_id = "group_123"
}

数据源会读取组的信息,组的生命周期仍由原系统管理。您可以读取通过 SCIM 管理的组,但如需更改成员关系,请在负责管理该组的身份系统中操作。

向组授予项目访问权限

在项目中将组与自定义角色关联:

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

此示例使用由 Terraform 管理的组。如果您通过数据源复用了现有组,请将 group_id 表达式替换为 data.openai_group.application_access.group_id。

这项角色分配关联了三个对象:

  • project_id 指定组可以访问哪个项目。
  • group_id 指定哪个组的成员获得访问权限。
  • role_id 指定组通过哪个角色获得相应权限。

组成员会继承该项目中的自定义角色。单独添加角色或组都不会授予访问权限,只有将角色分配给组,两者才会关联起来。

添加用户和其他身份

使用 openai_group_user 将身份加入由 Terraform 管理的组织组:

resource "openai_group_user" "application_developer" {
  group_id = openai_group.application_access.group_id
  user_id  = "user_123"
}

user_id 可以指向现有的组织用户或服务账号。要添加服务账号,请将 openai_project_service_account.application.id 用作 user_id。有关如何通过组为服务账号授予访问权限,以及身份验证和凭据生命周期管理方面的要求,请参阅服务账号。

如果不适合通过组授予访问权限,请直接分配角色:

resource "openai_project_user_role" "application_developer" {
  project_id = openai_project.application.project_id
  user_id    = "user_123"
  role_id    = openai_project_role.application.role_id
}

要授予适用于整个组织的权限,请创建组织角色,然后直接分配该角色,或通过组分配:

variable "organization_role_permissions" {
  type = list(string)
}

resource "openai_role" "platform_operator" {
  role_name   = "Platform operator"
  description = "Organization permissions for the platform team"
  permissions = var.organization_role_permissions
}

resource "openai_user_role" "platform_operator" {
  user_id = "user_123"
  role_id = openai_role.platform_operator.role_id
}

将 organization_role_permissions 设为已获批准的组织级权限标识符列表。将组织权限与项目权限分开,确保每次分配的权限都限于所需的最小范围。

查看当前的角色分配

更改某个身份的访问权限之前,请查看已分配给该身份的组织角色和项目角色:

data "openai_user_roles" "current" {
  user_id = "user_123"
}

data "openai_project_user_roles" "current" {
  project_id = openai_project.application.project_id
  user_id    = "user_123"
}

output "organization_roles" {
  value = data.openai_user_roles.current.roles
}

output "project_roles" {
  value = data.openai_project_user_roles.current.roles
}

数据源会列出当前的角色分配,但 Terraform 不会因此接管这些分配。

移除角色分配

如果角色分配已由 Terraform 管理,从配置中移除其资源块后,下一次生成的执行计划就会列出要删除的远程角色分配。请检查计划,并确认仍可通过其他途径获得所需的访问权限。

对于已有但尚未纳入 Terraform 管理的角色分配,请先声明对应的资源,并按文档说明使用复合 ID 将其导入。确认首次生成的计划不包含任何变更后,再从配置中移除该资源并执行删除操作。

Terraform 只能移除已记录在其状态中的角色分配。要移除现有的默认角色分配,请先将其导入对应的 Terraform 资源。然后从配置中移除该资源,并应用由此生成的销毁计划。如果您的组织不允许先导入再销毁,请通过获准使用的控制台或管理 API 流程移除该分配。

有关导入格式以及如何安全地将现有资源纳入 Terraform 管理,请参阅导入与状态核对。

运行完整示例

前面的分步示例使用具体值来说明资源之间的关系。完整配置将反复出现且因环境而异的值替换为变量,以便您在不同环境中复用配置,无需修改资源定义。

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

terraform {
  required_version = ">= 1.0"

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

provider "openai" {}

variable "project_name" {
  type = string
}

variable "project_role_permissions" {
  type = list(string)
}

variable "user_id" {
  type = string
}

resource "openai_project" "application" {
  name = var.project_name
}

resource "openai_project_role" "application" {
  project_id  = openai_project.application.project_id
  role_name   = "Application API access"
  description = "Permissions approved for this application"
  permissions = var.project_role_permissions
}

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

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

resource "openai_group_user" "application_developer" {
  group_id = openai_group.application_access.group_id
  user_id  = var.user_id
}

output "project_id" {
  value = openai_project.application.project_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_name = "example-application-development"
user_id      = "user_123"

project_role_permissions = [
  "api.webhooks.read",
]

初始化 Terraform,然后生成并保存执行计划,检查后再应用:

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

首次生成的计划应列出五个待添加的资源。应用计划后,用户会通过组继承自定义项目角色,运行 terraform output 会输出项目 ID、组 ID 和项目角色 ID。再次运行 terraform plan,确认配置不会产生进一步变更。

要添加更多真人用户,请按上述方式将每位用户加入组,并为每位用户使用唯一的 Terraform 资源名称。要配置非人类身份,请参阅服务账号。要为项目设置使用限制和支出提醒,请参阅模型、工具和数据控制以及速率限制和支出。