Administra proyectos y accesos con Terraform

Sigue esta guía para crear un proyecto de OpenAI y establecer controles de acceso reutilizables. Usarás un rol de proyecto para definir qué acciones pueden realizar las identidades, reunirás esas identidades en un grupo de la organización y vincularás el grupo al proyecto.

Al completar el flujo de trabajo principal, tendrás una configuración que podrás volver a usar para lo siguiente:

• Crear un proyecto de OpenAI para una aplicación.
• Definir un rol de proyecto con los 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 los permisos aprobados para la aplicación. Usa una organización de prueba para 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.

Delimita el alcance 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 por parte de la aplicación, sus cuentas de servicio, los límites de solicitudes, las alertas de gasto y la configuración del proyecto. Terraform expone el ID generado como openai_project.application.project_id. Los recursos del proyecto pueden hacer referencia a ese valor, por lo que Terraform crea primero el proyecto.

Este ejemplo usa un nombre concreto. Más adelante, el ejemplo completo lo reemplaza por una variable para que puedas reutilizar la configuración en distintos entornos.

Define 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 los webhooks. Reemplaza api.webhooks.read por los identificadores de los permisos aprobados para tu aplicación y comienza solo con los que necesita.

Al modificar permissions, se actualiza el rol. Ejecuta terraform plan para revisar cada permiso que se agregará o eliminará antes de aplicar el cambio.

Crea o reutiliza un grupo

Crea un grupo de la organización si Terraform debe administrar su ciclo de vida:

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

Los grupos se definen a nivel de la organización y puedes reutilizarlos en varios proyectos. Un nombre que termina en -access indica que pertenecer al grupo otorga acceso y que el nombre no se limita a describir un equipo.

Si otro sistema administra un grupo existente, consulta ese grupo:

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

La fuente de datos consulta el grupo sin que esta configuración se haga cargo de su ciclo de vida. Puedes consultar grupos administrados mediante SCIM, pero debes agregar o quitar miembros desde el sistema de identidades que administra esos grupos.

Otorga al grupo acceso al proyecto

Vincula el grupo al 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 por data.openai_group.application_access.group_id.

La asignación vincula tres objetos:

• project_id identifica el proyecto al que se otorga acceso.
• group_id identifica el grupo de identidades que recibe acceso.
• role_id identifica los permisos que recibe el grupo.

Los miembros del grupo heredan el rol personalizado en este proyecto. Para otorgar acceso, no basta con agregar un rol o un grupo. La asignación establece el vínculo entre ambos.

Agrega 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"
}

El campo user_id puede identificar a un usuario o una cuenta de servicio que ya exista en la organización. Para agregar una cuenta de servicio, usa openai_project_service_account.application.id como valor de user_id. Consulta Cuentas de servicio para conocer los requisitos de acceso mediante grupos, autenticación y gestión del ciclo de vida de las credenciales de las cuentas de servicio.

Asigna roles directamente cuando el acceso mediante 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 que abarquen 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
}

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

Consulta las asignaciones actuales

Antes de modificar el acceso de una identidad, consulta los roles de organización y de proyecto que tiene asignados:

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 sin que Terraform se encargue de administrarlas.

Elimina asignaciones

Si Terraform ya administra una asignación y quitas el bloque de recurso correspondiente, el siguiente plan propondrá eliminar la asignación remota. Revisa el plan y verifica que cualquier acceso necesario siga disponible por otra vía.

Para eliminar una asignación preexistente, primero declara el recurso correspondiente e importa la asignación con el ID compuesto que indica la documentación. Confirma que el primer plan no proponga ningún cambio antes de quitar el recurso de la configuración y aplicar la eliminación.

Consulta Importación y conciliación para conocer los formatos de importación y los pasos para adoptar recursos de forma segura.

Ejecuta el ejemplo completo

Los ejemplos anteriores usan valores concretos para mostrar cómo se relacionan los recursos. La configuración completa reemplaza los valores que se repiten y dependen del entorno por variables. Así puedes 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 el archivo 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. Luego guarda el plan, revísalo y aplícalo:

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

El primer plan debería proponer la creación de cinco recursos. Una vez aplicado, 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. Vuelve a ejecutar terraform plan para confirmar que la configuración no genera más cambios.

Para agregar más usuarios humanos al grupo, sigue el mismo procedimiento y usa un nombre de recurso de Terraform único para cada usuario. Para configurar una identidad no humana, consulta Cuentas de servicio. Sigue las guías Controles de modelos, herramientas y datos y Límites de solicitudes y gasto para agregar medidas de protección al proyecto.