Community Core 운영

Konduo Community Core는 플러그인 기반 리소스 등록, 권한 관리, 감사 기록, 알림 워크플로우, 메트릭 연결, 대시보드와 진단 화면을 제공하는 공통 운영 기반입니다. 개별 제품이나 시스템의 세부 동작은 플러그인이 담당하고, Core는 모든 플러그인이 같은 방식으로 등록되고 운영되도록 공통 경계를 제공합니다.

주요 역할

1. 리소스와 메트릭 소스, 알림 채널 플러그인을 등록하고 수명주기를 관리합니다.
2. 사용자, 역할, 리소스 권한, 감사 기록을 공통 모델로 처리합니다.
3. 리소스별 대시보드, 진단, 알림 규칙 화면을 호스트 렌더링 스키마로 렌더링합니다.
4. 플러그인 상태 점검, 알림 평가, 알림 전송 세션을 공통 워크플로우로 실행합니다.
5. 플러그인 매핑 팩을 통해 리소스의 논리 메트릭을 실제 메트릭 소스 쿼리로 연결합니다.

운영 흐름

• 관리자 설정에서 리소스 플러그인, 메트릭 소스, 알림 채널을 먼저 확인합니다.
• 리소스를 등록할 때 플러그인별 스키마에 따라 접속 정보와 메트릭 연결을 설정합니다.
• 등록 후 연결 테스트와 리소스 상태 점검으로 기본 접근 경로를 검증합니다.
• 대시보드와 진단 화면에서 현재 상태, 과거 위험 신호, 메트릭 수집 범위를 함께 확인합니다.
• 알림 규칙, 라우트, 워크플로우를 리소스별로 조정하고 전송 이력을 확인합니다.

최초 관리자 준비

Konduo는 운영 환경에 알려진 기본 관리자 비밀번호를 만들지 않습니다. 새 데이터베이스에 스키마와 기준 데이터를 적용한 뒤에도 활성 관리자가 없으면 /readyz와 admin-bootstrap-status가 setup_required를 보고합니다. 이 상태에서 운영자가 일회성 명령으로 최초 관리자를 만들어야 합니다.

로컬 개발 환경

저장소 루트에서 다음 순서로 실행합니다.

task db:postgres:up
task db:seed
printf '%s\n' "$INITIAL_ADMIN_PASSWORD" | task backend:admin:bootstrap
task run

기본 사용자 이름은 admin입니다. 다른 이름이 필요하면 ADMIN_USERNAME을 지정합니다.

printf '%s\n' "$INITIAL_ADMIN_PASSWORD" | \
  ADMIN_USERNAME=operator task backend:admin:bootstrap

현재 상태는 다음 명령으로 확인합니다.

task backend:admin:bootstrap:status

task clean은 빌드 결과, 검사 결과와 임시 파일만 삭제합니다. PostgreSQL 데이터, 기존 관리자와 부트스트랩 완료 상태는 삭제하지 않습니다. 완전히 새로운 로컬 데이터베이스가 필요할 때만 task db:reset을 실행한 뒤 위 절차를 처음부터 반복합니다.

task db:seed:demo는 알려진 비밀번호를 사용하는 데모 계정과 예제 데이터를 명시적으로 만들 때만 사용합니다. 운영 환경의 최초 관리자 준비를 대신하는 명령이 아닙니다.

Docker Compose

백엔드와 같은 이미지 및 환경 설정으로 일회성 명령을 실행합니다. 비밀번호는 명령행 인수가 아니라 표준 입력 또는 권한이 0600인 파일로 전달해야 합니다.

printf '%s\n' "$INITIAL_ADMIN_PASSWORD" | \
  docker compose --env-file docker/compose.release.env \
  -f docker/compose.yml run --rm -T backend \
  admin-bootstrap --username admin --password-stdin

Kubernetes

백엔드와 같은 이미지, 데이터베이스 설정과 암호화 키를 사용하는 일회성 Job을 만듭니다. 초기 비밀번호는 Secret에서 읽어 메모리 기반 emptyDir에 권한 0600으로 준비하고 다음 인수로 실행합니다.

admin-bootstrap --username admin --password-file /run/konduo-bootstrap/password

Job 재시도는 안전합니다. 부트스트랩이 이미 완료됐다면 기존 비밀번호를 바꾸지 않고 성공으로 끝납니다. 상태가 complete인지 확인한 뒤 초기 비밀번호 Secret과 Job을 삭제합니다.

로그인 및 복구 경계

• 최초 로그인에서는 즉시 비밀번호를 변경해야 합니다.
• 비밀번호는 현재 로컬 인증 정책을 만족해야 합니다.
• complete 상태에서 부트스트랩 명령을 다시 실행해도 기존 계정이나 비밀번호를 변경하지 않습니다.
• 부트스트랩 완료 후 활성 관리자가 사라지면 상태는 recovery_required입니다. 이때 부트스트랩 명령으로 새 관리자를 만들지 말고 승인된 비밀번호 재설정 또는 검증된 백업 복구 절차를 사용합니다.
• 비밀번호 재설정은 임시 비밀번호를 표준 입력으로 전달해 실행하며, 성공하면 기존 로그인 세션과 갱신 토큰이 폐기되고 다음 로그인에서 비밀번호 변경이 강제됩니다.

printf '%s\n' "$TEMPORARY_PASSWORD" | \
  task backend:reset-password RESET_USERNAME=admin

경계

• Core는 공통 수명주기, 권한, 감사, 알림 워크플로우, 화면 호스팅을 담당합니다.
• 플러그인은 도메인별 설정 스키마, 진단 근거, 논리 메트릭, 매핑팩, 관리 작업을 담당합니다.
• 민감한 인증 정보는 설정 저장과 실행 경계 안에서만 사용하고, 건강 점검 결과나 진단 메시지에 노출하지 않습니다.
• 플러그인 전용 화면을 Core에 직접 추가하지 않고, 플러그인이 제공하는 스키마와 contribution을 통해 확장합니다.

관련 문서

• docs/community-edition-boundary.md
• docs/plugin-extension-point-policy.md
• docs/frontend-plugin-ui-contract.md
• docs/plugin-diagnostics-contract.md
• docs/manual-source-contract.md
• backend/docs/administrator-bootstrap.md