Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Modelle, Tools und Datenaufbewahrung mit Terraform verwalten

Konfiguriere den Modellzugriff, die gehosteten Tools und die Datenaufbewahrung für dein Projekt.

In dieser Anleitung konfigurierst du den Modellzugriff, die gehosteten Tools und die Datenaufbewahrung für ein bestehendes Projekt. Diese Einstellungen legen fest, welche Modelle und Tools Workloads im Projekt nutzen können und welche genehmigte Aufbewahrungsrichtlinie gilt. Sie gewähren weder Personen noch Dienstkonten Zugriff auf das Projekt.

Nach Abschluss der folgenden Schritte hast du eine wiederverwendbare Konfiguration, die Folgendes festlegt:

  • Das Projekt darf nur genehmigte Modelle verwenden.
  • Für jedes unterstützte gehostete Tool ist ausdrücklich festgelegt, ob das Projekt es verwenden darf.
  • Für das Projekt gilt die standardmäßige Aufbewahrungsrichtlinie der Organisation.

Bevor du beginnst

Schließe das Setup des Terraform-Providers ab und exportiere einen Admin-API-Schlüssel als OPENAI_ADMIN_KEY. Außerdem brauchst du:

  • Die ID eines bestehenden Projekts.
  • Die IDs der Modelle, die deiner Organisation zur Verfügung stehen.
  • Eine Organisation, für die Einstellungen zur Datenaufbewahrung aktiviert sind, falls du die Datenaufbewahrung für das Projekt verwalten möchtest.

Verwende ein Testprojekt, um den Ablauf zu erproben. Damit du ein gehostetes Tool für ein einzelnes Projekt deaktivieren kannst, muss die Organisation den Zugriff auf dieses Tool bereits auf ausgewählte Projekte beschränkt haben. Ein Projekt kann ein Tool nicht deaktivieren, das die Organisation für alle Projekte freigegeben hat.

Modellzugriff einschränken

Mit openai_project_model_permissions legst du für ein Projekt entweder eine Liste erlaubter oder eine Liste gesperrter Modelle fest. In diesem Beispiel ist nur gpt-5.4-mini erlaubt:

resource "openai_project_model_permissions" "application" {
  project_id = "proj_123"
  mode       = "allow_list"
  model_ids  = ["gpt-5.4-mini"]
}

Wähle für mode einen der folgenden Werte:

  • allow_list erlaubt nur die Modelle in model_ids.
  • deny_list erlaubt alle verfügbaren Modelle mit Ausnahme der Modelle in model_ids.

Jede Modell-ID muss für die Organisation sichtbar sein. Das gilt auch für Snapshots feinabgestimmter Modelle, die du in die Richtlinie aufnimmst. Änderungen am Modus und an der Modellliste berücksichtigt Terraform beim Erstellen und Anwenden des nächsten Plans.

Gehostete Tools konfigurieren

Mit openai_project_hosted_tool_permissions verwaltest du fünf Tool-Berechtigungen auf Projektebene. Setze jedes Feld ausdrücklich, damit du bei der Prüfung der Konfiguration die gesamte Richtlinie siehst:

resource "openai_project_hosted_tool_permissions" "application" {
  project_id               = "proj_123"
  file_search_enabled      = true
  web_search_enabled       = false
  image_generation_enabled = false
  mcp_enabled              = false
  code_interpreter_enabled = true
}

Die Felder steuern den Zugriff auf Dateisuche, Websuche, Bildgenerierung, Remote-MCP-Server und Code Interpreter. Für jedes gehostete Tool kann die Organisation den Zugriff für alle Projekte erlauben, für alle Projekte sperren oder nur für ausgewählte Projekte erlauben. Mit true erlaubst du dem Projekt, das Tool zu verwenden, sofern es die übrigen Voraussetzungen der Organisation für die Nutzung und Datenaufbewahrung erfüllt. Mit false entfernst du das Projekt aus der Liste der Projekte, die das Tool verwenden dürfen. Wenn die Organisation das Tool derzeit für alle Projekte erlaubt, schlägt das Setzen des Felds auf false fehl. Beschränke den Zugriff in der Tool-Richtlinie der Organisation auf ausgewählte Projekte, bevor du das Tool für ein einzelnes Projekt deaktivierst.

Terraform ruft alle fünf Werte von OpenAI ab und weist Änderungen, die im Dashboard vorgenommen wurden, im nächsten Plan als Abweichungen aus.

Datenaufbewahrung konfigurieren

Mit openai_project_data_retention legst du für ein Projekt einen genehmigten Aufbewahrungstyp fest. Übernimm die aktuelle Richtlinie der Organisation, sofern für das Projekt keine abweichende Regelung genehmigt wurde:

resource "openai_project_data_retention" "application" {
  project_id = "proj_123"
  type       = "organization_default"
}

Der Provider akzeptiert auch none, zero_data_retention, modified_abuse_monitoring, enhanced_zero_data_retention und enhanced_modified_abuse_monitoring. Welche Modi verfügbar sind und zwischen welchen du wechseln kannst, hängt von der Konfiguration deiner Organisation und der Datenresidenzregion des Projekts ab.

Lies den Leitfaden Deine Daten und prüfe die Vereinbarung deiner Organisation mit OpenAI, bevor du für ein Projekt eine abweichende Einstellung wählst.

Standardeinstellung der Organisation verwalten

Verwende openai_organization_data_retention nur, wenn Terraform die bestehende Einstellung auf Organisationsebene verwaltet:

resource "openai_organization_data_retention" "default" {
  type = "zero_data_retention"
}

Mit dieser Ressource änderst du eine bestehende Einstellung der Organisation. Die Teilnahme an einem Programm zur Datenaufbewahrung lässt sich damit nicht aktivieren. Für manche Wechsel zwischen Aufbewahrungsstufen brauchst du Hilfe vom Support. Andere Wechsel sind nicht möglich.

Wenn du openai_project_hosted_tool_permissions oder openai_project_data_retention aus der Konfiguration entfernst, entfernt Terraform die jeweilige Ressource aus seinem State. Die Einstellungen bei OpenAI bleiben bestehen. Entfernst du openai_project_model_permissions, löscht Terraform die Konfiguration der Modellberechtigungen des Projekts. Berücksichtige diese Unterschiede, wenn du einen Plan zum Löschen von Ressourcen prüfst.

Änderungen außerhalb von Terraform erkennen

Erstelle einen Plan, damit Terraform den aktuellen Zustand bei OpenAI abruft und mit der geprüften Konfiguration vergleicht:

terraform plan -detailed-exitcode

Der Exitcode 0 bedeutet, dass keine Änderungen anstehen. Bei 2 enthält der Plan Änderungen. Bei 1 ist in Terraform ein Fehler aufgetreten. Kläre unerwartete Änderungen, bevor du den Plan anwendest. Falls im Notfall jemand eine administrative Änderung vorgenommen hat, kläre deren Zweck, bevor du sie automatisch überschreibst.

Das vollständige Beispiel ausführen

Im folgenden Beispiel verwaltest du alle drei Projekteinstellungen gemeinsam. Erstelle die Datei 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 "model_permission_mode" {
  type        = string
  description = "Whether model_ids is an allowlist or denylist."
  default     = "allow_list"

  validation {
    condition     = contains(["allow_list", "deny_list"], var.model_permission_mode)
    error_message = "The model permission mode must be allow_list or deny_list."
  }
}

variable "model_ids" {
  type        = list(string)
  description = "Model IDs included in the project model policy."
}

variable "hosted_tools" {
  type = object({
    file_search      = bool
    web_search       = bool
    image_generation = bool
    mcp              = bool
    code_interpreter = bool
  })
  description = "Hosted tools enabled for the project."
}

variable "project_data_retention_type" {
  type        = string
  description = "Approved data-retention type for the project."

  validation {
    condition = contains([
      "organization_default",
      "none",
      "zero_data_retention",
      "modified_abuse_monitoring",
      "enhanced_zero_data_retention",
      "enhanced_modified_abuse_monitoring",
    ], var.project_data_retention_type)
    error_message = "Provide a supported project data-retention type."
  }
}

resource "openai_project_model_permissions" "application" {
  project_id = var.project_id
  mode       = var.model_permission_mode
  model_ids  = var.model_ids
}

resource "openai_project_hosted_tool_permissions" "application" {
  project_id               = var.project_id
  file_search_enabled      = var.hosted_tools.file_search
  web_search_enabled       = var.hosted_tools.web_search
  image_generation_enabled = var.hosted_tools.image_generation
  mcp_enabled              = var.hosted_tools.mcp
  code_interpreter_enabled = var.hosted_tools.code_interpreter
}

resource "openai_project_data_retention" "application" {
  project_id = var.project_id
  type       = var.project_data_retention_type
}

output "controlled_project_id" {
  value = var.project_id
}

output "model_permission_mode" {
  value = openai_project_model_permissions.application.mode
}

output "project_data_retention_type" {
  value = openai_project_data_retention.application.type
}

Erstelle die Datei terraform.tfvars. Gib darin die ID eines bestehenden Projekts, die für deine Organisation sichtbaren Modell-IDs, die Richtlinie für gehostete Tools und einen genehmigten Aufbewahrungstyp an:

project_id            = "proj_123"
model_permission_mode = "allow_list"
model_ids             = ["gpt-5.4-mini"]

hosted_tools = {
  file_search      = true
  web_search       = true
  image_generation = true
  mcp              = true
  code_interpreter = true
}

project_data_retention_type = "organization_default"

Das Beispiel aktiviert alle gehosteten Tools. So lässt es sich auch ausführen, wenn die Richtlinie der Organisation die Tools für alle Projekte freigibt. Setze einen Wert erst dann auf false, wenn die Organisation den Zugriff auf das entsprechende Tool auf ausgewählte Projekte beschränkt hat. Prüfe vor dem Anwenden des Plans, ob die Modell-ID und der Aufbewahrungstyp für deine Organisation verfügbar sind.

Initialisiere Terraform. Erstelle und speichere anschließend einen Plan, prüfe ihn und wende ihn an:

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

Der erste Plan sollte drei Ressourcen zum Hinzufügen aufführen. Bei den Berechtigungen für gehostete Tools und bei der Datenaufbewahrung bedeutet das Hinzufügen, dass Terraform die Verwaltung der jeweils einzigen bestehenden Einstellung für das Projekt übernimmt. Dabei entsteht kein separates Objekt bei OpenAI. Bei den Modellberechtigungen erstellt oder aktualisiert Terraform die entsprechende Konfiguration des Projekts.

Führe terraform plan erneut aus und vergewissere dich, dass die Konfiguration zu keinen weiteren Änderungen führt. Falls der Plan Abweichungen anzeigt, kläre vor dem nächsten Update, ob eine andere Person mit Administrationsrechten oder eine Automatisierung eine Projekteinstellung geändert hat.