조직 생애주기

조직 생성부터 AWS 연동, 제거까지 — 고객사 하나가 Voltra에 들어오고 나가는 전 과정.

언제 쓰나

새 고객사를 들일 때 조직을 만든다. 조직을 만들면 Org Admin 계정과 초기 크레딧이 함께 생긴다. 조직은 항상 AWS 계정과 묶이므로, 생성 직후 또는 나중에 AWS 연동 방식을 설정한다. 계약이 끝나 고객사를 내보낼 때는 조직을 제거한다. 제거는 하드 삭제가 아니라 정산 종료 + 기록 보존이다.

화면

조직 관리는 조직별 크레딧 판매 누적·미할당 잔여·팀 수·AWS 모드를 한눈에 보여준다.

조직 관리

요소	위치	의미
조직 검색...	우측 상단	조직 이름으로 필터
판매 정책 · ₩500/C	우측 상단	크레딧 판매 단가·VAT 정책 (자세히는 크레딧 판매)
+ 조직 생성	우측 상단	생성 모달 열기
조직 (이름·슬러그)	행	굵은 글씨가 이름, 아래 회색이 슬러그
플랜	행	growth 또는 enterprise
크레딧 판매 누적	행	이 조직에 판매한 크레딧 총합
미할당 잔여	행	조직 계정에서 아직 팀에 배분되지 않은 크레딧
팀	행	조직에 속한 팀 수
AWS	행	플랫폼 계정 또는 BYOC
팀 노드	행 우측	조직의 팀별 허용 노드 타입 관리
크레딧 판매	행 우측	크레딧 판매 모달
제거	행 우측(빨강)	조직 제거

+ 조직 생성 을 누르면 입력 모달이 뜬다. 부제는 조직은 항상 AWS 계정과 묶입니다다.

조직 생성

입력	규칙	설명
조직 이름	1~120자, 전역 유일	이미 있는 이름이면 거부
슬러그	2~60자, 소문자·숫자·하이픈(^[a-z0-9-]+$), 전역 유일	URL·식별용
플랜	Growth / Enterprise	드롭다운
조직 어드민 계정	이메일, 전역 유일	이 계정이 Org Admin이 된다
어드민 초기 비밀번호	최소 8자	첫 로그인용
AWS Credentials *필수	플랫폼 계정 사용 / BYOC · 조직 소유 계정	토글
초기 크레딧 (판매)	0 이상	생성과 동시에 판매 처리된다. 0으로 두고 나중에 팔아도 된다
금액 (₩, VAT 별도)	0 이상	판매 정산 이력에 남는 금액

절차

조직 생성

1. + 조직 생성 을 누른다.
2. 이름·슬러그·플랜을 넣는다. 이름과 슬러그가 이미 쓰였으면 반영 단계에서 duplicate로 거부된다.
3. Org Admin 이메일과 초기 비밀번호를 넣는다. 이메일이 이미 다른 조직(또는 제거된 조직)의 어드민에 쓰였으면 duplicate_admin_email로 거부되고 조직은 생성되지 않는다.
4. AWS Credentials를 고른다. 플랫폼 계정 사용은 Voltra 플랫폼 계정에서 인스턴스를 돌리는 방식이고, BYOC · 조직 소유 계정은 고객 자기 계정에서 돌리는 방식이다.
5. 초기 크레딧과 금액을 넣는다(선택). 넣으면 생성과 동시에 판매로 잡힌다.
6. 조직 생성 을 누른다. 조직·Org Admin 계정·원장 계정이 만들어지고, 크로스 계정용 ExternalId가 자동 발급된다(voltra- + 16자리 hex).

AWS 연동 (BYOC)

BYOC는 순서가 중요하다. ExternalId가 먼저 발급되어야 고객이 그 값으로 IAM 역할을 만들 수 있다(D-022). 그래서 생성 시 ARN은 필수가 아니고 사후 등록한다.

1. 조직을 플랫폼 계정 사용 또는 BYOC로 먼저 만든다. 생성 응답에 aws_external_id가 담겨 나온다.
2. 고객이 그 ExternalId로 크로스 계정 역할(voltra-access)을 만들고 ARN을 알려준다.
3. AWS 연동 설정에서 aws_mode를 byoc로, 역할 ARN을 등록한다. ARN이 arn:aws:iam:: 로 시작하지 않으면 invalid_arn으로 거부된다.
4. 리전(aws_region, 기본 ap-northeast-2)을 조직에 맞게 설정한다.

역할 셋업 절차·정책 JSON·CloudFormation 템플릿은 별도 문서(BYOC-SETUP.md)에 있다.

조직 제거

1. 조직 행의 제거(빨강)를 누른다.
2. 확인을 위해 조직 이름을 정확히 입력한다. 이름이 일치하지 않으면 confirm_mismatch로 거부된다.
3. 제거를 실행한다. 진행 중 자원이 있으면 먼저 막힌다(아래 표 참고).
4. 차단이 없으면 정산이 돈다: 팀 잔여 크레딧을 조직으로 회수(원장 reclaim) → 조직 잔액을 정산 종료(원장 adjust) → LLM 키 전부 폐기 → 노드 등록 해제 → 팀·조직 soft delete + 어드민·멤버 계정 비활성화.

이렇게 되면 정상

• 생성: 목록에 새 조직이 나타나고 미할당 잔여가 초기 크레딧과 같다. 초기 크레딧을 넣었으면 원장에 purchase 엔트리와 credit_sales 행이 생긴다. 감사 로그에 org.create가 남는다.
• AWS 연동: 감사 로그에 org.aws_update가 before/after와 함께 남는다.
• 제거: 목록에서 사라진다. 응답에 정산 종료액(retired_c)과 등록 해제된 노드 수(nodes_unregistered)가 담긴다. 감사 로그에 org.delete가 남고, 사용 이력·원장·감사 기록은 보존된다. 실제 EC2 인스턴스는 조직 AWS 계정에 그대로 남는다 — 인프라 제거는 수동이다.

막히는 경우

증상	원인	조치
생성 시 duplicate	조직 이름 또는 슬러그가 이미 존재	다른 이름/슬러그 사용
생성 시 duplicate_admin_email	어드민 이메일이 이미 다른 조직(또는 제거된 조직)에 등록됨	다른 이메일 사용. 제거된 조직의 어드민 행도 이메일을 계속 점유한다
연동 시 invalid_arn	역할 ARN이 arn:aws:iam::<계정ID>:role/… 형식이 아님	형식 확인 후 재입력
제거 시 confirm_mismatch	입력한 이름이 조직 이름과 불일치	조직 이름을 정확히 입력
제거 시 reservations_open	진행 중 예약(submitted·adjusted·approved·active)이 있음	승인 처리 또는 취소 후 재시도
제거 시 sessions_open	실행 중 세션이 있음	세션 중지 후 재시도
제거 시 active_holds	팀에 활성 선점(hold)이 남아 있음	실행 세션을 정리한 뒤 재시도

알아둘 것

• 조직은 항상 AWS 계정과 묶인다(D-019). GPU는 각 조직의 AWS 계정 안에서 돈다. 플랫폼 공용 풀은 없다.
• Org Admin 이메일은 전역 유일이다(uq_admin_email). 미리 걸러 주지 않으면 반영 단계에서 유니크 위반으로 전체가 롤백되므로, 생성 전에 중복을 검사해 무엇이 문제인지 화면에 드러낸다.
• 제거는 soft delete다(D-021). 사용 이력·원장·감사 기록은 지우지 않는다. 원장은 append-only라 지난 차감이 영원히 남는데, 귀속할 이름이 사라지면 고객 사용량 리포트에 정체불명의 금액이 생기기 때문이다.
• 제거 시 잔여 크레딧은 자동 환불되지 않는다 — 조직 잔액을 원장 adjust로 정산 종료 처리하고 그 사유를 감사 로그에 남긴다. 환불이 필요하면 별도 회계 처리다.
• 실 검증(dry-run AssumeRole)은 AWS 연동 승인 후에 활성화된다(D-009). 그 전까지 인스턴스 시작/중지는 기본값인 시뮬레이션(fake)으로 동작한다.