이 가이드에서는 기존 프로젝트에 모델 권한, 호스팅 도구 권한 및 데이터 보존 정책을 적용하는 방법을 설명합니다. 이 설정에 따라 프로젝트의 워크로드에서 사용할 수 있는 모델과 도구, 그리고 프로젝트에 적용할 승인된 보존 정책이 결정됩니다. 사용자나 서비스 계정에 프로젝트 접근 권한을 부여하는 기능은 아닙니다.
워크플로우를 완료하면 다음 작업을 반복해서 수행할 수 있는 구성이 마련됩니다.
- 프로젝트에서 승인된 모델만 사용할 수 있도록 제한합니다.
- 지원되는 각 호스팅 도구의 사용 권한을 명시적으로 설정합니다.
- 조직의 기본 데이터 보존 정책을 프로젝트에 적용합니다.
시작하기 전에
Terraform 프로바이더 설정을 완료하고 관리자 API 키를 OPENAI_ADMIN_KEY 환경 변수로 내보내세요. 다음 항목도 필요합니다.
- 기존 프로젝트의 ID
- 조직에서 사용할 수 있는 모델의 ID
- 프로젝트의 데이터 보존 정책을 관리하려는 경우, 데이터 보존 제어 기능이 활성화된 조직
워크플로우를 시험할 때는 테스트 프로젝트를 사용하세요. 특정 프로젝트에서 호스팅 도구를 비활성화하려면 조직의 도구 정책에서 이미 선택한 프로젝트에만 해당 도구를 허용하고 있어야 합니다. 조직이 모든 프로젝트에 허용한 도구는 개별 프로젝트에서 비활성화할 수 없습니다.
모델 접근 제한하기
openai_project_model_permissions는 개별 프로젝트에 모델 허용 목록 또는 차단 목록을 적용합니다. 다음 예시에서는 gpt-5.4-mini만 허용합니다.
resource "openai_project_model_permissions" "application" {
project_id = "proj_123"
mode = "allow_list"
model_ids = ["gpt-5.4-mini"]
}mode에 다음 값 중 하나를 지정하세요.
allow_list를 지정하면model_ids에 있는 모델만 허용합니다.deny_list를 지정하면model_ids에 있는 모델을 제외한 나머지 사용 가능한 모델을 허용합니다.
모든 모델 ID는 조직에서 조회할 수 있어야 합니다. 정책에 추가하는 파인튜닝 모델의 스냅샷 ID도 마찬가지입니다. Terraform은 다음 실행 계획에 모드와 모델 목록의 변경 사항을 포함하고, 계획을 적용할 때 이를 반영합니다.
호스팅 도구 설정하기
openai_project_hosted_tool_permissions는 프로젝트 수준에서 다섯 가지 도구의 권한을 관리합니다. 검토할 구성에 전체 정책이 드러나도록 모든 필드를 설정하세요.
resource "openai_project_hosted_tool_permissions" "application" {
project_id = "proj_123"
file_search_enabled = true
web_search_enabled = false
image_generation_enabled = false
mcp_enabled = false
code_interpreter_enabled = true
}각 필드는 파일 검색, 웹 검색, 이미지 생성, 원격 MCP 서버, 코드 인터프리터의 사용 권한을 제어합니다. 조직의 호스팅 도구 정책에는 모든 프로젝트에서 허용, 모든 프로젝트에서 차단, 선택한 프로젝트에서만 허용이라는 세 가지 모드가 있습니다. 필드를 true로 설정하면 조직의 다른 사용 자격 요건과 보존 요건을 충족하는 경우 해당 프로젝트에서 도구를 사용할 수 있습니다. 필드를 false로 설정하면 해당 도구를 사용할 수 있도록 선택한 프로젝트 목록에서 이 프로젝트가 제외됩니다. 현재 조직이 모든 프로젝트에 해당 도구를 허용하고 있다면 필드를 false로 설정하는 작업은 실패합니다. 개별 프로젝트에서 도구를 비활성화하려면 먼저 조직의 도구 정책을 변경해 선택한 프로젝트에만 도구를 허용하세요.
Terraform은 OpenAI에서 다섯 필드의 최신 값을 모두 가져옵니다. 대시보드에서 값을 변경하면 다음 실행 계획에 드리프트로 표시됩니다.
데이터 보존 설정하기
openai_project_data_retention은 개별 프로젝트에 승인된 데이터 보존 유형을 적용합니다. 프로젝트에 별도로 승인된 설정이 없다면 조직의 현재 정책을 상속하세요.
resource "openai_project_data_retention" "application" {
project_id = "proj_123"
type = "organization_default"
}프로바이더는 none, zero_data_retention, modified_abuse_monitoring, enhanced_zero_data_retention, enhanced_modified_abuse_monitoring도 지원합니다. 사용할 수 있는 모드와 허용되는 모드 간 전환은 조직의 설정과 프로젝트의 데이터 레지던시 리전에 따라 다릅니다.
프로젝트에 조직 기본값과 다른 설정을 지정하기 전에 사용자 데이터 문서와 조직이 OpenAI와 체결한 계약을 검토하세요.
조직 기본값 관리하기
Terraform으로 기존 조직 수준 설정을 관리하는 경우에만 openai_organization_data_retention을 사용하세요.
resource "openai_organization_data_retention" "default" {
type = "zero_data_retention"
}이 리소스는 기존 조직 설정을 변경합니다. 조직을 데이터 보존 프로그램에 등록하는 기능은 없습니다. 보존 등급 간 전환 중에는 지원팀의 도움이 필요하거나 전환 자체가 불가능한 경우가 있습니다.
구성에서 openai_project_hosted_tool_permissions 또는
openai_project_data_retention을 제거하면 Terraform 상태에서 해당 리소스가 제거되지만 원격 설정은 그대로 유지됩니다.
openai_project_model_permissions를 제거하면 프로젝트의 모델 권한 구성이 삭제됩니다.
삭제 계획을 검토할 때는 리소스별로 어떤 설정이 삭제되는지 확인하세요.
Terraform 외부에서 발생한 변경 감지하기
다음 명령을 실행해 최신 원격 상태를 가져오고 검토한 구성과 비교하세요.
terraform plan -detailed-exitcode종료 코드 0은 변경 사항이 없음을, 2는 실행 계획에 변경 사항이 있음을, 1은 Terraform 실행 중 오류가 발생했음을 나타냅니다. 예상치 못한 변경 사항은 계획을 적용하기 전에 원인을 확인하세요. 관리자가 긴급하게 변경한 설정은 그 목적을 파악하기 전에 자동으로 덮어쓰지 마세요.
전체 예시 실행하기
다음 예시에서는 세 가지 프로젝트 설정을 함께 관리합니다. main.tf를 만드세요.
terraform {
required_version = ">= 1.0"
required_providers {
openai = {
source = "openai/openai"
version = ">= 1.0.0"
}
}
}
provider "openai" {}
variable "project_id" {
type = string
description = "ID of the existing OpenAI project."
}
variable "model_permission_mode" {
type = string
description = "Whether model_ids is an allowlist or denylist."
default = "allow_list"
validation {
condition = contains(["allow_list", "deny_list"], var.model_permission_mode)
error_message = "The model permission mode must be allow_list or deny_list."
}
}
variable "model_ids" {
type = list(string)
description = "Model IDs included in the project model policy."
}
variable "hosted_tools" {
type = object({
file_search = bool
web_search = bool
image_generation = bool
mcp = bool
code_interpreter = bool
})
description = "Hosted tools enabled for the project."
}
variable "project_data_retention_type" {
type = string
description = "Approved data-retention type for the project."
validation {
condition = contains([
"organization_default",
"none",
"zero_data_retention",
"modified_abuse_monitoring",
"enhanced_zero_data_retention",
"enhanced_modified_abuse_monitoring",
], var.project_data_retention_type)
error_message = "Provide a supported project data-retention type."
}
}
resource "openai_project_model_permissions" "application" {
project_id = var.project_id
mode = var.model_permission_mode
model_ids = var.model_ids
}
resource "openai_project_hosted_tool_permissions" "application" {
project_id = var.project_id
file_search_enabled = var.hosted_tools.file_search
web_search_enabled = var.hosted_tools.web_search
image_generation_enabled = var.hosted_tools.image_generation
mcp_enabled = var.hosted_tools.mcp
code_interpreter_enabled = var.hosted_tools.code_interpreter
}
resource "openai_project_data_retention" "application" {
project_id = var.project_id
type = var.project_data_retention_type
}
output "controlled_project_id" {
value = var.project_id
}
output "model_permission_mode" {
value = openai_project_model_permissions.application.mode
}
output "project_data_retention_type" {
value = openai_project_data_retention.application.type
}terraform.tfvars를 만들고 기존 프로젝트의 ID, 조직에서 조회할 수 있는 모델 ID, 호스팅 도구 정책, 승인된 데이터 보존 유형을 지정하세요.
project_id = "proj_123"
model_permission_mode = "allow_list"
model_ids = ["gpt-5.4-mini"]
hosted_tools = {
file_search = true
web_search = true
image_generation = true
mcp = true
code_interpreter = true
}
project_data_retention_type = "organization_default"이 예시는 조직 정책이 모든 프로젝트에 도구를 허용하는 경우에도 실행할 수 있도록 모든 호스팅 도구를 활성화합니다. 값을 false로 변경하려면 먼저 해당 도구의 조직 정책이 선택한 프로젝트에만 사용을 허용하도록 설정되어 있어야 합니다. 적용하기 전에 조직에서 해당 모델 ID와 데이터 보존 유형을 사용할 수 있는지 확인하세요.
Terraform을 초기화한 다음 실행 계획을 저장하고 검토한 뒤 적용하세요.
terraform init
terraform fmt
terraform validate
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan첫 번째 실행 계획에는 추가할 리소스가 세 개 표시되어야 합니다. 호스팅 도구와 데이터 보존의 경우, 리소스 추가는 Terraform이 프로젝트마다 하나씩 있는 기존 설정을 관리하기 시작한다는 뜻입니다. 별도의 원격 객체가 생성되지는 않습니다. 모델 권한 리소스는 프로젝트의 모델 권한 구성을 생성하거나 업데이트합니다.
terraform plan을 다시 실행해 구성에 따른 추가 변경 사항이 없는지 확인하세요. 드리프트가 표시되면 다시 변경 사항을 적용하기 전에 다른 관리자나 자동화 작업이 프로젝트 설정을 변경했는지 확인하세요.