Controles de modelos, ferramentas e dados com Terraform

Use este guia para aplicar controles de modelos, ferramentas hospedadas e retenção de dados a um projeto existente. Esses controles determinam quais recursos as cargas de trabalho do projeto podem usar e qual política de retenção aprovada se aplica. Eles não concedem acesso ao projeto a usuários ou contas de serviço.

Após concluir o fluxo de trabalho principal, você terá uma configuração que pode ser reaplicada e que:

• Limita o projeto a um conjunto aprovado de modelos.
• Define uma permissão explícita para cada ferramenta hospedada compatível.
• Aplica ao projeto a política padrão de retenção de dados da organização.

Antes de começar

Conclua a configuração do provedor Terraform e exporte uma chave da API de administração como OPENAI_ADMIN_KEY. Você também precisa de:

• O ID de um projeto existente.
• Os IDs dos modelos disponíveis para sua organização.
• Uma organização com controles de retenção de dados habilitados, caso pretenda gerenciar a retenção do projeto.

Use um projeto de teste ao avaliar o fluxo de trabalho. Para desabilitar uma ferramenta hospedada em um projeto, a política de ferramentas da organização já deve limitar essa ferramenta a projetos selecionados. Um projeto não pode desabilitar uma ferramenta que a organização habilitou para todos os projetos.

Restrinja o acesso a modelos

openai_project_model_permissions aplica uma lista de modelos permitidos ou negados a um projeto. Este exemplo permite apenas gpt-5.4-mini:

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

Defina mode como:

• allow_list para permitir apenas os modelos em model_ids.
• deny_list para permitir os modelos disponíveis, exceto aqueles em model_ids.

Cada ID de modelo deve estar visível para a organização. Isso inclui todos os snapshots de modelos com ajuste fino que você adicionar à política. O Terraform reconcilia as alterações no modo e na lista de modelos na próxima geração e aplicação do plano.

Configure as ferramentas hospedadas

openai_project_hosted_tool_permissions gerencia cinco permissões de ferramentas no nível do projeto. Defina todos os campos para que a configuração revisada descreva a 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
}

Os campos controlam a pesquisa de arquivos, a pesquisa na Web, a geração de imagens, os servidores MCP remotos e o Code Interpreter. A política de ferramentas hospedadas de cada organização tem três modos: permitir todos os projetos, negar todos os projetos ou permitir projetos selecionados. Definir um campo como true permite o uso dessa ferramenta no projeto, sujeito aos demais requisitos de elegibilidade e retenção da organização. Definir um campo como false remove o projeto da política de projetos selecionados dessa ferramenta. Se a organização atualmente permite a ferramenta para todos os projetos, a tentativa de definir o campo como false falha. Altere a política de ferramentas da organização para permitir projetos selecionados antes de desabilitar a ferramenta em um projeto específico.

O Terraform atualiza os cinco valores com os dados da OpenAI e informa as alterações feitas no painel como divergências no próximo plano.

Configure a retenção de dados

openai_project_data_retention aplica um tipo de retenção aprovado a um projeto. Herde a política atual da organização, a menos que o projeto tenha uma configuração específica aprovada:

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

O provedor também aceita none, zero_data_retention, modified_abuse_monitoring, enhanced_zero_data_retention e enhanced_modified_abuse_monitoring. Os modos disponíveis e as transições permitidas dependem da configuração da sua organização e da região de residência de dados do projeto.

Consulte Seus dados e o contrato da sua organização com a OpenAI antes de selecionar uma configuração específica para o projeto.

Gerencie a configuração padrão da organização

Use openai_organization_data_retention somente quando o Terraform for responsável por gerenciar a configuração existente no nível da organização:

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

Este recurso altera uma configuração existente da organização; ele não inscreve a organização em um programa de retenção de dados. Algumas transições exigem assistência do suporte ou não estão disponíveis entre níveis de retenção.

Detecte alterações feitas fora do Terraform

Execute um plano para atualizar o estado remoto e compará-lo com a configuração revisada:

terraform plan -detailed-exitcode

O código de saída 0 indica que não há alterações, 2 indica que o plano contém alterações e 1 indica que o Terraform encontrou um erro. Investigue alterações inesperadas antes de aplicar o plano. Não sobrescreva automaticamente uma alteração administrativa de emergência sem antes entender sua finalidade.

Execute o exemplo completo

O exemplo a seguir gerencia os três controles do projeto em conjunto. Crie 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
}

Crie terraform.tfvars com o ID de um projeto existente, IDs de modelos visíveis, a política de ferramentas hospedadas e um tipo de retenção aprovado:

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"

O exemplo habilita todas as ferramentas hospedadas para que possa ser executado quando a política da organização habilitar ferramentas para todos os projetos. Altere um valor para false somente depois que a política correspondente da organização passar a permitir acesso apenas a projetos selecionados. Confirme que o ID do modelo e o tipo de retenção estão disponíveis para sua organização antes de aplicar o plano.

Inicialize o Terraform e, em seguida, revise e aplique um plano salvo:

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

O primeiro plano deve conter três recursos a serem adicionados. Para os controles de ferramentas hospedadas e retenção de dados, uma adição significa que o Terraform passa a gerenciar uma configuração existente que tem uma única instância por projeto; ela não cria um objeto remoto separado. As permissões de modelos criam ou atualizam a configuração de permissões de modelos do projeto.

Execute terraform plan novamente para confirmar que a configuração não produz mais alterações. Se houver divergências, verifique se outro administrador ou uma automação alterou um controle do projeto antes de aplicar outra atualização.