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.

Ao concluir as etapas principais, você terá uma configuração reutilizável que:

• Restringe 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 de retenção de dados padrão da organização.

Antes de começar

Conclua a configuração do provedor Terraform e exporte uma chave da API de administração na variável de ambiente OPENAI_ADMIN_KEY. Você também precisa dos seguintes itens:

• 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 para avaliar o fluxo de trabalho. Para desabilitar uma ferramenta hospedada em um projeto específico, a política da organização já deve restringir o uso dessa ferramenta a projetos selecionados. Um projeto não pode desabilitar uma ferramenta que a organização habilitou para todos os projetos.

Restrinja o acesso aos modelos

openai_project_model_permissions aplica a um projeto uma lista de modelos permitidos ou uma lista de modelos bloqueados. 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 todos os modelos disponíveis, exceto os que constam em model_ids.

Cada ID de modelo deve estar visível para a organização. Isso também vale para os snapshots de modelos com ajuste fino que você incluir na política. O Terraform identifica as alterações no modo e na lista de modelos no próximo plano e as efetiva quando você o aplica.

Configure as ferramentas hospedadas

openai_project_hosted_tool_permissions gerencia cinco permissões de ferramentas no 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 em 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 oferece três modos: permitir o uso em todos os projetos, bloquear o uso em todos os projetos ou permitir o uso apenas em projetos selecionados. Definir um campo como true permite que o projeto use a ferramenta, desde que o projeto atenda aos demais requisitos de elegibilidade e retenção da organização. Definir um campo como false remove o projeto da lista de projetos selecionados para usar a ferramenta. Se a organização permite o uso da ferramenta em todos os projetos, a tentativa de definir o campo como false falha. Antes de desabilitar a ferramenta em um projeto específico, altere a política da organização para permitir o uso apenas em projetos selecionados.

O Terraform consulta a OpenAI para atualizar os cinco valores e, no próximo plano, indica como divergências as alterações feitas no painel.

Configure a retenção de dados

openai_project_data_retention aplica a um projeto um tipo de retenção aprovado. Configure o projeto para herdar a política atual da organização, a menos que haja uma exceção aprovada para ele:

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 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 escolher uma política diferente para o projeto.

Gerencie a política padrão da organização

Use openai_organization_data_retention apenas quando o Terraform for responsável por gerenciar a configuração existente na organização:

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

Esse 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 entre níveis de retenção exigem a ajuda do suporte ou não estão disponíveis.

Detecte alterações feitas fora do Terraform

Execute um plano para atualizar as informações sobre o estado remoto e compará-las 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. Antes de sobrescrever automaticamente uma alteração administrativa de emergência, entenda por que ela foi feita.

Execute o exemplo completo

O exemplo a seguir gerencia os três controles do projeto em conjunto. Crie o arquivo 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 o arquivo terraform.tfvars com o ID de um projeto existente, os IDs dos modelos visíveis para a organização, 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 as ferramentas para todos os projetos. Só altere um valor para false depois que a política correspondente da organização restringir o acesso a projetos selecionados. Antes de aplicar o plano, confirme que o ID do modelo e o tipo de retenção estão disponíveis para sua organização.

Inicialize o Terraform, salve o plano, revise-o e aplique-o:

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

O primeiro plano deve indicar três recursos a adicionar. No caso dos controles de ferramentas hospedadas e de retenção de dados, cada adição indica que o Terraform passa a gerenciar uma configuração que já existe e é única por projeto. Nenhum objeto remoto separado é criado. Já o recurso de permissões de modelos cria ou atualiza a configuração de permissões de modelos do projeto.

Execute terraform plan novamente para confirmar que a configuração não gera outras alterações. Se o plano indicar alguma divergência, verifique se outro administrador ou alguma automação alterou um controle do projeto antes de aplicar uma nova atualização.