OpenAI Terraform provider 운영법: 프로젝트·권한·비용 제한을 코드로 관리하는 방법

OpenAI Terraform provider는 OpenAI API 조직 리소스를 infrastructure as code로 관리하기 위한 공식 provider입니다. OpenAI 문서에 따르면 이 provider는 Administration API를 사용해 projects, users, groups, roles, service accounts, certificates, rate limits, spend alerts, project settings를 관리합니다. 개발팀이 봐야 할 핵심은 모델 호출 코드가 아니라 운영 제어면입니다. 누가 어떤 프로젝트를 쓰고, 어떤 서비스 계정이 있고, 얼마까지 쓸 수 있는지를 Terraform plan으로 검토할 수 있게 됩니다.

AI API가 실험 단계일 때는 콘솔에서 프로젝트 하나 만들고 키를 발급해도 됩니다. 하지만 팀과 서비스가 늘어나면 곧 문제가 생깁니다. 테스트용 키가 운영 서버에 들어가고, 퇴사자 계정이 프로젝트 권한을 유지하고, 비용 제한이 누락되고, rate limit 변경 이력이 Slack 어딘가에 묻힙니다. Terraform provider는 이 문제를 클라우드 인프라와 같은 방식으로 다루게 해줍니다.

무엇을 코드로 관리할 수 있나

문서 기준으로 provider가 다루는 범위는 꽤 넓습니다. 프로젝트 생성, 사용자와 그룹 접근, 역할 기반 권한, 서비스 계정, 인증서, rate limit, spend alert, 모델·도구·데이터 retention 관련 project control까지 포함됩니다. 즉, 단순히 API key를 만드는 도구가 아니라 조직 운영 레이어를 관리하는 도구입니다.

예를 들어 제품별로 OpenAI project를 나누는 팀이라면 product-api-prod, product-api-staging, internal-tools 같은 프로젝트를 Terraform으로 선언할 수 있습니다. 각 프로젝트에 접근 가능한 그룹을 붙이고, 서비스 계정을 따로 만들고, 월간 spend alert와 rate limit을 명시합니다. 변경이 필요하면 콘솔에서 직접 바꾸는 대신 pull request로 변경합니다.

이 방식의 장점은 재현성입니다. 어떤 프로젝트가 왜 만들어졌고 누가 접근 가능한지 Git history에 남습니다. 비용 제한을 올릴 때도 plan diff가 남습니다. 보안 사고가 났을 때 ‘현재 콘솔 상태’를 뒤지는 대신 코드와 state를 기준으로 추적할 수 있습니다.

Admin API key를 다루는 방식

OpenAI Terraform provider는 OPENAI_ADMIN_KEY 환경변수를 기본으로 읽습니다. 여기서 중요한 점은 Administration API key가 일반 모델 호출용 API key와 다르다는 것입니다. 문서도 admin endpoint는 Admin API key가 필요하고, 이 키는 일반 OpenAI API endpoint에서는 작동하지 않는다고 설명합니다.

운영에서는 이 키를 절대 Terraform 파일에 넣으면 안 됩니다. 로컬에서는 환경변수로 주입하고, CI에서는 secrets manager나 CI secret store를 사용해야 합니다. 또한 가능하면 Terraform 실행 권한을 제한된 파이프라인에만 줘야 합니다. Admin key는 조직 리소스를 바꿀 수 있으므로 일반 애플리케이션 런타임에 들어가면 안 됩니다.

선택적으로 OPENAI_ORG_ID, OPENAI_PROJECT_ID도 설정할 수 있습니다. 여러 조직이나 프로젝트를 다루는 환경에서는 명시하는 편이 안전합니다. 키에서 자동 해석되도록 두면 편하지만, CI가 잘못된 secret을 물고 실행될 때 피해를 키울 수 있습니다.

최소 구성 예시와 운영 패턴

문서의 기본 예시는 openai_project 하나를 만드는 형태입니다. 실무에서는 여기에 네 가지를 추가하는 편이 좋습니다.

첫째, 프로젝트 naming convention입니다. 서비스명, 환경, 용도를 이름에 넣습니다. 둘째, 접근 그룹입니다. 개인 사용자 직접 권한보다 그룹 기반 접근이 나중에 정리하기 쉽습니다. 셋째, 서비스 계정입니다. 서버 workload에는 사람 계정 대신 service account를 씁니다. 넷째, 비용과 rate limit입니다. 실험 프로젝트는 낮은 한도를 두고 운영 프로젝트는 알림과 escalation 기준을 둡니다.

Terraform 실행 흐름은 익숙합니다. terraform init, terraform fmt, terraform validate, terraform plan, terraform apply입니다. .terraform.lock.hcl은 커밋해서 provider 버전을 고정하는 편이 좋습니다. provider upgrade는 별도 PR로 분리해야 예상치 못한 resource schema 변경을 추적할 수 있습니다.

기존 콘솔 리소스는 어떻게 가져올까

이미 콘솔에서 만든 프로젝트가 많다면 새로 만들기보다 import와 reconciliation이 먼저입니다. OpenAI 문서도 import and reconciliation guide를 별도로 제공합니다. 핵심은 ‘Terraform이 현재 상태를 모르는데 apply부터 하지 말라’입니다.

기존 리소스를 import하지 않고 같은 이름으로 선언하면 충돌이 나거나, 더 나쁘게는 중복 리소스를 만들 수 있습니다. 따라서 1단계는 inventory입니다. 현재 프로젝트, 사용자, 그룹, 서비스 계정, spend limit, rate limit을 export하거나 콘솔에서 정리합니다. 2단계는 Terraform resource로 선언합니다. 3단계는 import합니다. 4단계는 plan으로 drift를 확인합니다. 5단계부터 변경을 시작합니다.

이 과정은 귀찮지만 한 번 끝내면 운영이 훨씬 안정됩니다. 특히 AI API 비용이 팀별로 늘어나는 조직에서는 누가 어떤 프로젝트에서 비용을 쓰는지 보여주는 기준점이 됩니다.

비용 제한과 rate limit을 코드에 넣는 이유

AI API 운영에서 비용 사고는 대부분 악의가 아니라 루프, 재시도, 잘못된 배치, 예상보다 긴 context에서 발생합니다. 콘솔 알림만 믿으면 사고 후에 알게 됩니다. Terraform으로 spend alert와 hard/soft limit을 관리하면 새 프로젝트가 생길 때 비용 제한이 빠지는 일을 줄일 수 있습니다.

rate limit도 마찬가지입니다. 개발 환경 프로젝트에 운영 수준 limit을 주면 실험 코드가 provider quota를 잡아먹을 수 있습니다. 반대로 운영 프로젝트 limit이 너무 낮으면 장애로 보입니다. 환경별 limit을 코드에 명시하고 review하면 변경 이유를 남길 수 있습니다.

도입 전 체크리스트

• OpenAI 조직에서 Admin API key 발급 권한을 확인한다.
• Admin key를 Terraform 파일이나 저장소에 절대 커밋하지 않는다.
• 프로젝트 naming convention을 먼저 정한다.
• 기존 콘솔 리소스를 inventory로 정리한다.
• 기존 리소스는 import 후 plan으로 drift를 확인한다.
• 사용자 직접 권한보다 그룹 기반 접근을 우선한다.
• 서버 workload는 service account로 분리한다.
• 프로젝트별 spend alert와 rate limit을 기본값으로 둔다.
• .terraform.lock.hcl을 커밋하고 provider upgrade는 별도 PR로 처리한다.
• apply 권한은 제한된 CI 또는 운영 담당자에게만 둔다.