Administrar proyectos y acceso con Terraform

Usa esta guía para crear un proyecto de OpenAI y establecer controles de acceso reutilizables. Definirás qué pueden hacer las identidades mediante un rol de proyecto, reunirás las identidades en un grupo de la organización y vincularás el grupo con el proyecto.

Al completar el flujo de trabajo principal, tendrás una configuración que puedes usar de forma repetible para:

• Crear un proyecto de OpenAI para una aplicación.
• Definir un rol de proyecto con privilegios mínimos.
• Crear un grupo de la organización para las identidades que necesitan acceso.
• Otorgar al grupo acceso al proyecto mediante el rol.
• Agregar al grupo un usuario existente 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 el ID de un usuario existente de la organización y los identificadores de permisos aprobados para la aplicación. Usa una organización de prueba al evaluar el flujo de trabajo.

Al destruir un recurso openai_project, el proyecto se archiva en lugar de eliminarse de forma permanente. No puedes restaurar un proyecto archivado.

Crear el límite del proyecto

Crea un proyecto para la aplicación:

123resource "openai_project" "application" {
  name = "example-application-development"
}

El proyecto delimita el uso de la API, las cuentas de servicio, los límites de solicitudes, las alertas de gasto y la configuración del proyecto de la aplicación. Terraform pone el ID generado a disposición como openai_project.application.project_id. Los recursos del proyecto pueden hacer referencia a ese valor, por lo que Terraform crea el proyecto antes que esos recursos.

Este ejemplo específico usa un nombre concreto. El ejemplo completo que aparece más adelante lo reemplaza con una variable para que puedas reutilizar la configuración en distintos entornos.

Definir los permisos del proyecto

Crea un rol de proyecto con los permisos aprobados para la aplicación:

123456resource "openai_project_role" "application" {
  project_id  = openai_project.application.project_id
  role_name   = "Application API access"
  description = "Permissions approved for this application"
  permissions = ["api.webhooks.read"]
}

El recurso openai_project_role define qué puede hacer una identidad dentro del proyecto. Este ejemplo otorga permiso para leer la configuración de webhooks. Reemplaza api.webhooks.read con los identificadores de permisos aprobados para tu aplicación y comienza solo con los permisos que necesita.

Cambiar permissions actualiza el rol. Ejecuta terraform plan para revisar cada permiso agregado o eliminado antes de aplicar el cambio.

Crear o reutilizar un grupo

Crea un grupo de la organización cuando Terraform deba administrar su ciclo de vida:

123resource "openai_group" "application_access" {
  name = "example-application-development-access"
}

Los grupos existen a nivel de la organización y puedes reutilizarlos en distintos proyectos. Un nombre que termina en -access indica que pertenecer al grupo otorga acceso, en lugar de limitarse a describir un equipo.

Si otro sistema administra un grupo existente, consulta sus datos:

123data "openai_group" "application_access" {
  group_id = "group_123"
}

La fuente de datos consulta el grupo sin que esta configuración se haga responsable de su ciclo de vida. Puedes consultar grupos administrados mediante SCIM, pero realiza los cambios de membresía en el sistema de identidad que los administra.

Otorgar al grupo acceso al proyecto

Vincula el grupo con el rol personalizado dentro del proyecto:

12345resource "openai_project_group_role" "application_access" {
  project_id = openai_project.application.project_id
  group_id   = openai_group.application_access.group_id
  role_id    = openai_project_role.application.role_id
}

Este ejemplo usa el grupo administrado por Terraform. Si reutilizaste un grupo existente mediante la fuente de datos, reemplaza la expresión de group_id con data.openai_group.application_access.group_id.

La asignación vincula tres objetos:

• project_id identifica dónde recibe acceso el grupo.
• group_id identifica qué conjunto de identidades recibe acceso.
• role_id identifica qué permisos recibe el grupo.

Los miembros del grupo heredan el rol personalizado en este proyecto. Agregar un rol o un grupo por sí solo no otorga acceso; la asignación es el vínculo entre ambos.

Agregar usuarios y otras identidades

Agrega una identidad a un grupo de la organización administrado por Terraform con openai_group_user:

1234resource "openai_group_user" "application_developer" {
  group_id = openai_group.application_access.group_id
  user_id  = "user_123"
}

user_id puede identificar a un usuario o una cuenta de servicio existentes de la organización. Para agregar una cuenta de servicio, usa openai_project_service_account.application.id como user_id. Consulta Cuentas de servicio para conocer los requisitos de acceso a cuentas de servicio basado en grupos, autenticación y ciclo de vida de las credenciales.

Usa asignaciones directas de roles cuando el acceso basado en grupos no sea adecuado:

12345resource "openai_project_user_role" "application_developer" {
  project_id = openai_project.application.project_id
  user_id    = "user_123"
  role_id    = openai_project_role.application.role_id
}

Para otorgar permisos en toda la organización, crea un rol de organización y asígnalo directamente o mediante un grupo:

1234567891011121314variable "organization_role_permissions" {
  type = list(string)
}

resource "openai_role" "platform_operator" {
  role_name   = "Platform operator"
  description = "Organization permissions for the platform team"
  permissions = var.organization_role_permissions
}

resource "openai_user_role" "platform_operator" {
  user_id = "user_123"
  role_id = openai_role.platform_operator.role_id
}

Establece organization_role_permissions con los identificadores de permisos aprobados a nivel de la organización. Mantén los permisos de la organización separados de los permisos del proyecto para que cada asignación tenga el alcance mínimo necesario.

Inspeccionar las asignaciones actuales

Consulta los roles de organización y de proyecto asignados a una identidad antes de cambiar el acceso:

12345678910111213141516data "openai_user_roles" "current" {
  user_id = "user_123"
}

data "openai_project_user_roles" "current" {
  project_id = openai_project.application.project_id
  user_id    = "user_123"
}

output "organization_roles" {
  value = data.openai_user_roles.current.roles
}

output "project_roles" {
  value = data.openai_project_user_roles.current.roles
}

Las fuentes de datos muestran las asignaciones actuales, pero no hacen que Terraform sea responsable de ellas.

Eliminar asignaciones

Cuando Terraform ya administra una asignación, eliminar su bloque de recurso hace que el siguiente plan proponga eliminar la asignación remota. Revisa el plan y verifica que otra vía siga otorgando los accesos necesarios.

Para una asignación preexistente, primero declara el recurso correspondiente e impórtalo con el ID compuesto documentado. Confirma que el primer plan no proponga cambios antes de eliminar el recurso de la configuración y aplicar la eliminación.

Consulta Importación y reconciliación para conocer los formatos de importación y una secuencia de adopción segura.

Ejecutar el ejemplo completo

Los ejemplos específicos usan valores concretos para aclarar cada relación. La configuración completa reemplaza los valores repetidos y específicos de cada entorno con variables para que puedas reutilizarla sin cambiar las definiciones de los recursos.

Guarda la siguiente configuración como main.tf:

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162terraform {
  required_version = ">= 1.0"

  required_providers {
    openai = {
      source  = "openai/openai"
      version = ">= 1.0.0"
    }
  }
}

provider "openai" {}

variable "project_name" {
  type = string
}

variable "project_role_permissions" {
  type = list(string)
}

variable "user_id" {
  type = string
}

resource "openai_project" "application" {
  name = var.project_name
}

resource "openai_project_role" "application" {
  project_id  = openai_project.application.project_id
  role_name   = "Application API access"
  description = "Permissions approved for this application"
  permissions = var.project_role_permissions
}

resource "openai_group" "application_access" {
  name = "${var.project_name}-access"
}

resource "openai_project_group_role" "application_access" {
  project_id = openai_project.application.project_id
  group_id   = openai_group.application_access.group_id
  role_id    = openai_project_role.application.role_id
}

resource "openai_group_user" "application_developer" {
  group_id = openai_group.application_access.group_id
  user_id  = var.user_id
}

output "project_id" {
  value = openai_project.application.project_id
}

output "group_id" {
  value = openai_group.application_access.group_id
}

output "project_role_id" {
  value = openai_project_role.application.role_id
}

Crea terraform.tfvars con un nombre de proyecto único, el ID de un usuario existente de la organización y los permisos aprobados:

123456project_name = "example-application-development"
user_id      = "user_123"

project_role_permissions = [
  "api.webhooks.read",
]

Inicializa Terraform y luego revisa y aplica un plan guardado:

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

El primer plan debería incluir cinco recursos para agregar. Después de aplicarlo, el usuario hereda el rol de proyecto personalizado mediante el grupo, y terraform output muestra los ID del proyecto, del grupo y del rol de proyecto. Ejecuta terraform plan de nuevo para confirmar que la configuración no produce más cambios.

Para agregar más usuarios humanos, repite el patrón de membresía del grupo con un nombre de recurso de Terraform único para cada usuario. Para configurar una identidad no humana, consulta Cuentas de servicio. Usa Controles de modelos, herramientas y datos y Límites de solicitudes y gasto para agregar medidas de protección al proyecto.