신규 포탈 자동 프로비저닝 운영 가이드
상태: 설계 문서(미구현) — 자동 프로비저닝은 아직 구현되지 않았다. 이 문서는 특정 배포 플랫폼 API에 의존하지 않는 흐름만 기록한다(플랫폼 전용 API·URL·CLI 안내는 두지 않는다 —
UiPlatform/docs/PLATFORM_NAMING.md).
작성자: Manus AI
대상: DirectoryService 관리자 및 포탈 운영 담당자
1. 목적과 범위
DirectoryService의 신규 포탈 자동 생성은 공통 기능이 준비된 포탈 소스와 배포 준비를 하나의 관리 작업으로 생성합니다. 생성 결과에는 Portal Foundation 공통 UI·라이트/다크 테마, 사용자·조직 동기화, 중앙 전문용어 사전 실시간 조회, 최소 권한 scope, 상위키 기반 암호화 컨텍스트가 포함됩니다.
소스 저장소는 현재 비공개 GitHub 템플릿 저장소로 생성합니다. 배포 대상은 공급자 드라이버로 분리되어 있으며, 현재 배포 플랫폼와 온프레미스를 선택할 수 있습니다. 새로운 클라우드·사내 배포 서비스는 동일한 드라이버 계약으로 추가합니다.
| 구분 | 배포 플랫폼 | 온프레미스 |
|---|---|---|
| 저장소 | 비공개 GitHub 템플릿에서 생성 | 비공개 GitHub 템플릿에서 생성 후 내부 Git/CI가 미러링 가능 |
| 서비스 준비 | DirectoryService가 Free 인스턴스 서비스·환경변수·재배포를 자동 처리 | DirectoryService가 포탈 원장·비밀값·배포 안내를 준비하고 내부 CI/에이전트가 배포 |
| 기본 URL | 배포 플랫폼가 반환한 공개 URL | 관리자가 입력한 내부 또는 공개 HTTPS URL |
| API Key 전달 | 배포 플랫폼 환경변수로 자동 주입 | 생성 결과에서 한 번만 표시하고 내부 Secret Manager 또는 수신 에이전트에 수동 주입 |
| 상태 확정 | DEPLOYING 후 health 확인 | CONFIGURED 후 고객사 내부 배포와 health 등록 필요 |
2. 자동 적용되는 공통 기반
신규 포탈은 초기 생성 단계에서 다음의 최소 권한만 가진 관리형 API Key를 발급받습니다.
| Scope | 용도 |
|---|---|
directory:read | 사용자·조직 원장 조회 |
directory:sync | 포탈의 동기화 상태 제출 |
directory:crypto | 포탈 로컬 민감정보의 context-bound Envelope Encryption |
glossary:read | 중앙 전문용어 사전 실시간 조회 |
환경변수 이름은 공통 계약으로 고정합니다. DIRECTORY_PORTAL_API_KEY의 원문은 생성 결과에 한 번만 나타나며, 운영 이력·감사 로그·DB 조회 화면에 다시 나타나지 않습니다.
| 환경변수 | 역할 |
|---|---|
DIRECTORY_SERVICE_URL | DirectoryService 공개 HTTPS 주소 |
DIRECTORY_PORTAL_ID | 포탈 식별자 |
DIRECTORY_PORTAL_API_KEY | 중앙 연동용 관리형 API Key |
DIRECTORY_SYNC_ENABLED / DIRECTORY_SYNC_CRON | 사용자·조직 동기화 활성화 및 주기 |
DIRECTORY_GLOSSARY_ENABLED / DIRECTORY_GLOSSARY_MODE | 전문용어 사전 실시간 조회 설정 |
PORTAL_THEME_STORAGE_KEY | 라이트·다크 테마의 포탈별 저장 키 |
3. DirectoryService 서버 사전 설정
자동 생성 버튼을 활성화하려면 DirectoryService 운영 환경에 다음 전역 설정을 등록합니다. 서버 Secret은 클라이언트·감사 로그·프로비저닝 이력에 노출해서는 안 됩니다. 반면 신규 저장소 소유자와 배포 플랫폼 Workspace·리전은 비밀값이 아니며, 작업별로 관리자 화면에서 입력합니다.
| 환경변수 | 분류 | 필수 대상 | 설명 | |---|---|---| | PORTAL_PROVISIONING_GITHUB_TOKEN | 서버 Secret | 모든 방식 | 비공개 저장소 생성 권한을 가진 GitHub 토큰 | | PORTAL_PROVISIONING_TEMPLATE_REPOSITORY | 서버 전역 설정 | 모든 방식 | owner/repository 형식의 포탈 템플릿 저장소 | | DIRECTORY_SERVICE_PUBLIC_URL | 서버 전역 설정 | 모든 방식 | 포탈이 호출할 DirectoryService 공개 HTTPS 주소 | | (미구현) 배포 플랫폼 API 키 | 서버 Secret | 자동 생성 시에만 | 배포 플랫폼 서비스·환경변수·배포 API 접근 — 수동 프로비저닝에는 필요 없다 |
GitHub의 템플릿 저장소 생성 API는 저장소의 소유자, 이름, 설명, 비공개 여부를 받아 새 저장소를 생성합니다.1
자동 생성은 배포 플랫폼의 무료 등급을 전제로 설계됐다 — 유료 옵션·디스크·애드온은 포함하지 않는다. 무료 등급은 유휴 시 중지될 수 있고 로컬 파일 변경은 재배포·재시작 뒤 유지되지 않으므로 운영 데이터는 외부 영속 저장소에 둔다.
4. 온프레미스 보안 경계
온프레미스 선택은 DirectoryService가 고객사 내부망에 직접 접속하지 않는 모델입니다. 따라서 내부 Kubernetes API, VM SSH, 내부 Git, Secret Manager의 장기 인증정보를 DirectoryService에 등록하거나 저장하지 않습니다.
원칙: DirectoryService는 포탈 원장·공통 기능 계약·일회성 API Key를 생성한다. 고객사 내부 배포 에이전트 또는 CI는 내부망에서 소스·이미지·비밀값을 수신해 실제 배포를 수행한다.
온프레미스 운영 담당자는 생성 결과에서 API Key를 한 번만 복사해 내부 Secret Manager에 저장해야 합니다. 이후 환경변수 묶음을 배포 런타임에 주입하고, 포탈의 /health 또는 조직이 정한 health endpoint를 확인합니다. API Key를 평문 파일·메신저·소스 저장소·이미지 레이어에 저장해서는 안 됩니다.
향후 내부 자동 배포가 필요하면 고객사 내부 네트워크에 수신 에이전트를 설치하고, DirectoryService가 서명된 단기 작업 요청만 보낼 수 있게 별도 드라이버를 추가합니다. 에이전트의 장기 키는 내부 Secret Manager에만 남기고, DirectoryService에는 공개 키·에이전트 식별자·작업 이력만 저장합니다.
5. 실패 복구와 재시도
프로비저닝은 단계별 상태를 저장합니다. 유효성 검사를 통과한 요청은 먼저 PENDING 이력을 기록하고, 그 뒤 서버 전역 설정과 외부 연결을 검사합니다. 따라서 설정 누락도 생성 이력의 FAILED 상태와 오류 요약으로 확인할 수 있습니다. 화면은 요청 직후 임시 REQUESTING 표시를 보이고, 실행 중에는 3초 간격으로 이력을 자동 조회하므로 수동 새로고침이 필요하지 않습니다.
| 상태 | 의미 | 운영 조치 |
|---|---|---|
REQUESTING | 브라우저가 요청을 전송 중인 임시 표시 | 화면이 자동으로 서버 이력을 조회한다. DB 상태값은 아니다. |
PENDING | 생성 요청 기록 | 서버 전역 설정·GitHub 템플릿 연결 검사를 기다린다. |
REPOSITORY_READY | GitHub 저장소 생성 완료 | 배포 공급자 생성 결과 확인 |
SERVICE_READY | 선택한 배포 대상 준비 완료 | 공통 환경변수와 중앙 Key 설정 확인 |
CONFIGURED | 공통 연동 준비 완료 | 온프레미스라면 내부 Secret·배포 적용 필요 |
DEPLOYING | 배포 플랫폼 배포 요청 완료 | 배포 플랫폼 서비스의 Events·Logs와 health endpoint를 확인한다. |
RECOVERY_REQUIRED | 외부 리소스 일부 생성 뒤 실패 | 생성 이력의 복구 안내 확인 후 같은 입력으로 재시도 |
FAILED | 외부 리소스 생성 전 실패 | 서버 비밀값·권한·입력값 수정 후 재시도 |
6. 확장 드라이버 구현 규칙
새 공급자를 추가할 때는 PortalDeploymentDriver 계약을 구현합니다. 드라이버는 provision, configureEnvironment, triggerDeploy를 제공해야 하며, 서비스 식별자·HTTPS URL·배포 시작 여부·수동 비밀값 전달 여부·운영 안내를 반환합니다.
클라우드 드라이버는 서버 비밀값으로만 공급자 API를 호출하고, 포탈 API Key를 환경변수 또는 공급자 Secret Store에 주입할 수 있습니다. 내부망 드라이버는 고객사 내부 에이전트가 없는 한 manualSecretDelivery: true를 유지해야 합니다. 공통 오케스트레이터는 배포 공급자 구현에 관계없이 포탈 원장, UI 구독, 관리형 API Key, 감사 이벤트를 동일하게 생성합니다.