Terraform으로 모델·도구·데이터 제어하기
Terraform으로 모델·도구·데이터 제어하기 (Model, tool, and data controls with Terraform)
출처: 문서
이 가이드로 기존 프로젝트에 모델, 호스팅 도구(hosted tool), 데이터 보존 제어를 적용해요. 이 제어들은 프로젝트 워크로드가 무엇을 사용할 수 있는지와 어떤 승인된 보존 정책이 적용되는지 결정해요. 사용자나 서비스 계정에 프로젝트 접근 권한을 부여하지는 않아요.
메인 워크플로를 완료하면 다음과 같은 반복 가능한 구성을 갖게 돼요:
- 프로젝트를 승인된 모델 집합으로 제한해요.
- 지원되는 모든 호스팅 도구에 대해 명시적인 권한을 설정해요.
- 프로젝트에 조직의 기본 데이터 보존 정책을 적용해요.
시작하기 전에
Terraform 프로바이더 설정을 완료하고 Admin API 키를 OPENAI_ADMIN_KEY로 export해요. 다음도 필요해요:
- 기존 프로젝트의 ID.
- 조직에서 사용할 수 있는 모델의 ID.
- 프로젝트 보존을 관리할 계획이라면 데이터 보존 제어가 활성화된 조직.
워크플로를 평가할 때는 테스트 프로젝트를 사용해요. 한 프로젝트에서 호스팅 도구를 비활성화하려면 조직 수준 도구 정책이 이미 해당 도구를 선택된 프로젝트로 제한하고 있어야 해요. 프로젝트는 조직이 모든 프로젝트에 대해 활성화한 도구를 비활성화할 수 없어요.
모델 접근 제한하기
openai_project_model_permissions는 한 프로젝트에 allowlist 또는 거부 목록(deny list)을 적용해요. 이 예시는 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는 조직에 보여야 해요. 여기에는 정책에 추가하는 모든 파인튜닝 모델 스냅샷도 포함돼요. Terraform은 다음 plan과 apply에서 모드와 모델 목록의 변경을 조정해요.
호스팅 도구 구성하기
openai_project_hosted_tool_permissions는 5개의 프로젝트 수준 도구 권한을 관리해요. 검토된 구성이 완전한 정책을 설명하도록 모든 필드를 설정해요:
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
}
이 필드들은 file search, web search, image generation, 원격 MCP 서버, Code Interpreter를 제어해요. 각 조직의 호스팅 도구 정책에는 세 가지 모드가 있어요: 모든 프로젝트 허용, 모든 프로젝트 거부, 선택된 프로젝트 허용. 필드를 true로 설정하면 조직의 다른 자격·보존 요구사항에 따라 해당 도구를 프로젝트에 허용해요. 필드를 false로 설정하면 프로젝트를 해당 도구의 선택된 프로젝트 정책에서 제거해요. 조직이 현재 모든 프로젝트에 도구를 허용하고 있다면 필드를 false로 설정하면 실패해요. 개별 프로젝트에서 도구를 비활성화하기 전에 조직의 도구 정책을 선택된 프로젝트 허용으로 변경해요.
Terraform은 다섯 값을 모두 OpenAI에서 새로고침하며, 다음 plan에서 대시보드 변경을 드리프트로 보고해요.
데이터 보존 구성하기
openai_project_data_retention은 승인된 보존 유형을 한 프로젝트에 적용해요. 프로젝트에 승인된 재정의(override)가 없으면 조직의 현재 정책을 상속해요:
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도 허용해요. 사용 가능한 모드와 허용되는 전환은 조직의 구성과 프로젝트의 데이터 상주(residency) 지역에 따라 달라져요.
프로젝트 재정의를 선택하기 전에 Your data와 조직의 OpenAI 계약을 검토해요.
조직 기본값 관리하기
openai_organization_data_retention은 Terraform이 기존 조직 수준 설정을 소유할 때만 사용해요:
resource "openai_organization_data_retention" "default" {
type = "zero_data_retention"
}
이 리소스는 기존 조직 설정을 변경하지, 조직을 데이터 보존 프로그램에 등록하지 않아요. 일부 전환은 지원이 필요하거나 보존 등급(tier) 간에 사용할 수 없어요.
openai_project_hosted_tool_permissions 또는 openai_project_data_retention을 구성에서 제거하면 리소스가 Terraform 상태에서 제거되지만 원격 설정은 그대로 남아요. openai_project_model_permissions를 제거하면 프로젝트의 모델 권한 구성이 삭제돼요. 이 서로 다른 동작을 염두에 두고 destroy 계획을 검토해요.
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
}
기존 프로젝트 ID, 볼 수 있는 모델 ID, 호스팅 도구 정책, 승인된 보존 유형으로 terraform.tfvars를 만들어요:
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이 기존의 단일 톤(singleton) 프로젝트 설정을 관리하기 시작함을 의미하지, 별도의 원격 객체를 만드는 것은 아니에요. 모델 권한은 프로젝트의 모델 권한 구성을 만들거나 업데이트해요.
terraform plan을 다시 실행해서 구성이 더 이상 변경을 생성하지 않는지 확인해요. 드리프트가 표시되면 다른 업데이트를 적용하기 전에 다른 관리자나 자동화가 프로젝트 제어를 변경했는지 판단해요.