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_listerlaubt nur die Modelle inmodel_ids.deny_listerlaubt alle verfügbaren Modelle mit Ausnahme der Modelle inmodel_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.