OpenAI Terraform provider: 파괴적인 드리프트(drift) 없이 API 리소스를 가져오기

빠른 답변 (Quick answer)

OpenAI는 2026년 7월 29일에 공식 Terraform provider를 출시했습니다. 이는 프로젝트, 사용자, 그룹, 역할, 액세스 할당, 서비스 계정, 인증서, 프로젝트 속도 제한(rate limits), 지출 알림, 모델 권한, 호스팅 도구 권한 및 데이터 보존 설정을 포함한 API 플랫폼 관리 리소스를 관리합니다.

라이브 대시보드를 Terraform으로 번역하고 바로 apply를 실행하는 것으로 시작하지 마십시오. 먼저 각 리소스를 어떤 시스템이 소유할지 결정해야 합니다. 외부에서 소유한 객체는 데이터 소스(data sources)를 통해 읽어오고, Terraform이 소유할 객체만 가져오기(import) 하십시오. 구성을 현재의 원격 설정과 일치시키고, 저장된 가져오기 계획(import plan)을 검토한 후 적용(apply)하십시오. 그리고 다음 terraform plan 실행 시 변경 사항이 보고되지 않아야 합니다. 그 이후에 의도적인 변경을 도입하십시오.

이 provider는 모델 배포 도구가 아니며, ChatGPT나 로그인된 Codex 설정을 구성하지 않습니다. 이는 Administration API를 통해 OpenAI API 플랫폼 리소스를 제어합니다. Terraform 마이그레이션이 Codex 모델 은퇴 마이그레이션 또는 애플리케이션 수준의 모델 라우팅과 혼동되지 않도록 이 경계를 명확히 유지하십시오.

대상 (Who this is for)

이 가이드는 이미 대시보드에 OpenAI API 프로젝트, ID, 제한 사항 또는 제어 항목을 보유하고 있으며, 운영 리소스를 재생성하지 않고 재현 가능한 인프라를 원하는 소규모 플랫폼 팀 또는 독립 개발자를 위한 것입니다. 또한 두 번째 환경에 동일한 최소 권한 정책(least-privilege policy)과 비용 제어가 필요한 경우에도 유용합니다.

이 provider는 Terraform 1.0 이상과 OpenAI Admin API 키를 필요로 합니다. 선언적 가져오기 블록(Declarative import blocks)을 사용하려면 Terraform 1.5 이상이 필요합니다. 실제 리소스를 도입하기 전에 테스트 조직이나 프로젝트에서 워크플로우를 평가하십시오.

리소스를 작성하기 전에 소유권 선택하기

세 가지 소유권 경로(ownership lanes)를 사용하십시오. 이들을 혼합하는 것은 구성 드리프트(configuration drift)를 실수에 의한 삭제나 중복 ID 생성으로 이어지게 하는 가장 빠른 방법입니다.

예를 들어, SCIM으로 관리되는 그룹은 Terraform이 멤버십을 책임지도록 가져오기(import)보다는 데이터 소스로 유지하십시오. 프로젝트 역할(project role)은 Terraform이 해당 권한 세트(permission set)를 소유할 때만 가져오십시오. 새로운 서비스 계정(service account)은 자격 증명 전달 및 로테이션(rotation) 경로가 준비되었을 때만 생성하십시오.

7단계 도입 워크플로우

1. 원격 진실(remote truth) 및 소유자 인벤토리 작성

범위 내의 모든 프로젝트, 그룹, 역할(role), 할당(assignment), 서비스 계정(service account), 속도 제한(rate-limit) 레코드, 지출 알림(spend alert), 모델 정책(model policy), 호스팅 도구 정책(hosted-tool policy), 데이터 보존 설정(data-retention setting) 및 인증서를 기록하십시오. 각 객체에 대해 안정적인 ID, 현재 설정, 비즈니스 소유자, 현재 컨트롤 플레인(control plane) 및 원하는 Terraform lane을 캡처하십시오.

OpenAI 대시보드에서의 가시성만으로 소유권을 추론하지 마십시오. 그룹은 ID 제공업체(identity provider)로부터 동기화될 수 있으며, 속도 제한 레코드는 OpenAI에 의해 생성되고 Terraform에 의해서만 업데이트될 수 있습니다. 서비스 계정 키는 별도의 비밀 관리자(secrets manager)에 존재할 수 있습니다.

2. 프로바이더(provider) 고정 및 자격 증명 분리

공식 openai/openai 프로바이더를 사용하고 .terraform.lock.hcl을 커밋하여 이후 실행 시 검토된 프로바이더 버전을 선택하도록 하십시오. Admin API 키는 프로바이더 블록이나 체크인된 변수 파일이 아닌 OPENAI_ADMIN_KEY를 통해 제공하십시오.

terraform {
  required_version = ">= 1.5"

...

Admin API 키는 애플리케이션 키가 아닌 관리용 자격 증명(administrative credential)입니다. 보호된 환경에서 Terraform을 실행하고, 로그 및 Plan 액세스를 제한하며, 상태(state) 저장소의 암호화, 잠금(locking), 액세스 제어, 버전 관리 및 복구에 동일한 주의를 기울이십시오.

3. 원격 객체를 존재하는 그대로 선언

영향력이 낮은 리소스 하나부터 시작하십시오. 해당 리소스의 현재 이름과 관계를 사용한 다음, 문서화된 가져오기 ID (import ID)를 연결하십시오. 프로젝트는 프로젝트 ID를 사용하고, 프로젝트 서비스 계정 (service account)은 /를 사용하며, 할당 (assignments)은 복합 ID (composite IDs)를 사용합니다.

resource "openai_project" "existing" {
  name = "existing-project"
}
...

기존 객체를 가져오기(import) 전에 리소스 선언을 적용하지 마십시오. 서비스 계정의 경우, 그러한 순서로 진행하면 기존의 라이브 계정을 채택하는 대신 두 번째 ID를 생성하게 됩니다.

4. 가져오기 전용 저장된 계획 (saved plan) 요구

terraform init
terraform fmt -check
terraform validate
...

저장된 계획 (plan)에는 원격 업데이트 없이 가져오기 작업만 표시되어야 합니다. 만약 이름 변경, 교체 (replacement), 권한 변경 또는 삭제를 제안한다면, 즉시 중단하고 구성을 원격 상태의 진실 (remote truth)과 일치시키십시오. 검토된 계획을 적용한 후, 다시 terraform plan을 실행하십시오. 채택의 관문은 단순히 성공적인 가져오기 명령이 아니라, 변경 사항이 없는 (no-op) 결과입니다.

자동화를 위해, terraform plan -detailed-exitcode는 변경 사항이 없으면 0을, 변경 사항이 존재하면 2를, 오류가 발생하면 1을 반환합니다. 2를 억제해야 할 실패한 셸 명령이 아니라, 검토가 필요한 증거로 취급하십시오.

5. 의도적인 가드레일(guardrail) 하나 추가

변경 사항이 없는 (no-op) 기준점을 만든 후, 제한된 변경 사항 하나를 도입하십시오: 최소 권한 프로젝트 역할 (least-privilege project role), 명시적인 모델 허용 목록 (model allowlist), 하나의 호스팅 도구 정책 (hosted-tool policy), 속도 제한 (rate-limit) 조정, 또는 지출 알림 (spend alert) 등이 있습니다. 계획을 저장하고 리소스 ID, 프로젝트 ID, 추가, 제거 및 교체 마커를 확인하십시오.

지출 알림 (spend alert)을 강제 한도 (hard cap)와 혼동하지 마십시오. 프로바이더의 지출 알림 리소스는 알림을 보낼 뿐, 요청을 중단시키지는 않습니다. 트래픽 중단이 의도된 안전 경계인 경우, 알림을 OpenAI hard-spend-limit runbook과 함께 사용하십시오.

6. 서비스 계정 키를 Terraform 외부로 유지

이 프로바이더(provider)는 기본 역할(role)이나 API 키가 없는 서비스 계정(service-account) ID를 생성합니다. 좁은 범위의 사용자 정의 프로젝트 역할(custom project role)을 할당한 다음, Administration API를 통해 범위가 제한된 API 키를 생성하고 이를 승인된 비밀 관리자(secrets manager)로 직접 전달하십시오. 전체 키는 생성(create) 응답에서만 확인할 수 있습니다.

절대로 키를 Terraform 구성(configuration), 변수(variables), 출력(outputs) 또는 상태(state)에 포함하지 마십시오. 서비스 계정을 가져오기(importing) 한다고 해서 기존 키가 복구되지는 않습니다. 키 순환(rotation)을 위해서는 교체할 ID를 생성하고, 동일한 좁은 범위의 역할을 부여하며, 새 비밀(secret)을 발급 및 검증한 뒤, 워크로드(workload)를 이동시키고, 이전 키를 취소(revoke)한 다음, 마지막으로 이전 ID를 삭제하십시오.

7. 드리프트(drift) 테스트 및 삭제 동작 확인

테스트 프로젝트에서 해롭지 않은 대시보드 변경을 한 번 수행하고, plan을 실행하여 드리프트(drift)가 가시적으로 나타나는지 확인하십시오. 원격 변경 사항이 권위 있는(authoritative) 것인지 아니면 되돌려야 하는 것인지 결정하여 이를 조정(reconcile)하고, 변경 사항이 없는(no-op) plan이 다시 나타나는지 확인하십시오.

그 다음 삭제 의미론(removal semantics)을 테스트하십시오. 블록(block)을 제거하는 것이 모든 OpenAI 리소스에 대해 동일한 의미를 갖지는 않습니다.

이것이 중요한 롤백 경계(rollback boundary)입니다. 상태(state)에서만 제거하는 것은 오래된 정책을 활성 상태로 남겨둘 수 있지만, 프로젝트 제거는 되돌릴 수 없는 아카이브입니다. 일반적인 destroy라는 단어에 의존하는 대신, 검토 과정에서 명시적인 제거 매트릭스(removal matrix)를 요구하십시오.

8가지 배포 게이트(rollout gates)

간결한 채택 기록을 유지하십시오:

organization: org_redacted
project: proj_redacted
provider: openai/openai
...

흔한 실수

모든 가시적인 객체를 Terraform 소유로 취급하는 것. SCIM, 다른 IaC 스택 또는 승인된 수동 프로세스에 의해 제어되는 리소스에는 데이터 소스(data sources)를 사용하십시오.

가져오기(import) 전에 적용(apply)하는 것. 기존 서비스 계정에 대한 선언(declaration)은 가져오기가 먼저 수행되지 않았을 경우 중복된 ID를 생성할 수 있습니다.

상태(state) 제거가 플랫폼을 초기화한다고 가정하는 경우. Rate limits (속도 제한), hosted-tool (호스팅된 도구) 권한, 그리고 data-retention (데이터 보존) 리소스는 상태(state)에서 제거된 후에도 원격 설정(remote setting)이 그대로 남아 있을 수 있습니다.

워크로드 API 키를 Terraform에 넣는 것. 공식 워크플로우는 의도적으로 Terraform 외부에서 서비스 계정 키를 생성합니다. 이러한 분리 상태를 유지하십시오.

Terraform 모델 권한을 애플리케이션 라우팅으로 사용하는 것. 프로젝트 허용 목록(allowlists)은 무엇을 사용할 수 있는지를 정의하지만, 모델을 선택하는 것은 여전히 애플리케이션입니다. 애플리케이션의 선택 사항은 GPT-5.6 model guide에서 별도로 비교해 보십시오.

FAQ

OpenAI Terraform provider가 모델을 배포할 수 있나요?

아니요. 이 프로바이더는 OpenAI API 플랫폼 관리 리소스와 프로젝트 제어(controls)를 관리합니다. 프로젝트가 사용할 수 있는 모델을 제한할 수는 있지만, 모델을 배포하거나 애플리케이션 요청을 위한 모델을 선택하지는 않습니다.

기존의 모든 OpenAI 리소스를 가져오기(import) 해야 하나요?

아니요. Terraform이 소유하게 될 리소스만 가져오십시오. 다른 시스템이 권한(authoritative)을 유지하는 경우에는 data sources (데이터 소스)를 사용하고, 지원되지 않거나 의도적으로 수동 관리되는 리소스는 승인된 인벤토리에 그대로 두십시오.

성공적인 가져오기(import)만으로 프로덕션 변경을 시작하기에 충분한가요?

아니요. 가져오기 후 첫 번째 plan (계획) 단계에서는 변경 사항이 나타나지 않아야 합니다. 이러한 no-op (변경 없음) 상태는 의도적인 업데이트를 도입하기 전에 구성(configuration)이 원격의 실제 상태(remote truth)를 정확히 설명하고 있음을 증명합니다.

구성(configuration)에서 리소스를 제거하면 롤백(roll back)되나요?

신뢰할 수 없습니다. 그 효과는 리소스마다 다릅니다. 프로젝트는 아카이브(archive)되고 서비스 계정은 삭제되지만, 일부 프로젝트 제어 항목은 Terraform 상태(state)에서만 제거되고 원격에서는 활성 상태로 남아 있습니다. 각 유형에 대해 프로바이더 문서와 저장된 destroy plan (삭제 계획)을 검토하십시오.

Sources

소스(Sources)

• OpenAI API 변경 로그: 공식 Terraform 프로바이더
• OpenAI Terraform 프로바이더 개요
• 프로젝트 및 액세스 관리
• 서비스 계정 관리
• 속도 제한 및 지출(Rate limits and spend)
• 모델, 도구 및 데이터 제어(Model, tool, and data controls)
• 리소스 가져오기 및 조정(Import and reconcile resources)
• 공식 프로바이더 저장소

원래 게시일: IndieSeek.