操作和管理→操作文档作为代码

操作文档作为代码

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：是的。语法，必填字段和位链接的验证作为标准管道执行，类似于代码测试。