OpenAI Terraform Provider 1.0 教程：用 IaC 管理 API Platform

OpenAI 于 2026 年 7 月 29 日发布官方 Terraform Provider 1.0，让 API Platform 的管理对象可以进入 Infrastructure as Code 工作流。团队不必只依赖控制台手工创建项目、添加成员或调整速率限制，而是可以把目标状态写进 Terraform 配置，通过代码审查、执行计划和状态文件管理变更。官方 Provider 的地址是：openai/terraform-provider-openai。

这套 Provider 能管理什么

OpenAI Terraform Provider 调用的是 Administration API，主要面向组织和项目的控制面资源。当前文档覆盖的常用对象包括：

• 组织项目与项目成员。
• 组织用户、邀请、用户组和角色。
• 项目级用户、用户组及角色分配。
• 项目服务账号。
• 组织证书与项目证书关联。
• 项目模型权限和 Hosted Tool 权限。
• 项目数据保留策略。
• 组织与项目支出提醒。
• 项目级速率限制。

Provider 同时提供大量 Data Source，可以查询已经存在的项目、用户、角色、证书和限制，避免在配置中硬编码所有 ID。它适合以下场景：

• 为开发、测试和生产环境建立一致的 OpenAI 项目结构。
• 通过 Pull Request 审查权限与配额变更。
• 将已有控制台资源逐步导入 Terraform。
• 定期运行 terraform plan 检测控制台手工修改。
• 为不同团队复用项目、角色和限制模板。

1.0.0 的两个迁移重点

1.0.0 是首个正式版本，但从早期预览版升级时不能只修改版本号。这个版本删除了已经弃用的聚合项目速率限制资源。项目现在应使用单项 openai_project_rate_limit 资源，每个资源对应一个已有的 rate_limit_id。此外，Provider 的请求韧性和遥测得到改进，但这不会改变 Terraform 的状态管理原则：生产环境仍应先执行 plan，确认变更范围后再 apply。

前置条件

开始前需要：

• Terraform CLI 1.0 或更高版本。
• OpenAI API Platform 组织权限。
• 一个 OpenAI Admin API Key。
• 用于保存 Terraform 状态的安全后端。

Admin API Key 与普通项目 API Key 用途不同。它用于 Administration API，不能拿来调用普通的模型推理接口。在 OpenAI API Platform 的组织设置中创建 Admin API Key 后，通过环境变量传入：

1

export OPENAI_ADMIN_KEY="<your-admin-api-key>"

PowerShell 可以这样设置：

1

$env:OPENAI_ADMIN_KEY = "<your-admin-api-key>"

不要把管理密钥写进 .tf 文件、变量默认值或 Git 仓库。CI/CD 环境应使用 Secret Store 注入，并限制谁能读取执行日志和 Terraform 状态。

初始化官方 Provider

新建 versions.tf：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

terraform {
  required_version = ">= 1.0"

  required_providers {
    openai = {
      source  = "openai/openai"
      version = "~> 1.0"
    }
  }
}

再创建 provider.tf：

1
2
3
4

provider "openai" {
  # 默认读取 OPENAI_ADMIN_KEY。
  # organization 和 project 也可由环境变量提供。
}

可用的 Provider 参数包括：

• admin_api_key：Admin API Key，属于敏感字段。
• organization：组织 ID。
• project：默认项目 ID。
• base_url：OpenAI API 请求基础地址。

对应的环境变量包括 OPENAI_ADMIN_KEY、OPENAI_ORG_ID 和 OPENAI_PROJECT_ID。初始化工作目录：

1
2

terraform init
terraform providers

提交代码时应一并提交 .terraform.lock.hcl，确保 CI 与本地使用经过确认的 Provider 版本。

创建一个 OpenAI 项目

最小项目资源只需要名称：

1
2
3
4
5
6
7

resource "openai_project" "production" {
  name = "production-api"
}

output "production_project_id" {
  value = openai_project.production.project_id
}

geography 是可选字段，是否设置应以实际 API Platform 配置和合规要求为准。不要为了示例直接修改现有生产项目的地域设置。先格式化并检查配置：

1
2
3

terraform fmt -check
terraform validate
terraform plan -out=tfplan

确认计划只包含预期资源后再执行：

1

terraform apply tfplan

管理项目成员与角色

可以把现有组织用户加入项目：

1
2
3
4
5
6
7
8
9

variable "operator_user_id" {
  type = string
}

resource "openai_project_user" "operator" {
  project_id = openai_project.production.project_id
  user_id    = var.operator_user_id
  role       = "member"
}

如果需要独立的项目角色分配，官方提供三个内置项目角色 ID：

• role-api-project-member
• role-api-project-owner
• role-api-project-viewer

例如分配只读角色：

1
2
3
4
5

resource "openai_project_user_role" "viewer" {
  project_id = openai_project.production.project_id
  user_id    = var.operator_user_id
  role_id    = "role-api-project-viewer"
}

也可以通过 openai_project_roles Data Source 动态发现角色，减少对固定 ID 的依赖。自定义项目角色使用 openai_project_role，其必要字段是 project_id、role_name 和 permissions：

1
2
3
4
5
6

resource "openai_project_role" "auditor" {
  project_id  = openai_project.production.project_id
  role_name   = "API auditor"
  description = "Read-only access for audit automation"
  permissions = ["api.project.read"]
}

权限字符串必须来自实际可用权限集合。上线前应以 Data Source 或官方 API 文档核对，不要凭名称猜测权限。

邀请尚未加入组织的用户

组织邀请可以连同项目成员身份一起声明：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

resource "openai_invite" "developer" {
  email = "[email protected]"
  role  = "reader"

  projects = [
    {
      id   = openai_project.production.project_id
      role = "member"
    }
  ]
}

邀请具有接受、过期等生命周期状态。收件人接受后，应重新运行 terraform plan，确认远端状态与配置的关系符合预期。

服务账号不会自动创建 API Key

创建项目服务账号的配置很简单：

1
2
3
4

resource "openai_project_service_account" "deploy" {
  project_id = openai_project.production.project_id
  name       = "production-deploy"
}

但该资源只创建服务账号本身。它明确设置 create_service_account_only=true，不会自动分配角色，也不会创建 API Key。角色需要使用单独的 Terraform 资源管理，API Key 则要通过公开 API 在 Terraform 外创建和管理。不要在模块输出中假设会出现可直接使用的密钥。

管理证书

组织证书可以从 PEM 文件读取：

1
2
3
4

resource "openai_certificate" "organization" {
  name        = "production-certificate"
  certificate = file("${path.module}/certificates/production.pem")
}

certificate 是敏感属性，但敏感标记不等于内容不会进入状态文件。需要确认远程 State 已加密，并限制 State 后端、备份和 CI Artifact 的访问权限。证书轮换前先查看计划中的替换行为，确保新旧证书的有效期有重叠，避免一次 apply 造成连接中断。

设置模型访问范围

项目模型权限可使用允许列表：

1
2
3
4
5

resource "openai_project_model_permissions" "production" {
  project_id = openai_project.production.project_id
  mode       = "allow_list"
  model_ids  = ["gpt-5.6-sol"]
}

模型标识可能随产品更新变化。合并配置前应核对当前可用模型，并在删除旧模型许可前确认应用已经完成迁移。

管理项目级速率限制

openai_project_rate_limit 管理的是已有速率限制对象，必须提供项目 ID 与具体的 rate_limit_id：

1
2
3
4
5
6

resource "openai_project_rate_limit" "primary_model" {
  project_id               = openai_project.production.project_id
  rate_limit_id            = "rate_limit_123"
  max_requests_per_1_minute = 500
  max_tokens_per_1_minute   = 200000
}

可管理字段还包括每日请求数、Batch 每日最大输入 token、每分钟图像数量和每分钟音频 MB 数。实际可设置的上限取决于组织和模型配额。Terraform 只能管理 API 接受的值，不能通过提高配置数字绕过平台配额。

把已有资源导入 Terraform

对已经在控制台创建的资源，不要重复创建，应先写出与远端资源匹配的配置并导入 State。Terraform 1.5 及以上可以使用 import 块：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import {
  to = openai_project.production
  id = "proj_123"
}

import {
  to = openai_project_service_account.deploy
  id = "proj_123/service_account_123"
}

import {
  to = openai_project_rate_limit.primary_model
  id = "proj_123/rate_limit_123"
}

不同资源的导入 ID 格式不同。常见形式包括单个资源 ID、project_id/resource_id，以及包含用户和角色的三段复合 ID。应以对应资源文档中的 Import 小节为准。导入后依次运行：

1
2

terraform plan
terraform state show openai_project.production

如果计划立即显示大量更新，说明本地配置没有完整反映远端状态。先调整配置直到计划符合预期，不要直接 apply 覆盖生产设置。

用 plan 检测配置漂移

当管理员在控制台手工修改成员、角色或限制后，Provider 的读取操作会把远端状态与 Terraform 配置比较。CI 中可以使用详细退出码：

1
2

terraform init -input=false
terraform plan -input=false -detailed-exitcode

退出码含义是：

• 0：配置与远端状态一致，没有变更。
• 1：命令执行失败，应检查权限、网络或配置错误。
• 2：检测到变更或漂移，需要人工审查计划。

不要在检测到退出码 2 后自动执行生产 apply。漂移可能来自紧急处置、权限撤销或平台侧变化，应先确认是恢复代码声明的状态，还是把合理的手工变更同步回配置。

State、权限与审查建议

Admin API Key 能修改组织控制面，应按高权限凭据处理。建议采用以下保护：

• 本地开发只通过环境变量短期注入密钥。
• CI 使用专用身份和受保护的 Secret。
• 远程 State 启用加密、锁和版本保留。
• 将 plan 与 apply 分成不同审批阶段。
• 生产环境限制可执行 apply 的分支和人员。
• 定期轮换 Admin API Key 并撤销不再使用的密钥。
• 对导入、角色变更和资源删除保留审计记录。

删除项目、成员、角色或证书前，要检查 Terraform 计划中的 destroy 与 replace 项。对关键资源可以结合 prevent_destroy，但它不能替代变更审查与恢复方案。

常见问题

Provider 可以调用模型 API 吗？

不可以。它面向 OpenAI Administration API，Admin API Key 也不能用于普通模型请求。

服务账号资源会返回 API Key 吗？

不会。它只创建服务账号，角色与 API Key 需要分别管理。

为什么不能创建新的速率限制对象？

该资源用于管理已有项目速率限制，需要提供实际的 rate_limit_id。1.0.0 已移除旧的聚合速率限制资源。

控制台手工变更能被发现吗？

可以通过 terraform plan 发现远端状态与配置的差异。发现漂移后应人工判断以哪一侧为准，而不是无条件自动覆盖。

已有项目需要重建吗？

不需要。使用 import 块或 terraform import 把资源加入 State，再逐步补齐配置即可。

总结

OpenAI Terraform Provider 1.0 把 API Platform 管理纳入标准 IaC 流程，适合统一管理项目、成员、角色、服务账号、证书与项目限制。接入时最值得注意的不是一条 terraform apply，而是三件事：正确使用 Admin API Key、先导入已有资源、以及把 terraform plan 作为权限和配置漂移的审查入口。在生产环境中，还要特别处理服务账号密钥、复合资源导入 ID、1.0.0 速率限制资源变化和 Terraform State 的访问安全。

官方资料

• OpenAI 官方 Terraform Provider
• Provider 文档目录
• 1.0.0 Changelog