코드로서의 운영 및 → 관리 문서

코드로 거래 문서

1) 접근법의 본질

Code로서의 문서화는 Git, 풀 요청, 검토 및 CI 검증을 통해 운영 지식, 명령 및 프로세스가 코드와 동일한 방식으로 저장, 편집 및 검증되는 관행입니다.
연산 루프에서 이것은 신뢰성, 투명성 및 명령 호환성의 기초를 형성합니다.

• 각 명령어가 구식 PDF가 아닌 인프라의 아티팩트 인 생생하고 재현 가능하며 다양한 지식 시스템을 만듭니다.

2) 왜 필요한가

투명성: 누가, 언제, 왜 절차를 변경했는지 알 수 있습니다.
일관성: 모든 팀은 현재 버전에서 작동합니다.
CI/CD와의 통합: 명령어의 자동 검증.
복제 성-인프라 및 문서가 동기화됩니다.
보안: Git을 통한 액세스 제어 및 감사.
온 보딩 가속: 새로운 운영자는 정확한 코드 관련 시나리오를 봅니다.

3) 주요 시설

4) 리포지토리 아키텍

ops-docs/
├── README.md        # описание структуры
├── standards/
│  ├── sop-deploy.md
│  ├── sop-oncall.md
│  └── sop-release.md
├── runbooks/
│  ├── payments-latency.md
│  ├── games-cache.md
│  └── kyc-verification.md
├── playbooks/
│  ├── dr-failover.yaml
│  ├── psp-switch.yaml
│  └── safe-mode.yaml
├── postmortems/
│  └── 2025-03-17-bets-lag.md
├── policies/
│  ├── alerting.yaml
│  ├── communication.yaml
│  └── security.yaml
└── templates/
├── postmortem-template.md
├── sop-template.md
└── playbook-template.yaml

팁: 각 폴더에는 고유 한 Git 저장소 또는 하위 모듈이있어 다른 팀이 컨텐츠를 독립적으로 관리 할 수 있습니다.

5) 형식 및 표준

yaml id: sop-deploy owner: platform-team version: 3.2 last_review: 2025-10-15 tags: [deployment, ci-cd, rollback]
sla: review-180d

Цель
Контекст
Последовательность шагов
Проверка результата
Риски и откат
Контакты и каналы

yaml name: failover-psp triggers:
- alert: PSP downtime steps:
- action: check quota PSP-X
- action: switch PSP-Y
- action: verify payments latency < 200ms rollback:
- action: revert PSP-X

6) GitOps 및 프로세스 변경

Pull Request = RFC 문서 변경.
검토: 도메인 소유자와 Ops 책임자는 승인해야합니다.
CI 검증: 구조 검사, 필수 필드, Markdown/YAML 린터.
자동 게시: 병합 후-IM/wiki/대시 보드 생성.
로그 변경: 날짜 및 저자에 대한 변경 사항의 자동 기록.
알림: N 일마다 문서 수정 (SLA).

7) CI/CD 통합

린트 검사: 마크 다운 구문, YAML 유효성, 소유자/버전 필드.
링크 확인: 탭 및 내부 링크 확인.

문서 빌드: HTM/Confluence/portal로 변환

Diff 분석: 문서의 마지막 릴리스 이후 변경된 사항.

자동 동기화: 대시 보드 Grafana, Ops UI, Slack의 링크 업데이트

봇 검토: 오래된 섹션 또는 누락 된 소유자에 대한 팁.

8) 운영 도구와의 통합

Grafana/Kibana: 패널에서 직접 주석과 해당 런북에 대한 링크.
인시던트 관리자: 티켓을 만들 때 "오픈 런북" 버튼.
통화 중 포털: 사건 범주별 현재 SOP 및 플레이 북 발행.
AI 어시스턴트: 저장소 검색, TL 생성; DR 및 액션 팁.
BCP 패널-스크립트가 활성화되면 자동으로 DR 명령어를로드합니다.

9) 문서 라이프 사이클 관리

10) 자동화 및 동기화

문서 봇: 어떤 문서가 오래되었는지 확인하십시오.
버전 배지: '! [마지막 검토: 2025-05] '모자에.
런북 파인더: 경고로 원하는 문서를 태그별로 엽니 다.
템플릿 생성기: 템플릿별로 새 SOP를 생성합니다 ('새 Sop' 배포 ').
감사 동기화: SOP 버전을 시스템 릴리스 및 커밋 ID와 연결합니다.

11) 보안 및 개인 정보 보호

저장소 당 RBAC: 도메인 소유자 만 편집 할 수 있습니다.
비밀과 PII: 공개 문서에 보관할 수 없습니다. 보호 금고에만 연결됩니다.
감사: 모든 변경 사항, 리뷰 및 출판물 기록.
업데이트 정책: 6 개월마다 SOP 검토.
백업: DR 영역의 일반 저장소 스냅 샷 및 포털 캐시.

12) 성숙도 지표

13) 반 패턴

다른 위치에서 동일한 명령어를 중복하십시

문서는 버전과 소유자없이 Google 문서에 저장됩니다.
출시 후 런북이 업데이트되지 않습니다.
SOP는 레거시 명령/도구를 나타냅니다.
CI 검증 없음: 오류가있는 마크 다운 및 링크 고장.
소유자 부족 및 검토 프로세스.

14) 구현 점검표

• 도메인 소유자와 문서 소유자를 식별합니다.
• Git 저장소 'ops-docs/' 및 SOP/runbook/playbook 템플릿을 만듭니다.
• CI 검사 및 라인터 설정 (Markdown/YAML).
• 포털 또는 위키에 자동 게시를 설정합니다.
• Grafana/Incident Manager와 통합.
• 알림 및 SLA 개정을 위해 Ops 봇을 추가하십시오.
• 코드로서의 워크 플로 명령을 훈련시킵니다.

15) 30/60/90-구현 계획

• 저장소 구조, 템플릿, CI 라인터 및 PR 검토 프로세스를 만듭니다.
• 주요 SOP 및 5-10 개의 중요한 런북을 마이그레이트하십시오.
• 포털에 자동 빌드를 설정합니다.

• 사건 관리자 및 Grafana와의 통합 구현.
• 감사 및보고를 위해 Ops 봇을 연결하십시오.
• 사후 템플릿을 업데이트하고 대시 보드 사건에 대한 링크.

• SOP/런북의 전체 범위 (90% 이상).
• KPI 입력: 적용 범위, 검토 SLA, 사용.
• "코드로서의 문서" 프로세스의 편리성과 품질에 대한 복고풍.

16) SOP 템플릿의 예 (Markdown)

SOP: Deployment через ArgoCD id: sop-deploy owner: platform-team last_review: 2025-10-15 tags: [deployment, rollback, argo]

Цель
Обеспечить безопасное и управляемое развертывание сервисов через ArgoCD.

Контекст
Используется для всех микросервисов с шаблоном Helm v2+.
Требует активного GitOps-контура и включенных health-checks.

Последовательность шагов
1. Проверить статус `argocd app list`
2. Выполнить `argocd app sync payments-api`
3. Убедиться, что `status: Healthy`
4. В случае проблем — `argocd app rollback payments-api --to-rev <rev>`

Проверка результата
SLO API доступность ≥ 99.95%, алертов нет.

Риски и откат
- Ошибка синхронизации — rollback.
- При повторных ошибках — эскалация Head of Ops.

Контакты
@platform-team / #ops-deploy

17) 다른 프로세스와의 통합

운영 분석: 적용 범위 및 SLA 감사 보고서.
운영자 교육: 실제 런북을 기반으로 한 교육.
사후 모템: SOP 및 플레이 북에 대한 링크를 자동으로 삽입합니다.
거버넌스 윤리: 변화와 저자의 투명성.
AI 어시스턴트: 컨텍스트 검색 및 TL; 저장소에서 DR.

18) FAQ

Q: 혼란이있는 이유는 무엇입니까?
A: Git은 버전, 검토, 자동화 및 재현성을 제공합니다. 결합은 궁극적 인 쇼케이스 일 수 있지만 진실의 원천은 아닙니다.

Q: 오래된 지침을 피하는 방법?
A: 개정 용 SLA (180 일) + Ops 알림 봇 + 마지막 수표의 자동 배지.

Q: CI를 문서에 연결할 수 있습니까?
A: 예. 구문, 필요한 필드 및 깨진 참조는 코드 테스트와 유사한 표준 파이프 라인으로 확인됩니다.