開發工具

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

介紹 OpenAI 官方 Terraform Provider 1.0 的安裝、專案與權限配置、服務帳號和證書管理、速率限制、資源匯入及配置漂移檢測。

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 覆蓋生產設定。

用 terraform 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 的訪問安全。

官方資料