Gerencie projetos e acesso com Terraform

Use este guia para criar um projeto OpenAI e estabelecer controles de acesso reutilizáveis. Você definirá o que as identidades podem fazer por meio de uma função de projeto, reunirá identidades em um grupo da organização e vinculará o grupo ao projeto.

Ao concluir o fluxo de trabalho principal, você terá uma configuração que pode ser replicada e que:

• Cria um projeto OpenAI para uma aplicação.
• Define uma função de projeto com o mínimo de privilégios.
• Cria um grupo na organização para as identidades que precisam de acesso.
• Concede ao grupo acesso ao projeto por meio da função.
• Adiciona ao grupo um usuário existente 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 do ID de um usuário existente da organização e dos identificadores de permissão aprovados para a aplicação. Use uma organização de teste ao avaliar o fluxo de trabalho.

Destruir um recurso openai_project arquiva o projeto em vez de excluí-lo permanentemente. Não é possível restaurar um projeto arquivado.

Estabeleça os limites do projeto

Crie um projeto para a aplicação:

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

O projeto delimita o uso da API, as contas de serviço, os limites de taxa, os alertas de gastos e as configurações de projeto da aplicação. O Terraform disponibiliza o ID gerado em openai_project.application.project_id. Os recursos no nível do projeto podem fazer referência a esse valor, para que o Terraform crie o projeto antes deles.

Este exemplo específico usa um nome concreto. O exemplo completo, mais adiante, substitui esse nome por uma variável para que você possa reutilizar a configuração em diferentes ambientes.

Defina as permissões do projeto

Crie uma função de projeto com as permissões aprovadas para a aplicação:

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

O recurso openai_project_role define o que uma identidade pode fazer dentro do projeto. Este exemplo concede permissão para ler a configuração de webhooks. Substitua api.webhooks.read pelos identificadores de permissão aprovados para sua aplicação e comece apenas com as permissões de que ela precisa.

Alterar permissions atualiza a função. Execute terraform plan para revisar cada permissão adicionada ou removida antes de aplicar a alteração.

Crie ou reutilize um grupo

Crie um grupo na organização quando o Terraform precisar gerenciar seu ciclo de vida:

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

Os grupos existem no nível da organização e podem ser reutilizados em diferentes projetos. Um nome terminado em -access indica que fazer parte do grupo concede acesso, em vez de apenas descrever uma equipe.

Se outro sistema gerencia um grupo existente, apenas consulte-o:

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

A fonte de dados consulta o grupo sem tornar esta configuração responsável por seu ciclo de vida. Você pode consultar grupos gerenciados por SCIM, mas mantenha as alterações de membros no sistema de identidade que os gerencia.

Conceda ao grupo acesso ao projeto

Vincule o grupo à função personalizada dentro do projeto:

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 exemplo usa o grupo gerenciado pelo Terraform. Se você reutilizou um grupo existente por meio da fonte de dados, substitua a expressão de group_id por data.openai_group.application_access.group_id.

A atribuição vincula três objetos:

• project_id identifica onde o grupo recebe acesso.
• group_id identifica qual conjunto de identidades recebe acesso.
• role_id identifica quais permissões o grupo recebe.

Os membros do grupo herdam a função personalizada neste projeto. Adicionar apenas uma função ou um grupo não concede acesso; a atribuição estabelece o vínculo entre eles.

Adicione usuários e outras identidades

Adicione uma identidade a um grupo da organização gerenciado pelo Terraform usando openai_group_user:

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

O campo user_id pode identificar um usuário ou uma conta de serviço existente na organização. Para adicionar uma conta de serviço, use openai_project_service_account.application.id como user_id. Consulte Contas de serviço para saber mais sobre acesso de contas de serviço baseado em grupos, autenticação e requisitos do ciclo de vida das credenciais.

Use atribuições diretas de funções quando o acesso baseado em grupos não for adequado:

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 permissões que abrangem toda a organização, crie uma função de organização e atribua-a diretamente ou por meio de um 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
}

Defina organization_role_permissions com os identificadores de permissão aprovados para o nível da organização. Mantenha as permissões da organização separadas das permissões de projeto para que cada atribuição tenha o menor escopo necessário.

Inspecione as atribuições atuais

Consulte as funções de organização e de projeto atribuídas a uma identidade antes de alterar o acesso:

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
}

As fontes de dados informam as atribuições atuais, mas não tornam o Terraform responsável por elas.

Remova atribuições

Quando o Terraform já gerencia uma atribuição, remover o bloco do recurso faz com que o próximo plano proponha excluir a atribuição remota. Revise o plano e verifique se outra forma de acesso continua garantindo todas as permissões necessárias.

Para uma atribuição preexistente, primeiro declare o recurso correspondente e importe-o usando o ID composto documentado. Confirme que o primeiro plano não propõe nenhuma alteração antes de remover o recurso da configuração e aplicar a exclusão.

Consulte Importação e reconciliação para conhecer os formatos de importação e uma sequência segura de adoção.

Execute o exemplo completo

Os exemplos específicos usam valores concretos para deixar clara cada relação. A configuração completa substitui os valores repetidos e específicos de cada ambiente por variáveis, para que você possa reutilizá-la sem alterar as definições dos recursos.

Salve a configuração a seguir 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
}

Crie terraform.tfvars com um nome de projeto exclusivo, o ID de um usuário existente da organização e as permissões aprovadas:

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

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

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 cinco recursos a serem adicionados. Após a aplicação do plano, o usuário herda a função personalizada do projeto por meio do grupo, e terraform output exibe os IDs do projeto, do grupo e da função de projeto. Execute terraform plan novamente para confirmar que a configuração não produz mais alterações.

Para adicionar mais usuários humanos, repita o padrão de inclusão de membros no grupo com um nome de recurso Terraform exclusivo para cada usuário. Para configurar uma identidade não humana, consulte Contas de serviço. Use Controles de modelos, ferramentas e dados e Limites de taxa e gastos para adicionar mecanismos de proteção ao projeto.