操作和管理→操作文檔作為代碼

操作文檔作為代碼

1）方法的本質

作為代碼的文檔（Documentation as Code）是一種實踐，其中以與代碼相同的方式存儲，編輯和驗證操作知識，指示和過程：通過Git，pull requests，review和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存儲庫或Sabmodul,以便不同的團隊可以獨立管理內容。

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。
評論：域名所有者和行動負責人必須批準。
CI驗證：結構驗證，必填字段，Markdown/YAML linter。
自動發布：merge後生成HTML/wiki/dashbords。
更改日誌：更改的自動歷史與日期和作者。
警告提醒：每N日修訂一份文件 （SLA）。

7） CI/CD集成

Lint檢查：Markdown語法，YAML有效性，所有者/版本字段。
鏈接檢查：檢查URL和內部鏈接。
Docs-build：轉換為HTML/Confluence/門戶。
Diff分析：自上次文檔發布以來發生了什麼變化。
自動同步：更新了Grafana、Ops UI、Slack行車記錄板中的鏈接。
評論機器人：關於過時部分或缺席所有者的提示。

8）與操作工具集成

Grafana/Kibana：直接從面板中註釋和引用相應的運行手冊。
事件管理器：創建tiket時的「Open Runbook」按鈕。
通話門戶：按事件類別發布最新的SOP和劇本。
AI助手：通過存儲庫搜索，TL生成；DR和行動建議。
BCP面板：在激活腳本時自動加載DR指令。

9）文檔生命周期管理

10）自動化和同步

Docs-bot：檢查哪些文檔已過時。
版本徽章：「！［最後的評論：2025-05］」就在帽子裏。
Runbook-finder：通過標註打開所需的文檔。
Templates generator：根據模板創建新的SOP（"make new sop "Dployment"）。
審核同步：將SOP版本與系統版本和commit-ID關聯。

11）安全和隱私

RBAC到存儲庫：只能從域所有者訪問編輯。
秘密和PII：不能保存在公開文檔中；僅指向安全保險庫的鏈接。
審計：記錄所有更改、評論和出版物。
更新政策：每6個月修訂一次SOP。
Backups： DR區中的常規存儲庫快照和門戶緩存。

12）成熟度量

13）反模式

文檔存儲在Google Docs中，沒有版本或所有者。
發布後不會更新Runbook。
SOP引用過時的命令/工具。
沒有CI驗證：帶有錯誤和失敗鏈接的Markdown。
在不同的位置重復相同的指令。
缺少所有者和審查過程。

14）實施支票

• 確定域所有者和文檔負責人。
• 創建「ops-docs/」 Git存儲庫和SOP/runbook/劇本模板。
• 自定義CI 檢查和linter （Markdown/YAML）。
• 將自動發布配置為門戶或Wiki。
• 與Grafana/Incident Manager集成。
• 添加用於提醒和SLA修訂的Ops-bot。
• 對團隊進行「基於代碼的工作流」的培訓。

15）30/60/90-實施計劃

• 創建存儲庫結構、模板、CI-linter和公關流程。
• 移動關鍵SOP和5-10關鍵運行手冊。
• 將自動構建配置為門戶。

• 與Incident Manager和Grafana實現集成。
• 連接Ops-bot進行審核和報告。
• 更新後驗屍模板並鏈接到dashbord事件。

• SOP/runbook的完整覆蓋範圍（≥90％）。
• 引入KPI： Coverage, Review SLA, Usage。
• 對「文檔代碼」過程的便利性和質量進行復古。

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）與其他流程的集成

操作分析：審核的Coverage和SLA報告。
操作員培訓：基於真實運行手冊的培訓。
後驗：自動插入對SOP和劇本的引用。
管理倫理：變革透明度和作者身份。
AI助手：上下文搜索和TL；來自存儲庫的DR。

18) FAQ

Q： 如果有會議,為什麼Git?

答：Git提供版本，評論，自動化和可重現性。會議可能是一個終極的展示，但不是真相的來源。

Q： 如何避免過時的指令?

答：修訂版SLA （180天）+Ops-bot提醒+最新檢查的自動徽章。

Q： CI能否連接到文檔?

A：是的。語法，必填字段和位鏈接的驗證作為標準管道執行，類似於代碼測試。