Herramientas de desarrollo

Tutorial de OpenAI Terraform Provider 1.0: Gestión de plataformas API con IaC

Introducción a la instalación oficial de Terraform Provider 1.0 de OpenAI, configuración de proyectos y permisos, gestión de cuentas de servicio y certificados, límites de tasa, importación de recursos y detección de desviación de configuración.

El 29 de julio de 2026, OpenAI lanzó el Provider oficial de Terraform 1.0, que permite que los objetos de gestión de la Plataforma API ingresen en el flujo de trabajo de Infraestructura como Código. Los equipos ya no necesitan depender únicamente de la consola para crear proyectos manualmente, añadir miembros o ajustar límites de tasa; en su lugar, pueden escribir estados objetivo en configuraciones de Terraform y gestionar cambios mediante revisión de código, planes de ejecución y gestión de archivos de estado. La dirección oficial del Provider es: openai/terraform-provider-openai.

¿Qué puede manejar este Provider?

OpenAI Terraform Provider llama a la API de Administración, dirigida principalmente a recursos de planos de control para organizaciones y proyectos. Los objetos comunes actualmente cubiertos por la documentación incluyen:

  • Organizar proyectos y miembros del proyecto.
  • Organizar usuarios, invitaciones, grupos de usuarios y roles.
  • Asignación a nivel de proyecto de usuarios, grupos de usuarios y roles.
  • Cuenta de servicio de proyectos.
  • Asociar el certificado organizativo con el certificado del proyecto.
  • Permisos de modelos de proyecto y permisos de herramientas alojadas.
  • Estrategias de retención de datos del proyecto.
  • Recordatorios de gastos organizativos y de proyectos.
  • Límites de tarifa a nivel de proyecto.

El proveedor también proporciona un gran número de fuentes de datos, permitiendo consultas de proyectos existentes, usuarios, roles, certificados y restricciones, evitando la codificación dura de todos los IDs en la configuración. Es adecuado para los siguientes escenarios:

  • Establecer una estructura de proyectos OpenAI coherente para entornos de desarrollo, pruebas y producción.
  • Revisar permisos y cambios de cuotas mediante Pull Requests.
  • Importar gradualmente los recursos existentes de consola a Terraform.
  • Ejecutarse regularmente terraform plan modificar manualmente la consola de detección.
  • Reutilizar plantillas de proyectos, roles y restricciones para diferentes equipos.

Dos puntos clave de migración en la 1.0.0

La versión 1.0.0 fue la primera oficial, pero actualizar desde la versión previa temprana no solo podía cambiar el número de versión. Esta versión eliminó los recursos obsoletos de limitación de tasa del proyecto de agregación. Los proyectos deben ahora usar recursos de openai_project_rate_limit de entrada única, cada uno correspondiente a una rate_limit_id existente. Además, la resiliencia de las solicitudes del proveedor y la telemetría han mejorado, pero esto no cambia los principios de gestión del estado de Terraform: los entornos de producción deben seguir realizando plan primero, confirmar el alcance de los cambios y luego apply.

Requisitos previos

Antes de empezar, necesitas:

  • Terraform CLI 1.0 o posterior.
  • Autoridad Organizativa de la Plataforma API OpenAI.
  • Una clave de API de administrador de OpenAI.
  • Un backend seguro para preservar el estado de Terraform.

La Clave de API de Administrador cumple un propósito diferente al de una Clave API de proyecto convencional. Se utiliza para la API de Administración y no puede usarse para llamar a la interfaz de inferencia del modelo estándar. Tras crear la Clave de API de Administrador en la configuración organizativa de la Plataforma API OpenAI, se transmite mediante variables de entorno:

1

export OPENAI_ADMIN_KEY="<your-admin-api-key>"

PowerShell se puede configurar así:

1

$env:OPENAI_ADMIN_KEY = "<your-admin-api-key>"

No escribas claves de gestión en archivos .tf, valores por defecto de variables ni repositorios Git. Los entornos CI/CD deberían usar inyección Secret Store y restringir quién puede leer los registros de ejecución y los estados de Terraform.

Inicializar el proveedor oficial

Nuevos versions.tf:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

terraform {
  required_version = ">= 1.0"

  required_providers {
    openai = {
      source  = "openai/openai"
      version = "~> 1.0"
    }
  }
}

Recrea provider.tf:

1
2
3
4

provider "openai" {
  # 默认读取 OPENAI_ADMIN_KEY。
  # organization 和 project 也可由环境变量提供。
}

Los parámetros disponibles para el proveedor incluyen:

  • admin_api_key: Clave API de Administrador, que es un campo sensible.
  • organization: ID de organización.
  • project: ID de proyecto por defecto.
  • base_url: La dirección base para las solicitudes de API de OpenAI.

Las variables de entorno correspondientes incluyen OPENAI_ADMIN_KEY, OPENAI_ORG_ID y OPENAI_PROJECT_ID. Inicializar el directorio de trabajo:

1
2

terraform init
terraform providers

Al enviar el código, .terraform.lock.hcl deben presentarse juntos para asegurar el CI y el uso local de la versión confirmada del Provider.

Creando un proyecto OpenAI

El recurso más pequeño del proyecto solo necesita un nombre:

1
2
3
4
5
6
7

resource "openai_project" "production" {
  name = "production-api"
}

output "production_project_id" {
  value = openai_project.production.project_id
}

geography es un campo opcional; si se debe configurar o no debe basarse en la configuración real de la plataforma API y los requisitos de cumplimiento. No modifiques directamente la configuración regional de proyectos de producción existentes, solo por ejemplo. Primero, formatea y comprueba la configuración:

1
2
3

terraform fmt -check
terraform validate
terraform plan -out=tfplan

Ejecuta solo después de confirmar que el plan solo incluye los recursos esperados:

1

terraform apply tfplan

Gestión de miembros y roles del proyecto

Puedes añadir usuarios organizativos existentes al proyecto:

1
2
3
4
5
6
7
8
9

variable "operator_user_id" {
  type = string
}

resource "openai_project_user" "operator" {
  project_id = openai_project.production.project_id
  user_id    = var.operator_user_id
  role       = "member"
}

Si necesitas asignar roles independientes al proyecto, el equipo oficial proporciona tres IDs de rol de proyecto integrados:

  • role-api-project-member
  • role-api-project-owner
  • role-api-project-viewer

Por ejemplo, asignar roles de solo lectura:

1
2
3
4
5

resource "openai_project_user_role" "viewer" {
  project_id = openai_project.production.project_id
  user_id    = var.operator_user_id
  role_id    = "role-api-project-viewer"
}

También puedes descubrir dinámicamente roles openai_project_roles Fuente de Datos, reduciendo la dependencia de IDs fijos. Los roles de proyectos personalizados usan openai_project_role, siendo los campos requeridos project_id, role_name y permissions:

1
2
3
4
5
6

resource "openai_project_role" "auditor" {
  project_id  = openai_project.production.project_id
  role_name   = "API auditor"
  description = "Read-only access for audit automation"
  permissions = ["api.project.read"]
}

Las cadenas de permisos deben provenir del conjunto de permisos realmente disponible. Antes de lanzar, verifica con Data Source o documentación oficial de la API; no adivines permisos basándote en nombres.

Invita a los usuarios que aún no se han unido a la organización

Las invitaciones organizativas pueden declararse junto con el estatus de membresía del proyecto:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

resource "openai_invite" "developer" {
  email = "[email protected]"
  role  = "reader"

  projects = [
    {
      id   = openai_project.production.project_id
      role = "member"
    }
  ]
}

La invitación debe tener estados de ciclo de vida como aceptado o expirado. Después de que el destinatario acepte, el terraform plan debe ejecutarse de nuevo para confirmar que el estado remoto y la configuración coinciden con las expectativas.

Las cuentas de servicio no crean automáticamente claves API

Configurar una cuenta de servicio de proyecto es muy sencillo:

1
2
3
4

resource "openai_project_service_account" "deploy" {
  project_id = openai_project.production.project_id
  name       = "production-deploy"
}

Pero este recurso solo crea la cuenta de servicio en sí. Establece claramente create_service_account_only=true, no asigna roles automáticamente y no crea claves de API. Los roles requieren gestión separada de recursos de Terraform, mientras que las claves de API deben crearse y gestionarse fuera de Terraform mediante APIs públicas. No asumas que las claves directamente utilizables aparecen en la salida del módulo.

Gestionar certificados

Los certificados de organización pueden leerse desde archivos PEM:

1
2
3
4

resource "openai_certificate" "organization" {
  name        = "production-certificate"
  certificate = file("${path.module}/certificates/production.pem")
}

certificate es una propiedad sensible, pero una etiqueta sensible no significa que el contenido no entrará en el archivo de estado. Debes confirmar que el estado remoto está cifrado y restringir el acceso al backend de estado, copias de seguridad y artefactos de CI. Antes de la rotación de certificados, revisa el comportamiento de reemplazo previsto para asegurar que la validez de los solapamientos de los certificados nuevos y antiguos, evitando interrupciones de conexión causadas por un solo apply.

Establecer el rango de acceso al modelo

Los permisos del modelo de proyecto pueden usarse en la lista de permisos:

1
2
3
4
5

resource "openai_project_model_permissions" "production" {
  project_id = openai_project.production.project_id
  mode       = "allow_list"
  model_ids  = ["gpt-5.6-sol"]
}

La identificación de modelos puede cambiar con las actualizaciones del producto. Antes de fusionar configuraciones, verifica los modelos disponibles actualmente y confirma que la migración de la aplicación se ha completado antes de retirar la licencia del modelo anterior.

Gestionar los límites de tasas a nivel de proyecto

openai_project_rate_limit gestiona los objetos existentes con límite de tasa y debe proporcionar el ID del proyecto junto con el rate_limit_id específico:

1
2
3
4
5
6

resource "openai_project_rate_limit" "primary_model" {
  project_id               = openai_project.production.project_id
  rate_limit_id            = "rate_limit_123"
  max_requests_per_1_minute = 500
  max_tokens_per_1_minute   = 200000
}

Los campos gestionables también incluyen el recuento diario de solicitudes, el número máximo de tokens de entrada por lotes por día, imágenes por minuto y MB de audio por minuto. El límite superior configurable real depende de la organización y de las cuotas del modelo. Terraform solo puede gestionar valores aceptados por la API y no puede saltarse las cuotas de la plataforma aumentando los números de configuración.

Importando recursos existentes en Terraform

Para recursos ya creados en consola, no los crees repetidamente; primero escribe la configuración que coincida con el recurso remoto e importa el Estado. Terraform 1.5 y superiores pueden usar import bloques:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import {
  to = openai_project.production
  id = "proj_123"
}

import {
  to = openai_project_service_account.deploy
  id = "proj_123/service_account_123"
}

import {
  to = openai_project_rate_limit.primary_model
  id = "proj_123/rate_limit_123"
}

Diferentes recursos tienen diferentes formatos de ID de importación. Los formatos comunes incluyen un único ID de recurso, project_id/resource_id y un ID compuesto de tres segmentos que contiene usuarios y roles. La sección Importación en la documentación de recursos correspondiente debe usarse como estándar. Después de importar, ejecuta en secuencia:

1
2

terraform plan
terraform state show openai_project.production

Si el plan muestra inmediatamente un gran número de actualizaciones, significa que la configuración local no refleja completamente el estado remoto. Ajusta primero la configuración hasta que el plan cumpla con las expectativas; no sobrescribas la configuración de producción directamente apply.

Usar terraform plan para detectar drift de configuración

Cuando los administradores modifican manualmente miembros, roles o restricciones en la consola, la operación de lectura del Provider compara el estado remoto con la configuración de Terraform. Se pueden usar códigos de salida detallados en CI:

1
2

terraform init -input=false
terraform plan -input=false -detailed-exitcode

El significado del código de salida es:

  • 0: La configuración coincide con el estado remoto sin cambios.
  • 1: Si falla la ejecución del comando, comprueba errores de permiso, red o configuración.
  • 2: Detectar cambios o derivas requiere revisión manual de los planos.

No ejecutes automáticamente apply de producción tras detectar 2 de código de salida. La deriva puede deberse a un manejo de emergencia, revocación de permisos o cambios en el lado de la plataforma. Primero, confirma si restaurar el estado de las declaraciones de código o sincronizar cambios manuales razonables para volver a la configuración.

Estado, permisos y recomendaciones de revisión

La clave API de administrador puede modificar el plano de control organizativo y debe gestionarse como credenciales de alto privilegio. Se recomiendan las siguientes protecciones:

  • El desarrollo local solo inyecta claves a corto plazo a través de variables del entorno.
  • CI utiliza una identidad dedicada y secretos protegidos.
  • El Estado Remoto permite cifrado, bloqueo y retención de versiones.
  • Dividir plan y apply en diferentes etapas de aprobación.
  • Los entornos de producción limitan las sucursales y el personal capaz de ejecutar apply.
  • Rotar regularmente las claves de la API de administrador y revocar las claves no utilizadas.
  • Mantener registros de auditoría para importaciones, cambios de roles y eliminaciones de recursos.

Antes de eliminar elementos, miembros, roles o certificados, revisa los destroy y replace elementos del plan Terraform. Puedes combinar prevent_destroy para recursos críticos, pero no puede sustituir la revisión de cambios y los planes de recuperación.

Preguntas frecuentes

¿Pueden los proveedores llamar a las APIs de modelo?

No, no puede. Apunta a la API de Administración de OpenAI, y la clave de API de administrador no puede usarse para solicitudes de modelos normales.

¿Devuelven los recursos de la cuenta de servicio claves de API?

No, no lo hará. Solo crea cuentas de servicio, y los roles y las claves de API deben gestionarse por separado.

¿Por qué no podemos crear un nuevo objeto de límite de tasa?

Este recurso se utiliza para gestionar los límites de tasa en proyectos existentes y requiere proporcionar rate_limit_id real. 1.0.0 Eliminado el antiguo recurso de límite de tasa agregada.

¿Se pueden detectar cambios manuales en la consola?

Puedes usar terraform plan para detectar diferencias entre el estado remoto y la configuración. Después de detectar la deriva, se debe hacer un juicio manual sobre qué lado usar, en lugar de anular automáticamente de forma incondicional.

¿Hay que reconstruir los proyectos existentes?

No, no es necesario. Usa import bloques o terraform import para añadir recursos a State y luego completa la configuración gradualmente.

Resumen

OpenAI Terraform Provider 1.0 incorpora la gestión de la Plataforma API en el flujo estándar de IaC, adecuada para la gestión unificada de proyectos, miembros, roles, cuentas de servicio, certificados y restricciones de proyectos. Lo más importante a tener en cuenta durante la integración no es un solo terraform apply, sino tres: usar correctamente las claves API de administrador, importar primero los recursos existentes y usar terraform plan como punto de entrada de revisión para permisos y deriva de configuración. En producción, también se presta especial atención a las claves de cuentas de servicio, IDs compuestos de importación de recursos, cambios en el límite de tasa 1.0.0 y seguridad de acceso a Terraform State.

Recursos oficiales