Controles de modelos, herramientas y datos con Terraform

Usa esta guía para aplicar controles de modelos, herramientas alojadas y retención de datos a un proyecto existente. Estos controles determinan qué modelos y herramientas pueden usar las cargas de trabajo del proyecto y qué política de retención aprobada se aplica. No otorgan acceso al proyecto a usuarios ni a cuentas de servicio.

Al completar el flujo de trabajo principal, tendrás una configuración que podrás reutilizar para:

• Limitar el proyecto a un conjunto de modelos aprobados.
• Establecer un permiso explícito para cada herramienta alojada compatible.
• Aplicar al proyecto la política de retención de datos predeterminada de la organización.

Antes de comenzar

Completa la configuración del proveedor de Terraform y exporta una clave de la API de administración como OPENAI_ADMIN_KEY. También necesitas lo siguiente:

• El ID de un proyecto existente.
• Los ID de los modelos disponibles para tu organización.
• Una organización que tenga habilitados los controles de retención de datos si planeas administrar la retención del proyecto.

Usa un proyecto de prueba para evaluar el flujo de trabajo. Para deshabilitar una herramienta alojada en un proyecto, la política de herramientas de la organización ya debe limitar el acceso a esa herramienta a proyectos seleccionados. Un proyecto no puede deshabilitar una herramienta que la organización haya habilitado para todos los proyectos.

Restringir el acceso a los modelos

openai_project_model_permissions aplica a un proyecto una lista de modelos permitidos o una lista de modelos denegados. En este ejemplo, solo se permite gpt-5.4-mini:

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

Asigna a mode uno de estos valores:

• allow_list para permitir solo los modelos incluidos en model_ids.
• deny_list para permitir los modelos disponibles, excepto los incluidos en model_ids.

Cada ID de modelo debe ser visible para la organización, incluidos los ID de las instantáneas de modelos ajustados que agregues a la política. Terraform incorpora los cambios en el modo y en la lista de modelos la próxima vez que generes y apliques un plan.

Configurar las herramientas alojadas

openai_project_hosted_tool_permissions administra cinco permisos de herramientas a nivel de proyecto. Define todos los campos para que la configuración que revises refleje la política completa:

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

Los campos controlan la búsqueda de archivos, la búsqueda web, la generación de imágenes, los servidores MCP remotos y el intérprete de código. La política de herramientas alojadas de cada organización admite tres modos: permitir el acceso a todos los proyectos, denegarlo a todos o permitirlo solo a proyectos seleccionados. Si asignas el valor true a un campo, el proyecto puede usar esa herramienta siempre que cumpla los demás requisitos de elegibilidad y retención de la organización. Si asignas el valor false a un campo, el proyecto se elimina de la lista de proyectos seleccionados para esa herramienta. Si la organización permite el uso de la herramienta en todos los proyectos, el intento de asignar el valor false falla. Antes de deshabilitar la herramienta en un proyecto específico, cambia la política de la organización para que permita el acceso solo a proyectos seleccionados.

Terraform consulta los cinco valores en OpenAI para actualizar su estado. Si se hicieron cambios desde el panel, los muestra en el siguiente plan como diferencias respecto de la configuración.

Configurar la retención de datos

openai_project_data_retention aplica un tipo de retención aprobado a un proyecto. Configura el proyecto para que herede la política vigente de la organización, salvo que tenga una excepción aprobada:

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

El proveedor también acepta none, zero_data_retention, modified_abuse_monitoring, enhanced_zero_data_retention y enhanced_modified_abuse_monitoring. Los modos disponibles y las transiciones permitidas dependen de la configuración de tu organización y de la región de residencia de los datos del proyecto.

Consulta Tus datos y el acuerdo de tu organización con OpenAI antes de elegir una política de retención distinta para el proyecto.

Administrar la política predeterminada de la organización

Usa openai_organization_data_retention solo si Terraform ya administra la configuración de retención de la organización:

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

Este recurso modifica una configuración existente de la organización. No inscribe a la organización en un programa de retención de datos. Algunos cambios de nivel de retención requieren la intervención del equipo de soporte y otros no están disponibles.

Detectar cambios realizados fuera de Terraform

Genera un plan para actualizar la información sobre el estado remoto y compararla con la configuración revisada:

terraform plan -detailed-exitcode

El código de salida 0 indica que no hay cambios, 2 indica que el plan contiene cambios y 1 indica que Terraform encontró un error. Investiga los cambios inesperados antes de aplicar el plan. Si se hizo un cambio administrativo de emergencia, averigua para qué se hizo antes de sobrescribirlo de forma automática.

Ejecutar el ejemplo completo

En este ejemplo se administran los tres controles del proyecto en conjunto. Crea el archivo main.tf:

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293terraform {
  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
}

Crea el archivo terraform.tfvars con el ID de un proyecto existente, los ID de los modelos visibles para tu organización, la política de herramientas alojadas y un tipo de retención aprobado:

12345678910111213project_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"

El ejemplo habilita todas las herramientas alojadas para que pueda ejecutarse cuando la política de la organización las habilite en todos los proyectos. Cambia un valor a false solo cuando la política de la organización para esa herramienta ya limite el acceso a proyectos seleccionados. Antes de aplicar el plan, confirma que el ID del modelo y el tipo de retención estén disponibles para tu organización.

Inicializa Terraform y luego revisa y aplica el plan guardado:

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

El primer plan debería indicar que se agregarán tres recursos. En el caso de los controles de herramientas alojadas y de retención de datos, agregar un recurso significa que Terraform pasa a administrar la configuración existente de ese control, que es única para cada proyecto. No se crea un objeto remoto independiente. El recurso de permisos de acceso a modelos crea o actualiza la configuración de esos permisos para el proyecto.

Vuelve a ejecutar terraform plan para confirmar que la configuración no genere más cambios. Si el plan muestra diferencias, averigua si otro administrador o una automatización modificó algún control del proyecto antes de aplicar otra actualización.