이 글에서 다루는 것

Runbook / Security / Proof / Audit 운영 문서 구조와 Proof 파일 생성 방식

선수지식

• GitOps 기반 E2E ML Platform - 운영 제어 구조

운영 문서화

• Runbook / Security / Proof 디렉토리까지 남긴 이유

들어가며

많은 프로젝트는 다음 단계에서 멈춥니다.

코드 작성
README 작성

하지만 실제 운영 환경에서는 다음 문제가 발생합니다.

• 서비스 장애 발생
• 운영자가 시스템 구조를 모름
• 복구 절차 문서 없음
• 보안 정책 위치 불명확

이 경우 시스템이 아무리 잘 만들어져 있어도

운영 대응이 어려워집니다.

그래서 이 프로젝트에서는 코드 외에

다음 문서 구조를 함께 구성했습니다.

Runbook
Security
Proof
Audit

즉

코드를 설명하는 문서가 아니라

운영을 설명하는 문서 구조를 만들었습니다.

문서 디렉토리 구조

이 프로젝트의 문서 구조는 다음과 같습니다.

docs/
 ├─ overview
 │   ├─ architecture.md
 │   ├─ e2e-flow.md
 │   └─ airflow-dag-integration.md
 │
 ├─ runbook
 │
 ├─ security
 │
 └─ proof
     └─ latest

각 디렉토리는 서로 다른 목적을 가집니다.

Runbook: 운영 절차 문서

Runbook은 운영자가 시스템을 관리할 때 사용하는 문서입니다.

예를 들어 다음 상황을 생각해볼 수 있습니다.

• 모델 배포 실패
• Triton 모델 로딩 실패
• FastAPI reload 오류
• Airflow DAG 실패

이 경우 운영자는 다음 정보를 필요로 합니다.

어떤 명령을 실행해야 하는가
어떤 로그를 확인해야 하는가
어떤 서비스 상태를 확인해야 하는가

이 정보를 Runbook에 정리합니다.

실제 구조:

docs/runbook/
 ├─ observability.md
 └─ optional-toggle.md

이 문서는 다음 상황에서 사용됩니다.

운영 장애 대응
서비스 복구 절차
운영 인수인계

즉 Runbook은

운영자가 실제로 사용하는 문서입니다.

Security 문서

ML 플랫폼은 다양한 시스템을 포함합니다.

예를 들어 이 프로젝트에는 다음 시스템이 있습니다.

Airflow
MLflow
Triton
FastAPI
MinIO
Prometheus
ArgoCD

각 시스템은 다음 정보를 필요로 합니다.

Secret
Access token
Webhook
Storage credential

이 정보는 반드시 관리되어야 합니다.

그래서 이 프로젝트에서는 보안 관련 문서를

별도 디렉토리로 분리했습니다.

docs/security/

이 문서에는 다음 내용이 포함됩니다.

Secret 관리 정책
Sealed Secrets 사용 방식
Credential rotation 전략
External access 정책

즉 보안 관련 내용은 코드가 아니라

문서로도 설명됩니다.

Proof 디렉토리

이 프로젝트에서 가장 특징적인 문서는

Proof 디렉토리입니다.

경로:

docs/proof/latest/

이 디렉토리는 다음 목적을 가집니다.

시스템이 실제로 동작했음을 기록

많은 프로젝트는 다음과 같은 방식으로 설명됩니다.

아키텍처 다이어그램
코드 설명
설정 파일

하지만 이 방식만으로는

시스템이 실제로 동작했는지 확인할 수 없습니다.

그래서 이 프로젝트에서는

실행 결과를 파일로 기록했습니다.

Proof 구조

Proof 디렉토리에는 다음 항목이 포함됩니다.

docs/proof/latest/
 ├─ e2e_success
 ├─ core_only
 ├─ optional_on
 └─ observability

각 디렉토리는 다음 내용을 증명합니다.

즉 이 구조는 다음 질문에 답합니다.

이 시스템이 실제로 동작하는가?

Proof 생성 방식

Proof는 다음 스크립트로 생성됩니다.

make proof-e2e

또는

./ops/proof/proof_e2e_success.sh

이 스크립트는 다음 작업을 수행합니다.

Triton 상태 확인
FastAPI 상태 확인
Reload API 실행
Metrics 확인

그리고 결과를 파일로 저장합니다.

예시:

triton_dev_ready_and_repo_index.txt
fastapi_dev_health_models_metrics.txt
reload_dev_variant_A.json

이 파일들은 단순 로그가 아니라

시스템이 실제로 동작했다는 증거입니다.

왜 Proof가 필요한가

이 Proof 구조는 다음 상황에서 특히 중요합니다.

포트폴리오 제출

이 프로젝트가 실제로 동작했는가?

면접 설명

이 플랫폼을 실제로 운영해봤는가?

운영 기록

배포 결과가 무엇이었는가?

Proof 디렉토리는 이 질문들에 대해

파일로 답할 수 있게 합니다.

운영 문서화의 목적

이 프로젝트에서 문서 구조는

단순 설명 문서가 아닙니다.

각 문서는 다음 역할을 합니다.

즉 문서는 코드 설명이 아니라

운영 시스템을 설명하는 구조입니다.

설계 판단 (Why This Way?)

README만으로는 장애 대응과 보안 정책을 전달할 수 없으므로 Runbook/Security/Proof를 디렉토리 구조로 분리하여 문서 종류별 위치를 강제했습니다. Proof는 make proof-e2e 스크립트로 자동 생성하여 수동 기록의 누락 없이 재현 가능한 검증 기록을 남깁니다.

다음에 읽을 글

→ GitOps 기반 E2E ML Platform - 부하 테스트 — k6로 검증한 Triton + FastAPI 서빙 성능