Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 0 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,19 +52,6 @@ Kafka, Debezium, Kafka Connect, Kubernetes를 직접 다루지 않고도 데이
| AI Agent | 자연어 질의, incident RCA workflow, 35종 root cause catalog, evidence matrix, verifier loop, HITL approval·action |
| Governance | `/internal/ops` 경계, mutation allowlist, `PolicyGuard`, approval·change ticket·idempotency·audit |

## 화면

<table>
<tr>
<td width="50%"><img src="docs/test/assets/live-02-rca.png" alt="evidence 기반 RCA" /></td>
<td width="50%"><img src="docs/test/assets/live-03-actions.png" alt="승인 기반 조치 후보" /></td>
</tr>
<tr>
<td><sub><b>evidence 기반 RCA</b> — confidence와 근거가 부족하면 <code>UNKNOWN_WITH_EVIDENCE_GAP</code>으로 보류하고 추가 evidence를 요구</sub></td>
<td><sub><b>조치 후보</b> — 위험도(낮음·중간)와 승인 상태, 근거 리포트를 함께 제시하고 실행은 <code>/internal/ops</code> 경계를 통과</sub></td>
</tr>
</table>

## 아키텍처

```mermaid
Expand Down
97 changes: 31 additions & 66 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,74 +1,39 @@
# Bifrost 문서

엔터프라이즈 내부(폐쇄망·온프레미스) 환경에서 **데이터 파이프라인을 구축·운영·장애대응**하는 플랫폼. Kafka·Kafka Connect 같은 복잡한 내부를 직접 다루지 않고도 데이터 흐름을 만들고(파이프라인 생성), 상태를 보고(모니터링), 문제를 빠르게 대응(AI 운영 보조)할 수 있게 한다.
Bifrost는 데이터베이스 등록부터 CDC/EDA 파이프라인 생성, 운영 모니터링, evidence 기반 AI 장애 대응까지 다루는 DataOps/AIOps 플랫폼이다.

> AI 장애 대응 원칙: **LLM은 RCA Engine이 아니라 RCA Assistant다.** 원인을 자유 생성하지 않고, 허용된 원인 후보 중 evidence와 가장 잘 맞는 것을 선택·설명한다.
> 최종 SOT(Source of Truth)는 코드 구현 내용이다. 문서는 현재 구현을 읽기 쉽게 설명하는 보조 레이어이며, 코드와 문서가 다르면 코드를 기준으로 문서를 고친다.

## 문서 인덱스

| 분류 | 문서 | 내용 |
| --- | --- | --- |
| 요구사항(SoT) | [spec.md](./spec.md) | 기능명세서 — FR 카탈로그 + 부록 B(상태값·임계값·이벤트→인시던트 규칙)의 **단일 출처** |
| 시나리오 | [scenario.md](./scenario.md) | 시연 Critical Path, 통합 시나리오, 완료 정의(DoD) |
| 설계 | [design/infra.md](./design/infra.md) | 인프라(단일 EKS·Strimzi·Harbor·CI/CD·Observability) |
| 설계 | [design/frontend.md](./design/frontend.md) | 프론트엔드 화면(FR)별 백엔드 연동 |
| 설계 | [design/backend-springboot/](./design/backend-springboot/overview.md) | Spring Boot Operations Backend(플랫폼 본체·운영 집행) |
| 설계 | [design/backend-fastapi/](./design/backend-fastapi/overview.md) | FastAPI Agent Server(AI 장애대응 workflow) |
| API | [api/springboot.md](./api/springboot.md) | 플랫폼 `/api/v1` + 내부 전용 운영 `/internal/ops` |
| API | [api/fastapi.md](./api/fastapi.md) | Agent `/api/v1/agent…` |
| 결정 | [adr/](./adr/) | 아키텍처 결정 기록(ADR) |
| 팀 | [team/git-convention.md](./team/git-convention.md) | git 컨벤션 |

## 전체 구조

```text
Frontend (운영 콘솔)
├─ 플랫폼·모니터링 ───► Spring Boot Operations Backend (/api/v1)
└─ AI 장애대응 ───────► FastAPI Agent Server (/api/v1/agent)
└─► Spring Boot (/internal/ops, internal only)
Spring Boot Operations Backend
-> Fabric8 / Strimzi / Kafka AdminClient / Kafka Connect REST
-> Prometheus / Loki / Tempo
-> source/sink DB (JDBC) / 메타데이터 DB
```

- **Spring Boot Operations Backend**가 플랫폼 본체다. 워크스페이스·DB·파이프라인 CRUD, Kafka 프로비저닝(Fabric8/Strimzi), DB 등록·CDC 점검, 모니터링, 메타데이터, 그리고 에이전트 조치의 정책·승인·감사·실행을 담당한다.
- **FastAPI Agent Server**는 AI 장애 대응만 맡는다. Supervisor가 8개 LLM agent와 결정론적 단계로 구성된 workflow를 제어하며, 운영 조회·조치는 내부 서비스 경로로 Spring Boot `/internal/ops/**`에 위임한다. public frontend ingress는 `/internal/ops/**`를 프록시하지 않고, 브라우저/외부 클라이언트는 `/api/**` 계열만 호출한다. (MCP는 v1 미사용)

## 식별자

- **`workspace_id`(=`project_id`, uuid)**: scope·소유권 검증용 내부 키. 프론트/플랫폼은 `workspace_id`, 에이전트/내부 운영 API는 같은 테넌트를 `project_id`로 부른다(v1에서 동일).
- **`projectKey`(슬러그)**: 워크스페이스 이름에서 자동 생성하는 영소문자·숫자·하이픈 문자열. Kafka 토픽·ACL·KafkaUser 등 DNS-safe 리소스 이름의 기준.
- 코드/DB는 `tenant`/`datasource` 용어를 쓰되 설계 용어(`workspace`/`database`)와 공존한다([ADR 0002](./adr/0002-multi-tenancy-model.md), [ADR 0004](./adr/0004-monorepo-monolith.md)).
## 읽는 순서

## 소유권 · SoT 맵
1. [spec.md](./spec.md) — 기능 요구사항, 상태값·임계값 요구사항
2. [scenario.md](./scenario.md) — 시연 critical path와 완료 기준
3. [api/springboot.md](./api/springboot.md), [api/fastapi.md](./api/fastapi.md) — 사람이 읽는 API 카탈로그
4. [design/backend-springboot/overview.md](./design/backend-springboot/overview.md), [design/backend-fastapi/overview.md](./design/backend-fastapi/overview.md), [design/frontend.md](./design/frontend.md), [design/infra.md](./design/infra.md) — 구현 설명
5. [adr/](./adr/) — 방향 전환이 있었던 결정 기록

> 같은 정보를 여러 곳에서 정의하지 않도록, 각 항목의 **정본(Source of Truth)** 을 한 곳으로 고정한다. 나머지 문서/서비스는 인용·미러링만 한다.
## 코드 기준

| 항목 | 소유(SoT) | 정본 위치 |
| 항목 | 코드 기준 | 문서 |
| --- | --- | --- |
| 기능 요구사항(FR) | 기능명세 | [spec.md](./spec.md) |
| 상태값·임계값·이벤트→인시던트 규칙 | 기능명세 부록 B | [spec.md 부록 B](./spec.md#부록-b--리소스-상태값-정의-및-자동-기준-단일-출처) |
| 식별자(`workspace_id`=`project_id`·`projectKey`) | 공통 규약 | [위 식별자](#식별자) |
| 플랫폼 메타데이터(workspace·DB·pipeline·connector·event·incident·audit) | **Spring**(`metadb`) | [data-model.md](./design/backend-springboot/data-model.md#4-data-model) |
| 운영 operation·집행 allowlist(무엇을 실행하나) | **Spring** | [server.md §7.1](./design/backend-springboot/server.md#71-operation-allowlist-집행-경계-단일-출처) |
| approval·change·idempotency 검증·audit 원본 | **Spring** | [server.md §8](./design/backend-springboot/server.md#8-approval과-change-management) |
| Evidence 원문(운영 raw) | **Spring**(Evidence Store) | [data-model.md §3.9](./design/backend-springboot/data-model.md#39-evidence_ref) |
| DB 연결테스트 오류 5종 분류 | **Spring** | [database-registry.md §2](./design/backend-springboot/database-registry.md#2-step-1--연결-테스트-동적-datasource) |
| 모니터링 수집(상태=watch / 지표=폴링·질의) | **Spring** | [server.md §11.1](./design/backend-springboot/server.md#111-관측모니터링-데이터-수집-상태-vs-지표) |
| RCA 판단 카탈로그(장애유형·root cause·evidence matrix·correlation·runbook·policy) | **FastAPI** | [catalog-* §6~§12](./design/backend-fastapi/catalog/catalog-failure-types.md#6-catalog-failure-types) |
| Agent run 상태(run·state·event·approval facade·report) | **FastAPI**(`agentdb`) | [contract-state-schema §14](./design/backend-fastapi/contract/contract-state-schema.md#14-contract-state-schema) |
| Knowledge 코퍼스(RAG runbook·문서) | **FastAPI**(Vector Store) | [server-design §9](./design/backend-fastapi/server-design.md#2-server-design) |
| Tool 매핑(논리 tool→operation) | **FastAPI** Tool Client Registry | [tool-catalog.md §8·§9](./design/backend-fastapi/tool-catalog.md#4-tool-catalog) |
| CI 파이프라인·이미지 빌드 | **Jenkinsfile** + Jenkins JCasC | [infra/cicd README](../infra/cicd/README.md#ci-파이프라인-job-bifrost-ci) |
| GitOps 배포 구조 | **gitops 브랜치** `argocd/`, `charts/`, `databases/`, `infra/`, `secrets/` | [infra.md §7](./design/infra.md#7-cicd) |
| API 에러코드 | 표면별(각자 소유) | [Spring](./api/springboot.md) · [FastAPI](./api/fastapi.md) |
| 인프라 현황(클러스터·용량) | 인프라 | [infra.md §2](./design/infra.md#2-리소스-계획현황-resource-plan) |

> 방향 주의: **실행(tool/operation·allowlist)은 Spring이 정본**(FastAPI는 미러), **판단(RCA 카탈로그)은 FastAPI가 정본**(Spring은 모름), **임계값·상태 규칙은 spec 부록 B가 정본**(양쪽이 인용).

## 읽는 순서

1. 이 문서(README) → 2. [spec.md](./spec.md)(FR·임계값) → 3. [scenario.md](./scenario.md) → 4. 설계 [design/](./design/) → 5. API [api/](./api/)

상태값(`pipeline.status`·`connector.state` 등)·임계값(consumer lag 5,000/50,000, error rate 0.5%/2% 등)·이벤트→인시던트 규칙의 **단일 출처는 [spec.md 부록 B](./spec.md#부록-b--리소스-상태값-정의-및-자동-기준-단일-출처)**다. 다른 문서는 중복 정의하지 않고 이를 인용한다.
| Spring 플랫폼 API | `services/operations-backend/src/main/java/com/bifrost/ops/**/controller`, DTO | [api/springboot.md](./api/springboot.md) |
| Spring 내부 운영 API | `internalops/controller`, `governance/MutationGate`, `governance/policy/PolicyGuard` | [backend-springboot/governance.md](./design/backend-springboot/governance.md) |
| metadb schema | `services/operations-backend/src/main/resources/db/migration` | [backend-springboot/data-model.md](./design/backend-springboot/data-model.md) |
| Pipeline 생성·상태·삭제 | `PipelineController`, `PipelineService`, `PipelineStatusServiceImpl`, `StrimziKafkaPipelineProvisioner` | [pipeline.md](./design/backend-springboot/pipeline.md), [lifecycle.md](./design/backend-springboot/lifecycle.md), [provisioning.md](./design/backend-springboot/provisioning.md) |
| Monitoring·Incident | `MonitoringController`, `MonitoringReadService`, `InternalOpsObservabilityController`, `IncidentService` | [monitoring.md](./design/backend-springboot/monitoring.md) |
| FastAPI route·workflow | `services/ai-service/app/api`, `app/workflow`, `app/supervisor`, `app/schemas` | [api/fastapi.md](./api/fastapi.md), [backend-fastapi/server-design.md](./design/backend-fastapi/server-design.md) |
| Agent catalog·tool registry | `services/ai-service/app/catalogs`, `app/tools/registry.py`, `services/ai-service/corpus` | [backend-fastapi/catalog/](./design/backend-fastapi/catalog/), [tool-catalog.md](./design/backend-fastapi/tool-catalog.md) |
| Infra·배포 | `infra/`, `Jenkinsfile`, `docker-compose.yml`, `services/*/helm` | [design/infra.md](./design/infra.md) |

## 책임 경계

- **Spring Boot Operations Backend**: 플랫폼 본체. 인증, workspace, DB registry, pipeline lifecycle, provisioning, monitoring, governance, `/internal/ops` 집행 경계를 담당한다.
- **FastAPI Agent Server**: AI 장애 대응 계층. RCA와 조치 후보 생성을 담당하고, 운영 조회·실행은 Spring `/internal/ops`로 위임한다.
- **Frontend**: 운영 콘솔. Spring `/api/v1`과 FastAPI `/api/v1/agent`를 호출한다. 브라우저가 `/internal/ops/**`를 직접 호출하지 않는다.
- **Infra**: Kafka/Strimzi, Connect image, EKS/GitOps/CI/CD/observability 배포 구조를 관리한다.

## 작성 규칙

- 현재 구현, 계획, 과거 검증 기록을 같은 문단에 섞지 않는다.
- API schema 전체를 문서에 복붙하지 않는다. controller/DTO/OpenAPI를 기준으로 하고, 문서에는 권한·상태코드·주의점만 남긴다.
- 상태값·임계값 요구사항은 [spec.md 부록 B](./spec.md#부록-b--리소스-상태값-정의-및-자동-기준-단일-출처)에 모아 두되, 실제 동작 여부는 코드로 확인한다.
6 changes: 3 additions & 3 deletions docs/adr/0004-monorepo-monolith.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

## Context

[ADR 0001](./0001-polyrepo.md)은 7개 폴리레포 + 서비스별 MSA(core / orchestrator / ai 분리)를 결정했다. 그러나 실제 작업은 단일 레포(`bifrost`) 안에서 진행되었고, 설계 문서([design/overview.md](../README.md) §2, [springboot/DETAILS.md](../design/backend-springboot/server.md#5-패키지-구조) §5)는 백엔드를 **두 개의 백엔드**로만 정의한다.
[ADR 0001](./0001-polyrepo.md)은 7개 폴리레포 + 서비스별 MSA(core / orchestrator / ai 분리)를 결정했다. 그러나 실제 작업은 단일 레포(`bifrost`) 안에서 진행되었고, 현재 설계 개요([docs README](../README.md), [Spring Boot overview](../design/backend-springboot/overview.md))는 백엔드를 **두 개의 백엔드**로만 정의한다.

```
Frontend ─┬─► Spring Boot Operations Backend (플랫폼 본체, 단일 모놀리스)
Expand All @@ -21,7 +21,7 @@ Frontend ─┬─► Spring Boot Operations Backend (플랫폼 본체, 단일
2. **Spring Boot는 단일 모놀리스** `services/operations-backend`로 통합한다. 현재 Gradle 모듈은 `services:operations-backend`와 Kafka Connect 이미지에 동봉되는 `connect-plugins:timestamptz-converter`만 포함한다.
- `core-service` + `orchestrator-service` → `services/operations-backend` 병합.
- base 패키지 `com.platform.*` → **`com.bifrost.ops`** 통일.
- 패키지 구조는 설계 [springboot/DETAILS.md §5](../design/backend-springboot/server.md#5-패키지-구조)를 따른다.
- 패키지 구조는 `services/operations-backend/src/main/java/com/bifrost/ops`의 package-by-feature 구조를 따른다.
3. **Agent는 FastAPI(Python)** 로 별도 서비스 유지(`services/ai-service`). Spring Boot의 `/internal/ops`만 호출하며 K8s/Kafka에 직접 접근하지 않는다.
4. **`libs/common-dto` 흡수** — 모놀리스 내부 패키지로 옮기고 Gradle 모듈 제거. Spring ↔ FastAPI 계약은 공유 lib 대신 `/internal/ops` HTTP(JSON)/OpenAPI로 관리(언어가 갈리므로 공유 jar 불가).

Expand All @@ -42,4 +42,4 @@ Frontend ─┬─► Spring Boot Operations Backend (플랫폼 본체, 단일

## References
- 설계: [design/overview.md](../README.md) §2, §5
- 설계: [design/backend/springboot/DETAILS.md](../design/backend-springboot/server.md#5-패키지-구조) §1, §5
- 설계: [design/backend-springboot/overview.md](../design/backend-springboot/overview.md)
2 changes: 1 addition & 1 deletion docs/api/springboot.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,7 @@ OWNER 정책의 현재 코드 사실:
- principal은 workspace에 속해야 하며 없으면 `KAFKA_PRINCIPAL_NOT_FOUND` 404다(`services/operations-backend/src/main/java/com/bifrost/ops/workspace/kafka/KafkaPrincipalService.java:184-187`).
- revoked/inactive principal은 Secret 조회를 거부한다. 현재 정책은 `ACTIVE`만 허용하고 그 외는 `WORKSPACE_FORBIDDEN`이다(`services/operations-backend/src/main/java/com/bifrost/ops/workspace/kafka/KafkaPrincipalService.java:133-136`, `services/operations-backend/src/main/java/com/bifrost/ops/workspace/kafka/KafkaPrincipalService.java:228-231`).
- Secret 이름은 `TenantProvisioner`/`ConnectorNaming.kafkaUserName(workspace.namespace)` 규칙과 principal username이 일치해야 하며, 불일치 또는 Secret/key 없음은 404로 처리한다(`services/operations-backend/src/main/java/com/bifrost/ops/workspace/kafka/KafkaPrincipalService.java:137-164`).
- **플랫폼 정책(server.md: secret 원문 read deny)에 따라 raw password는 절대 반환하지 않는다.** 응답(`KafkaPrincipalSecretResponse`) 필드는 `principalId`, `username`, `status`, `namespace`, `secretName`, `availableKeys`(존재 key 목록), `passwordMasked="********"`, `retrievedAt`, `exposurePolicy="MASKED_REFERENCE_ONLY"`이며, **secret material(자격증명 원문)은 어떤 필드로도 제공하지 않는다.** 실제 자격증명은 워크로드가 K8s Secret을 직접 마운트해 사용한다.
- **플랫폼 정책상 raw password는 절대 반환하지 않는다.** 응답(`KafkaPrincipalSecretResponse`) 필드는 `principalId`, `username`, `status`, `namespace`, `secretName`, `availableKeys`(존재 key 목록), `passwordMasked="********"`, `retrievedAt`, `exposurePolicy="MASKED_REFERENCE_ONLY"`이며, **secret material(자격증명 원문)은 어떤 필드로도 제공하지 않는다.** 실제 자격증명은 워크로드가 K8s Secret을 직접 마운트해 사용한다.
- 무결성 가드: principal이 ACTIVE가 아니면 `WORKSPACE_FORBIDDEN`, TenantProvisioner 네이밍(secretName==principal username) 불일치·Secret/password key 부재·Secret 내부 username alias 불일치 시 `KAFKA_PRINCIPAL_NOT_FOUND`(fail-closed).
- 감사: 조회 성공 시 `AuditService.record(..., "KAFKA_PRINCIPAL_SECRET_VIEW", ...)`와 `OpsLog`를 남기되 detail/log에는 username·secretName만 포함하고 raw password는 어디에도 기록하지 않는다.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@

이 문서는 Agent action의 위험도와 승인 기준을 정의한다. Policy Guard는 이 문서를 기준으로 `allow`, `require_approval`, `require_change_management`, `deny` 중 하나를 선택한다.

**최종 집행·정본은 Spring Boot의 [server.md §7.1 Operation Allowlist](../../backend-springboot/server.md#71-operation-allowlist-현재-집행-경계)다.** 이 policy matrix는 사전 판단이며, 현재 Spring이 실제로 실행 가능한 mutation은 connector restart/pause/resume과 managed consumer group restart subset이다(불일치 시 Spring 기준 우선).
**최종 집행 기준은 Spring Boot의 `InternalOpsMutationController`, `MutationGate`, `PolicyGuard` 구현과 [governance.md §7 Mutation allowlist](../../backend-springboot/governance.md#7-mutation-allowlist)다.** 이 policy matrix는 사전 판단이며, 현재 Spring이 실제로 실행 가능한 mutation은 connector restart/pause/resume과 managed consumer group restart subset이다(불일치 시 Spring 기준 우선).

### 2. Decision

Expand Down
2 changes: 1 addition & 1 deletion docs/design/backend-springboot/auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@

- access token은 API 응답의 `accessToken`으로 발급한다. SSE용으로는 더 짧은 토큰을 쿼리로 전달할 수 있다(§5).
- `/api/auth/**` legacy alias는 v1 controller 계약이 아니다. 현재 security matcher는 `/api/auth/login`만 permitAll로 두어 handler 부재 404에 도달하고, `/api/auth/refresh`·`/api/auth/me`는 인증 필요, `/api/auth/register`는 Bearer 없이는 401이다. 클라이언트는 `/api/v1/auth/**`만 호출한다.
- `/api/v1/auth/me`의 `namespace`는 workspace API의 `projectKey`와 같은 슬러그다. 코드 정본은 `MeResponse`다(`services/operations-backend/src/main/java/com/bifrost/ops/auth/dto/MeResponse.java:8-19`).
- `/api/v1/auth/me`의 `namespace`는 workspace API의 `projectKey`와 같은 슬러그다. 응답 필드는 `MeResponse`를 기준으로 한다(`services/operations-backend/src/main/java/com/bifrost/ops/auth/dto/MeResponse.java:8-19`).

### 3. JWT 구조·공유 검증

Expand Down
Loading
Loading