Gerencie projetos e acesso com o Terraform

Use este guia para criar um projeto da OpenAI e configurar controles de acesso reutilizáveis. Você vai definir o que as identidades podem fazer por meio de uma função de projeto, reunir essas 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 reutilizável que:

• Cria um projeto da OpenAI para um aplicativo.
• Define uma função de projeto com o mínimo de privilégios necessários.
• 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 que já faz parte da organização.

Antes de começar

Conclua a configuração do provedor Terraform e exporte uma chave de API de administrador na variável de ambiente OPENAI_ADMIN_KEY. Você também precisa do ID de um usuário que já faz parte da organização e dos identificadores das permissões aprovadas para o aplicativo. Use uma organização de teste para avaliar o fluxo de trabalho.

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

Delimite o escopo do projeto

Crie um projeto para o aplicativo:

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

O projeto delimita o escopo do uso da API, das contas de serviço, dos limites de taxa, dos alertas de gastos e das configurações de projeto do aplicativo. O Terraform disponibiliza o ID gerado em openai_project.application.project_id. Quando recursos no nível do projeto fazem referência a esse valor, o Terraform cria o projeto antes desses recursos.

Este exemplo usa um nome específico. 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 o aplicativo:

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 no projeto. Este exemplo concede permissão para ler a configuração de webhooks. Substitua api.webhooks.read pelos identificadores das permissões aprovadas para o seu aplicativo. Comece apenas com as permissões de que ele 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 for gerenciar o ciclo de vida desse grupo:

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

Os grupos pertencem à organização e podem ser reutilizados em vários projetos. Um nome terminado em -access indica que o grupo tem outra finalidade além de identificar uma equipe: quem faz parte dele recebe acesso.

Se outro sistema já gerencia o grupo, consulte-o por meio de uma fonte de dados:

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

A fonte de dados consulta o grupo sem transferir o gerenciamento do ciclo de vida dele para esta configuração. Você pode consultar grupos gerenciados por SCIM, mas deve adicionar ou remover membros no sistema de identidades responsável por esses grupos.

Conceda ao grupo acesso ao projeto

Vincule o grupo à função personalizada no 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 o projeto ao qual o grupo terá acesso.
• group_id identifica o conjunto de identidades que recebe acesso.
• role_id identifica as permissões que 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 que vincula os dois.

Adicione usuários e outras identidades

Use openai_group_user para adicionar uma identidade a um grupo da organização gerenciado pelo Terraform:

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

O user_id pode identificar um usuário ou uma conta de serviço que já faz parte da 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 como conceder acesso a contas de serviço por meio de grupos e quais são os requisitos de autenticação e de gerenciamento do ciclo de vida das credenciais.

Atribua a função diretamente quando o acesso por grupo 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 válidas em 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 das permissões aprovadas no nível da organização. Mantenha as permissões da organização separadas das permissões do projeto para que cada atribuição tenha o menor escopo necessário.

Consulte as atribuições atuais

Antes de alterar o acesso, consulte as funções de organização e de projeto atribuídas à identidade:

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 mostram as atribuições atuais sem transferir o gerenciamento delas para o Terraform.

Remova atribuições

Quando o Terraform já gerencia uma atribuição, remover o bloco de recurso correspondente faz com que o próximo plano proponha excluir a atribuição remota. Revise o plano e verifique se os acessos necessários continuam garantidos por outros meios.

Para remover uma atribuição preexistente, primeiro declare o recurso correspondente e importe a atribuição usando o ID composto indicado na documentação. 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 a sequência de etapas para adotar recursos existentes com segurança.

Execute o exemplo completo

Os exemplos anteriores usam valores específicos para mostrar como os recursos se relacionam. A configuração completa substitui por variáveis os valores que se repetem e dependem do ambiente. Assim, você pode 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 o arquivo terraform.tfvars com um nome de projeto exclusivo, o ID de um usuário que já faz parte 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, 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 a adição de cinco recursos. Depois que você aplicar o plano, o usuário herdará a função de projeto personalizada por meio do grupo, e terraform output exibirá os IDs do projeto, do grupo e da função de projeto. Execute terraform plan novamente para confirmar que a configuração não gera outras alterações.

Para adicionar mais usuários humanos, repita a configuração que vincula o usuário ao grupo e use um nome de recurso Terraform exclusivo para cada usuário. Para configurar uma identidade não humana, consulte Contas de serviço. Siga os guias Controles de modelos, ferramentas e dados e Limites de taxa e gastos para adicionar proteções ao projeto.