26Y27b1

QK·2026년 7월 26일

Air-Gapped Cloud-Native 환경에서 Confluence 문서 수집, Markdown 변환, Git 저장, 그리고 하이브리드 인덱싱(OpenSearch + Qdrant)을 수행하는 AIOps Sync Worker Container Container와 연계 시스템 간 전반적인 관계도, 구성 절차, 컨테이너 내부 연동 방식을 종합 정리해 드립니다.

1. 전반적인 아키텍처 연계 구성도 (Relationship Diagram)

+---------------------------------------------------------------------------------------------------+
|                                  Air-Gapped Enterprise Network                                    |
|                                                                                                   |
|  [ Internal Source ]               [ Single Source of Truth ]        [ RAG Engine & Embedding ]   |
|  +-------------------+             +-----------------------+         +-------------------------+  |
|  |  1. Confluence    |             |  2. Bitbucket         |         |  4. OpenSearch          |  |
|  |  (Storage / REST) |             |  (Git Repository)     |         |  (Sparse / BM25)        |  |
|  +---------+---------+             +-----------+-----------+         +------------+------------+  |
|            |                                   ^                                  ^               |
|            | REST API                          | Push (MD + Assets)               | Bulk Ingest   |
|            v                                   v                                  |               |
|  +--------------------------------------------------------------------------------+------------+  |
|  |                                                                                             |  |
|  |   [ Sync Worker Container Image ] (Executed via K8s CronJob)                                |  |
|  |   - Step 1: CQL Incremental Extractor (State Tracking)                                      |  |
|  |   - Step 2: HTML Cleaning & Page Properties Table Parser                                    |  |
|  |   - Step 3: LLM Fallback Extractor & YAML Front-Matter Synthesis                             |  |
|  |   - Step 4: Markdown & Image/Diagram Assets Processor                                        |  |
|  |   - Step 5: Git Committer & Push Sync                                                       |  |
|  |   - Step 6: Markdown Header Splitter & Dual Ingester                                        |  |
|  |                                                                                             |  |
|  +---------+-----------------------------------+-----------------------------------+-----------+  |
|            |                                   |                                   |              |
|            | REST (Chat)                       | REST (Embeddings)                 | Bulk Ingest  |
|            v                                   v                                   v              |
|  +-------------------+             +-----------------------+         +-------------------------+  |
|  |  3. 사내 Local LLM  |             |  Embedding Engine     |         |  5. Qdrant              |  |
|  |  (vLLM / Qwen32B) |             |  (TEI / BGE-M3)       |         |  (Dense Vector DB)      |  |
|  +-------------------+             +-----------------------+         +-------------------------+  |
+---------------------------------------------------------------------------------------------------+

2. 연계 대상별 사전 준비 및 구성 절차 (Setup Checklist)

① Confluence (문서 원본 제공)

인증 설정: Sync Worker가 접속할 Personal Access Token (PAT) 생성 및 권한 부여 (해당 Space 읽기 권한).
템플릿/표준화: 엔지니어 대상 Page Properties(문서 속성) 매크로가 포함된 SOP / 작업계획서 표준 템플릿 배포 (doc_type, target_solutions, environment, status 항목 포함).

② Bitbucket (Git 버전 관리 & Single Source of Truth)

저장소 생성: ops-knowledge-repo 전용 Git Repository 생성.
서비스 계정 및 SSH/HTTP Token: Sync Worker가 K8s 내에서 Non-interactive하게 Push할 수 있도록 Repository Write 권한을 가진 PAT 발급 (또는 SSH Key 등록).

③ 사내 Local LLM & Embedding Engine (지능형 메타데이터 및 Vector 생성)

Main LLM (vLLM): Qwen2.5-Coder-32B-Instruct 등 코딩/JSON 구조화 추출 능력이 뛰어난 모델을 vLLM 인퍼런스 서버로 띄우고 OpenAI 호환 REST API 엔드포인트([http://vllm.internal:8000/v1](http://vllm.internal:8000/v1)) 개방.
Embedding Inference (TEI): HuggingFace TEI (Text Embeddings Inference) 컨테이너로 bge-m3 (또는 e5-large-v2) 모델을 띄워 고속 벡터화 REST API([http://tei.internal/embed](http://tei.internal/embed)) 준비.

④ OpenSearch (Sparse Index - BM25)

인덱스 생성 (Index Mapping): 에러 코드, 고유 식별자, CLI 명령문 검색을 위한 Analyzer 설정 적용.

PUT /ops-knowledge-sparse
{
  "mappings": {
    "properties": {
      "doc_id": { "type": "keyword" },
      "chunk_id": { "type": "keyword" },
      "content": { "type": "text", "analyzer": "standard" },
      "doc_type": { "type": "keyword" },
      "target_solutions": { "type": "keyword" },
      "environment": { "type": "keyword" },
      "status": { "type": "keyword" },
      "commit_hash": { "type": "keyword" }
    }
  }
}

⑤ Qdrant (Dense Vector DB)

컬렉션 생성 (Collection Creation): 임베딩 모델의 차원(Dimension, 예: BGE-M3 = 1024) 및 거리 알고리즘 설정.

curl -X PUT "http://qdrant.internal:6333/collections/ops-knowledge-dense" \
     -H 'Content-Type: application/json' \
     -d '{
       "vectors": { "size": 1024, "distance": "Cosine" }
     }'

Payload Indexing: 빠른 Filtering을 위해 doc_type, target_solutions, status 필드에 Payload Index 적용.

3. 컨테이너 이미지 내부 연동 방식 (Container Script Integration)

컨테이너 실행 시 main.py를 Entrypoint로 지정하여 1개 흐름 안에서 5개 시스템을 유기적으로 연동합니다.

작업 단계	연동 대상 시스템	내부 처리 방식 및 모듈 역할
Step 1. 증분 감지	1. Confluence	`confluence_client.py`: State File의 `last_sync_time` 이후 수정된 문서 CQL REST API로 수집
Step 2. 1차 메타 추출	(Internal Logic)	`converter.py`: HTML 파싱 중 `data-macro-name="details"` 표(Page Properties)를 찾아 사람 작성 메타데이터 추출
Step 3. 2차 메타 보충	3. 사내 Local LLM	`converter.py`: 필수 메타데이터(`doc_type` 등) 누락 시 vLLM REST API 호출 후 JSON 응답 추출 $\rightarrow$ YAML Front-Matter 최종 작성
Step 4. 미디어 처리	1. Confluence	`converter.py`: 이미지/Draw.io 파일 다운로드 후 `assets/` 저장 및 상대 경로 링크 변환
Step 5. Git 동기화	2. Bitbucket	`git_sync.py`: `.md` 및 `assets/` 파일 Write $\rightarrow$ `GitPython` 라이브러리로 Commit & Push 후 Latest Commit Hash 반환
Step 6. 임베딩 & Dual Index	4. OpenSearch

5. Qdrant

(+ TEI Engine) | indexer.py:

1) Markdown Header 기준으로 Chunking

2) TEI API 호출하여 Dense Vector 생성

3) OpenSearch(BM25) & Qdrant(Vector+Payload)에 Commit Hash 및 메타데이터와 함께 Bulk Upsert |

4. Kubernetes CronJob 배포 및 Environment / Secret 주입

망분리 K8s 클러스터 내에서 연동에 필요한 토큰과 URL 정보를 K8s Secret 및 ConfigMap으로 분리하여 CronJob 패키징을 완성합니다.

① Secret / ConfigMap 작성 (`aiops-sync-config.yaml`)

apiVersion: v1
kind: Secret
metadata:
  name: aiops-sync-secrets
  namespace: aiops
type: Opaque
stringData:
  CONFLUENCE_TOKEN: "your-confluence-pat-token"
  BITBUCKET_TOKEN: "your-bitbucket-pat-token"
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: aiops-sync-config
  namespace: aiops
data:
  CONFLUENCE_URL: "http://confluence.internal"
  BITBUCKET_REPO_URL: "http://bitbucket.internal/scm/ops/ops-knowledge-repo.git"
  LOCAL_LLM_URL: "http://vllm.internal:8000/v1/chat/completions"
  TEI_EMBEDDING_URL: "http://tei.internal/embed"
  OPENSEARCH_URL: "http://opensearch.internal:9200"
  QDRANT_URL: "http://qdrant.internal:6333"

② CronJob Manifest 작성 (`cronjob.yaml`)

apiVersion: batch/v1
kind: CronJob
metadata:
  name: confluence-aiops-sync-worker
  namespace: aiops
spec:
  schedule: "*/10 * * * *"  # 10분 마다 실행
  concurrencyPolicy: Forbid  # 중복 실행 방지
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: sync-worker
            image: harbor.internal/aiops/confluence-sync:v1.2.0
            imagePullPolicy: IfNotPresent
            envFrom:
            - configMapRef:
                name: aiops-sync-config
            - secretRef:
                name: aiops-sync-secrets
            volumeMounts:
            - name: git-storage
              mountPath: /workspace/ops-knowledge-repo
          volumes:
          - name: git-storage
            persistentVolumeClaim:
              claimName: ops-knowledge-git-pvc  # Git 저장용 PVC
          restartPolicy: OnFailure

5. 최종 시스템 모니터링 파이프라인

CronJob이 정상적으로 5개 연계 시스템을 완벽히 순회하는지 검증하기 위한 포인트입니다:

Worker Pod Logs: kubectl logs -f job/confluence-aiops-sync-worker-xxxxx를 통해 Confluence 수집부터 Qdrant Upsert 완료까지 예외(Exception) 없이 떨어지는지 확인.
Bitbucket Commit History: 새로운 Commit 메시지(docs(sync): update CONF-XXXX with hybrid metadata)와 함께 .md 파일 및 assets/ 이미지들이 푸시되었는지 확인.
OpenSearch / Qdrant Payload: 검색 엔진 상에서 doc_type == "sop" 및 status == "active"로 필터 검색 시 방금 동기화된 문서의 Chunk들이 올바르게 조회되는지 확인.

engineer

이전 포스트

26Y27a6

다음 포스트

26Y27b1

1. 전반적인 아키텍처 연계 구성도 (Relationship Diagram)

2. 연계 대상별 사전 준비 및 구성 절차 (Setup Checklist)

① Confluence (문서 원본 제공)

② Bitbucket (Git 버전 관리 & Single Source of Truth)

③ 사내 Local LLM & Embedding Engine (지능형 메타데이터 및 Vector 생성)

④ OpenSearch (Sparse Index - BM25)

⑤ Qdrant (Dense Vector DB)

3. 컨테이너 이미지 내부 연동 방식 (Container Script Integration)

4. Kubernetes CronJob 배포 및 Environment / Secret 주입

① Secret / ConfigMap 작성 (`aiops-sync-config.yaml`)

② CronJob Manifest 작성 (`cronjob.yaml`)

5. 최종 시스템 모니터링 파이프라인

26Y27a6

26Y27a7

0개의 댓글

26Y27b1

1. 전반적인 아키텍처 연계 구성도 (Relationship Diagram)

2. 연계 대상별 사전 준비 및 구성 절차 (Setup Checklist)

① Confluence (문서 원본 제공)

② Bitbucket (Git 버전 관리 & Single Source of Truth)

③ 사내 Local LLM & Embedding Engine (지능형 메타데이터 및 Vector 생성)

④ OpenSearch (Sparse Index - BM25)

⑤ Qdrant (Dense Vector DB)

3. 컨테이너 이미지 내부 연동 방식 (Container Script Integration)

4. Kubernetes CronJob 배포 및 Environment / Secret 주입

① Secret / ConfigMap 작성 (aiops-sync-config.yaml)

② CronJob Manifest 작성 (cronjob.yaml)

5. 최종 시스템 모니터링 파이프라인

26Y27a6

26Y27a7

0개의 댓글

① Secret / ConfigMap 작성 (`aiops-sync-config.yaml`)

② CronJob Manifest 작성 (`cronjob.yaml`)