開発ツール

OpenAI Terraform Provider 1.0 チュートリアル:IaCを用いたAPIプラットフォーム管理

OpenAIの公式Terraform Provider 1.0インストール、プロジェクトおよび権限設定、サービスアカウントおよび証明書管理、レート制限、リソースインポート、構成ドリフト検出の紹介。

2026年7月29日、OpenAIは公式のTerraform Provider 1.0をリリースし、APIプラットフォーム管理オブジェクトがInfrastructure as Codeワークフローに入ることを可能にしました。チームはもはやコンソールだけに頼ってプロジェクトの作成、メンバーの追加、レート制限の調整を行う必要がなくなり、代わりにターゲット状態をTerraformの設定に書き込み、コードレビュー、実行計画、ステータスファイル管理を通じて変更を管理できます。公式 Providerアドレスはopenai/terraform-provider-openaiです。

このProviderは何を管理できるのか?

OpenAI Terraform Providerは管理APIを呼び出し、主に組織やプロジェクトのコントロールプレーンリソースを対象としています。現在ドキュメントでカバーされている一般的なオブジェクトには以下があります:

  • プロジェクトやプロジェクトメンバーの組織化。
  • ユーザー、招待、ユーザーグループ、ロールを整理する。
  • ユーザー、ユーザーグループ、役割のプロジェクトレベルの割り当て。
  • プロジェクトサービスアカウント。
  • 組織証明書とプロジェクト証明書を関連付ける。
  • プロジェクトモデル権限およびホストツール権限。
  • プロジェクトデータ保持戦略。
  • 組織およびプロジェクトの支出リマインダー。
  • プロジェクトレベルのレート制限。

また、Providerは多数のデータソースを提供し、既存のプロジェクト、ユーザー、ロール、証明書、制限へのクエリを可能にし、設定時にすべてのIDをハードエンコードする必要を回避できます。以下のシナリオに適しています:

  • 開発、テスト、本番環境において一貫したOpenAIプロジェクト構造を確立すること。
  • プルリクエストを通じて権限とクオータの変更を確認します。
  • 既存のコンソールリソースを徐々にTerraformにインポートする。
  • 定期的に実行terraform plan手動で検知コンソールを修正する。
  • 異なるチームごとにプロジェクト、役割、制限テンプレートを再利用すること。

1.0.0の2つの重要な移行ポイント

1.0.0が最初の公式バージョンでしたが、初期プレビュー版からのアップグレードはバージョン番号を変更するだけでなく、このバージョンでは、アグリゲーションプロジェクトの廃止されたレート制限リソースが削除されました。プロジェクトは今後、既存のrate_limit_idに対応するシングルエントリーのopenai_project_rate_limitリソースを使用するべきです。さらに、Providerの要求耐性やテレメトリも改善されましたが、これはTerraformの状態管理原則を変えません。本番環境はまずplanを実行し、変更範囲を確認し、その後applyするべきです。

前提条件

始める前に、以下のことが必要です:

  • Terraform CLI 1.0以降。
  • OpenAI APIプラットフォーム組織権限。
  • OpenAI管理APIキー。
  • Terraform状態を保存するための安全なバックエンド。

管理者APIキーは通常のプロジェクトAPIキーとは異なる目的を果たします。管理APIに使用され、標準モデル推論インターフェースを呼び出すことはできません。OpenAI APIプラットフォームの組織設定で管理者APIキーを作成すると、環境変数を通じて渡されます:

1

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

PowerShellは次のように設定できます:

1

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

管理キーを.tfファイル、変数デフォルト値、Gitリポジトリに書き込まないでください。CI/CD環境ではシークレットストアインジェクションを使用し、実行ログや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 也可由环境变量提供。
}

利用可能な提供者のパラメータは以下の通りです:

  • admin_api_key:管理者APIキー(機密フィールド)。
  • organization:組織ID。
  • project:デフォルトのプロジェクトID。
  • base_url:OpenAI APIリクエストのベースアドレス。

対応する環境変数にはOPENAI_ADMIN_KEY、OPENAI_ORG_ID、OPENAI_PROJECT_IDが含まれます。ワーキングディレクトリの初期化:

1
2

terraform init
terraform providers

コードを提出する際は、CIと確認済みProviderバージョンのローカル使用を確保するために.terraform.lock.hclを一緒に提出する必要があります。

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プラットフォームの設定およびコンプライアンス要件に基づいて判断すべきです。既存の本番プロジェクトの地域設定を直接変更しないでください。まず、構成をフォーマットして確認します:

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"
}

独立したプロジェクトロールを割り当てたい場合は、公式チームが3つの組み込みプロジェクトロール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動的に役割を発見でき、固定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"]
}

権限文字列は、実際に利用可能な権限セットから取得する必要があります。稼働前に、データソースや公式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キーを作成しません

プロジェクトサービスアカウントの設定は非常に簡単です:

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キーも作成しません。ロールは別途Terraformのリソース管理を必要とし、APIキーは公開APIを介してTerraform外で作成・管理する必要があります。モジュール出力に直接利用可能なキーが現れるとは限りません。

証明書を管理する

組織証明書はPEMファイルから読み取ることができます:

1
2
3
4

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

certificateは機密性のプロパティですが、機密タグがあるからといって、その内容がステータスファイルに入らないわけではありません。リモート状態が暗号化されていることを確認し、状態バックエンド、バックアップ、CIアーティファクトへのアクセスを制限する必要があります。証明書のローテーション前に、新旧証明書の有効性が重複し、単一の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
}

管理可能なフィールドには、日次リクエスト数、1日あたりの最大バッチ入力トークン数、1分あたりの画像数、1分あたりの音声MB数などが含まれます。実際に設定可能な上限は組織やモデルのクォータによって異なります。TerraformはAPIで受け入れられる値のみを管理でき、設定数を増やすことでプラットフォームのクォータを回避することはできません。

既存リソースをTerraformにインポートする

コンソール上で既に作成されたリソースについては、繰り返し作成しないでください。まずリモートリソースに合致する構成を書き、状態をインポートします。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、ユーザーと役割を含む3セグメントの複合IDがあります。対応するリソースドキュメント内のインポートセクションを標準として使用すべきです。インポート後は順番に実行します:

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、権限、変更レビューの推奨事項

管理者APIキーは組織のコントロールプレーンを変更でき、高権限認証として扱うべきです。以下の保護が推奨されます:

  • ローカル開発は環境変数を通じて短期的にキーのみを注入します。
  • CIは専用のアイデンティティと保護された秘密を使用します。
  • リモートステートは暗号化、ロック、バージョン保持を可能にします。
  • planとapplyを異なる承認段階に分けます。
  • 本番環境は、applyを実行することができる部門や人員を制限します。
  • 管理者APIキーを定期的にローテーションし、未使用キーは取り消す。
  • インポート、役割変更、リソース削除に関する監査記録の維持。

アイテム、メンバー、ロール、証明書を削除する前に、Terraformプランのdestroyとreplace項目を確認してください。重要なリソースのためにprevent_destroyを組み合わせることはできますが、変更レビューや復旧計画の代わりにはなりません。

よくある質問

ProviderはモデルAPIを呼び出せるのか?

いいえ、できません。OpenAI管理APIをターゲットにしており、管理者APIキーは通常のモデルリクエストには使えません。

サービスアカウントリソースはAPIキーを返しますか?

いいえ、そうはなりません。サービスアカウントを作成するだけで、役割とAPIキーは別々に管理する必要があります。

なぜ新しいレート制限オブジェクトを作れないの?

このリソースは既存プロジェクトのレート制限管理に使用され、実際の料金制限の提供が必要ですrate_limit_id。1.0.0 旧の集計レート制限リソースを削除しました。

コンソールの手動変更は検出できますか?

リモート状態と設定の違いを検出するためにterraform planを使えます。ドリフトを検出した後は、無条件に自動的に上書きするのではなく、どちら側を使うか手動で判断すべきです。

既存のプロジェクトは再建が必要でしょうか?

いいえ、する必要はありません。importブロックやterraform importを使ってStateにリソースを追加し、徐々に設定を完了させてください。

まとめ

OpenAI Terraform Provider 1.0はAPIプラットフォーム管理を標準のIaCフローに組み込み、プロジェクト、メンバー、役割、サービスアカウント、証明書、プロジェクトの制限の統一管理に適しています。統合時に最も重要なのは単一のterraform applyではなく、3つのことです:管理者APIキーの正しい使用、既存リソースの先取り、そして権限や設定ドリフトのレビューエントリーとしてterraform planを使います。本番環境では、サービスアカウントキー、複合リソースインポートID、1.0.0のレート制限リソース変更、Terraformの状態アクセスセキュリティにも特別な注意が払われています。

公式資料