Community Core 운영

리소스 경보 규칙 통합 목록

리소스 알림 화면에서 규칙명 옆의 기본 제공·사용자 정의 표시로 규칙을 구분합니다. 검색·활성 상태 필터·규칙/심각도 열 제목 정렬·페이지 이동을 같은 목록에 적용합니다. 정렬 중인 열 제목을 다시 누르면 방향이 바뀝니다. 시스템 접근 규칙은 자동으로 감시하며 목록·검색·건수에서 제외합니다. 경보 발생·이력·알림 전송 설정은 유지됩니다. 메트릭 수집 규칙을 포함한 코어 규칙은 수정 불가입니다. 관리형 규칙은 조건 조정이 가능하고, 사용자 정의 규칙은 전체 편집·활성화·비활성화·삭제가 가능합니다. 알림 전달 경로와 워크플로우·경보 음소거는 규칙 정의의 수정 여부와 별도로 관리합니다.

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

주요 역할

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

운영 흐름

• 관리자 설정에서 리소스 플러그인, 메트릭 소스, 알림 채널을 먼저 확인합니다.
• 리소스를 등록할 때 플러그인별 스키마에 따라 접속 정보와 메트릭 연결을 설정합니다.
• 등록 후 연결 테스트와 리소스 상태 점검으로 기본 접근 경로를 검증합니다.
• 대시보드와 진단 화면에서 현재 상태, 과거 위험 신호, 메트릭 수집 범위를 함께 확인합니다.
• 일부 이벤트 패널은 지원되는 조회가 성공했지만 요청한 조회 범위에 이벤트 시계열이 없으면 체크와 “오류 없음”처럼 짧은 문구를 표시합니다. 시계열은 선택한 시간 축과 옅은 점선 안내선, 작은 “발생 이력 없음” 문구를 표시하며 비어 있어도 확대할 수 있습니다. 안내선은 측정값 0이 아닙니다. 쿼리 정보에서 조회 모드와 범위를 확인하세요. 순간값 조회는 선택 기간 전체의 부재나 리소스 정상을 확정하지 않습니다. 실제 0 샘플은 차트로 유지하며 메트릭 누락과 조회 실패는 알 수 없음·오류 상태를 유지합니다.
• 알림 규칙, 라우트, 워크플로우를 리소스별로 조정하고 전송 이력을 확인합니다.

리소스 메트릭 상세와 커스텀 임계값 알림

리소스 메트릭 설정에서 기존 메트릭 이름 접두사와 새 메트릭 이름 접두사를 지정합니다. 기존 접두사를 비우고 새 접두사에 prefix_를 입력하면 모든 이름 앞에 추가합니다. 기존 pg_, 새 prefix_이면 pg_up을 prefix_up으로 조회하고, 일치하지 않는 이름은 유지합니다. 새 접두사를 비우면 기존 접두사를 제거하며, 둘 다 비우면 원래 이름을 사용합니다. 대시보드·알림·쿼리 검사·진단에 동일하게 적용됩니다. 제거 후 이름이 비거나 유효하지 않으면 오류를 반환합니다. 리소스 라벨 필터는 계속 필요하며, 접두사 외 이름이나 단위 차이는 매핑 보정이 필요합니다.

리소스 메트릭 패널의 정보 버튼을 선택하면 메트릭 상세 및 설정이 열립니다. 이 화면에는 다음 네 개의 탭이 있습니다.

• 메트릭 정보에서 패널, 메트릭, 표시 단위를 확인합니다.
• 차트 필터에서 해당 패널에 표시할 반환 시계열을 조정합니다.
• 경보에서 기존 관련 규칙을 확인하고, 조건을 만족하는 패널의 커스텀 임계값 규칙을 만듭니다.
• 조회 상세에서 쿼리 블루프린트, 매핑 팩 해석, 실제 조회 근거를 확인합니다.

차트에서 임계값 규칙 만들기

경보 탭은 차트의 논리 메트릭에 실제 등록된 규칙을 먼저 보여줍니다. 플러그인 기본 규칙과 커스텀 규칙, 비활성 규칙을 포함하며 조회 성공 후 탭에 관련 규칙 수를 표시합니다. 조회 실패는 오류로 표시하며, 규칙이 없는 것으로 처리하지 않습니다.

새 규칙을 만들기 전에 기존 규칙의 조건, 심각도, 활성 여부, 메트릭 소스와 조회 범위를 확인하세요. 같은 논리 메트릭이어도 집계나 시계열 필터가 같다는 뜻은 아닙니다. 규칙이 활성 상태라는 사실만으로 평가나 알림 전달이 정상이라고 판단할 수 없습니다. 리소스 읽기 권한으로 목록을 확인할 수 있으며, 생성에는 리소스 관리 권한이 필요합니다.

새 규칙 추가를 누르면 커스텀 규칙 양식이 열립니다. 편집기는 메트릭 상세 및 설정 안에 있으며, 별도 모달을 열거나 차트에 별도 동작을 추가하지 않습니다. 저장된 규칙의 확인, 수정, 활성화, 비활성화, 삭제는 기존 리소스별 알림 화면의 통합 경보 규칙 목록에서 사용자 정의 표시를 선택한 목록에서 계속 수행합니다.

탭을 열기만 하면 초안이 열리지 않습니다. 임계값을 입력하고 저장해야 규칙이 만들어집니다. Konduo는 표시된 샘플이나 대시보드에서 선택한 시간 범위로 임계값을 추론하지 않습니다. 저장 후에는 관련 규칙을 다시 조회합니다. 규칙 목록으로 돌아갈 때 수정한 초안이 있으면 폐기 여부를 확인합니다. 기존 규칙 설정은 규칙 화면 링크로 열며, 새 규칙을 생성할 수 없는 차트에서도 관련 규칙을 확인할 수 있습니다.

초기 차트-알림 경로는 의미가 안전한 단일 논리 메트릭 시계열 프리셋만 허용합니다. 최상위 쿼리 블루프린트가 하나이거나 queries 안에 블루프린트가 정확히 하나여야 합니다. 초안은 블루프린트의 논리 메트릭 키, 연산, 집계, 쿼리 윈도우, 그룹 기준, 파라미터를 가져옵니다. 규칙은 선택한 리소스에 속하며 해당 리소스에 연결된 메트릭 소스 인스턴스를 조회합니다. 자체 메트릭 제공 리소스는 자신을 소스로 사용합니다. 감시 대상과 메트릭 소스의 ID가 달라도 실제 조회 범위는 감시 대상 리소스의 설정으로 결정됩니다.

리소스 문맥 또는 쿼리 블루프린트가 없거나, 여러 메트릭을 사용하거나, 동적 변수나 플레이스홀더를 포함하거나, 쿼리 단계 필터를 사용하거나, 임시 대시보드 작업·인스턴스 필터가 있거나, 사용자 정의 또는 지원되지 않는 인스턴스 선택자를 사용하면 알림 탭은 생성할 수 없는 이유를 표시합니다. stat, gauge, bar, pie 패널처럼 표시 단계에서 값을 축약한 경우와 top-N 같은 표시 변환을 선언한 경우도 지원하지 않습니다. 리소스 구성에 정의된 범위는 알림 평가가 관리되는 선택자를 독립적으로 다시 만들므로 허용됩니다.

표시 단계의 차트 필터는 정확한 조회 후 시계열 포함·제외 필터일 때만 새 규칙의 초기값으로 사용할 수 있습니다. 이 경우 메트릭 쿼리 뒤에 반환된 시계열을 알림에서 제한합니다. 차트 필터를 저장해도 기존 알림 규칙, 수집 메트릭, 원본 메트릭 쿼리는 바뀌지 않습니다.

평가 조건을 올바르게 설정하기

대시보드 시간 범위는 차트 이력을 보기 위한 범위입니다. 알림 평가 윈도우, 지속 시간, 임계값을 뜻하지 않습니다.

차트 블루프린트에 쿼리 윈도우가 있으면 초안에서 읽기 전용으로 유지합니다. 쿼리 윈도우가 없는 경우 **윈도우(초)**로 평가에 사용할 데이터 윈도우를 설정합니다. **지속 시간(초)**은 조건이 참인 상태가 유지되어야 규칙이 발생하는 시간입니다. 임계값은 차트가 표시용 축소를 적용하기 전의 기본 수치 샘플 값으로 입력합니다. 패널의 단위나 축 단위 메타 데이터는 표시를 제어하며 알림 값의 변환을 보장하지 않습니다. 차트 라벨을 위해 변환한 값을 입력하지 마세요. 예를 들어 차트가 바이트 단위를 축소해 표시해도 기본 바이트 값을 사용합니다.

이 커스텀 규칙 양식에는 편집 가능한 데이터 없음 정책이 없습니다. 성공한 쿼리가 한 시계열의 샘플을 반환하지 않으면 Konduo는 그 시계열에 새 알림을 만들지 않습니다. 이전에 대기 또는 발생 상태였던 시계열이 사라지면 상태는 비활성으로 바뀌며, 발생 중인 알림은 해결됩니다. 쿼리 또는 플러그인 오류는 텔레메트리를 사용할 수 없는 상태로 남으며 현재 알림 상태를 해결하지 않습니다.

커스텀 규칙은 기존 리소스 관리자 보호 리소스 알림 API와 리소스별 알림 화면의 Core 권한을 그대로 사용합니다. 전체 관리자 또는 권한을 위임받은 리소스 관리자는 해당 리소스 규칙을 관리할 수 있지만, 이 권한으로 전역 전송 커넥터, 템플릿, 알림 일시 중지를 관리할 수는 없습니다. 규칙을 만들어도 전송 라우트는 만들어지지 않습니다. 규칙을 저장한 뒤 기존 리소스별 알림 전송 설정에서 수신처, 라우트, 전송 동작을 구성하거나 확인하세요.

최초 관리자 준비

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

Docker Compose

Docker Compose를 실행한 서버에 접속하고, 설치할 때 사용한 compose.yml과 .env가 있는 디렉터리에서 Bash 터미널로 실행합니다. 브라우저나 컨테이너 내부 셸에 입력하는 명령이 아닙니다.

백엔드와 데이터베이스가 실행 중이어야 합니다. 다른 파일명이나 경로로 설치했다면 아래 모든 명령의 --env-file, -f 옵션을 설치 시 사용한 값으로 바꾸세요.

docker compose --env-file .env -f compose.yml exec -T backend \
  /app/konduo-backend admin-bootstrap-status

상태가 setup_required이면 다음 명령으로 최초 관리자를 생성합니다. 비밀번호는 입력 중 화면에 표시되지 않으며 표준 입력으로 전달됩니다.

read -rsp '초기 관리자 비밀번호: ' INITIAL_ADMIN_PASSWORD
echo
printf '%s\n' "$INITIAL_ADMIN_PASSWORD" |
  docker compose --env-file .env -f compose.yml exec -T backend \
    /app/konduo-backend admin-bootstrap --username admin --password-stdin
unset INITIAL_ADMIN_PASSWORD

• 위 예시의 사용자 이름은 admin입니다. 다른 이름을 사용하려면 --username 값을 바꿉니다.
• 비밀번호는 현재 인증 정책을 만족해야 합니다. INITIAL_ADMIN_PASSWORD는 위 명령에서만 사용하는 임시 셸 변수이며, .env에 추가한다고 계정이 생성되지는 않습니다.
• 생성 후 상태 조회 명령을 다시 실행해 complete인지 확인합니다.
• 이미 complete라면 기존 관리자 계정을 사용합니다. 생성 명령을 다시 실행해도 기존 비밀번호는 바뀌지 않습니다.

Kubernetes

백엔드와 같은 scratch 이미지, 데이터베이스/TLS 설정과 암호화 키를 사용하는 일회성 Job을 만듭니다. 셸이나 준비 컨테이너 없이 바이너리를 직접 실행합니다. Secret을 /run/konduo-bootstrap에 defaultMode: 0440으로 마운트하고 Pod의 UID/GID와 fsGroup을 10001로 설정하면 Kubernetes의 password -> ..data/password projection을 워크로드 그룹만 읽을 수 있습니다. activeDeadlineSeconds는 최소 600으로 설정하고 다음 인수로 실행합니다.

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

새 설치에서는 이 Job이 성공할 때까지 backend /readyz가 setup_required이므로 Ready를 기다리지 마세요. 명령은 동시 backend의 자동 스키마 migration과 seed 완료를 최대 5분 동안 기다리고, deadline 또는 ledger 무결성 오류에서는 실패합니다. Job 재시도는 안전합니다. 부트스트랩이 이미 완료됐다면 기존 비밀번호를 바꾸지 않고 성공으로 끝납니다. 상태가 complete인지 확인한 뒤 초기 비밀번호 Secret과 Job을 삭제합니다.

폐쇄망 Kubernetes 배포에서는 checksum을 확인한 offline bundle의 kubernetes/install.py와 포함된 chart를 사용하고, JSON 설정에 명시적인 kubeconfig와 context를 지정합니다. 설정에는 이미지 참조와 Secret 이름/key만 넣습니다. Secret 값은 플랫폼의 Secret 관리 체계로 만들고 Helm values, JSON, 셸 인수, 로그에 넣지 마세요. bundle은 CloudNativePG, CRD, Operator를 설치하지 않습니다. 이미지 archive는 모든 Kubernetes 노드 runtime에 import하거나 private registry에 mirror해야 합니다. 관리자 workstation의 Docker daemon에만 load하면 cluster에서 사용할 수 없습니다. 독립 CNPG DB에는 안정적인 -rw Service와 verify-full TLS CA 설정을 사용합니다.

release smoke는 kubeconfig, context, namespace를 모두 명시해서 실행합니다. smoke 대상은 installer 설정과 일치해야 하며 현재 kubectl context로 fallback하지 않습니다. 업그레이드 중 DB와 runtime Secret identity를 유지하세요. bundled, operator, external DB mode 변경은 검증된 데이터 복사 또는 복원이 필요한 별도 migration입니다.

로그인 및 복구 경계

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

read -rsp '임시 비밀번호: ' TEMPORARY_PASSWORD
echo
printf '%s\n' "$TEMPORARY_PASSWORD" | \
  docker compose --env-file .env -f compose.yml exec -T backend \
    /app/konduo-backend password-reset --user admin --password-stdin
unset TEMPORARY_PASSWORD

경계

• 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