İşlemler ve - Kod Olarak İşlemlerin Yönetim Belgeleri

Kod Olarak İşlem Belgeleri

1) Yaklaşımın özü

Kod olarak dokümantasyon, operasyonel bilginin, talimatların ve süreçlerin kodla aynı şekilde depolandığı, düzenlendiği ve doğrulandığı bir uygulamadır: Git, pull-requests, review ve CI validation.
Operasyonel bir döngüde bu, güvenilirlik, şeffaflık ve komut uyumluluğunun temelini oluşturur.

• Her bir talimatın altyapının bir eseri olduğu ve eski bir PDF olmadığı canlı, tekrarlanabilir ve sürümlü bir bilgi sistemi oluşturun.

2) Neden ihtiyacınız var

Şeffaflık: Prosedürü kimin, ne zaman ve neden değiştirdiğini görebilirsiniz.
Tutarlılık: Tüm ekipler mevcut sürümler üzerinde çalışır.
CI/CD ile entegrasyon: Talimatların otomatik olarak doğrulanması.
Çoğaltılabilirlik - Altyapı ve belgeler senkronize edilir.
Güvenlik: Git aracılığıyla erişim kontrolü ve denetimi.
Onboarding hızlandırma: Yeni operatörler kodla ilgili senaryoları tam olarak görürler.

3) Ana tesisler

4) Depo mimarisi

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

İpucu: Her klasörün kendi Git deposu veya alt modülü vardır, böylece farklı ekipler içeriği bağımsız olarak yönetebilir.

5) Format ve standartlar

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 ve değişim süreçleri

Pull Request = RFC dokümantasyon değişiklikleri.
İnceleme: Alan adı sahibi ve Ops Başkanı onaylamalıdır.
CI doğrulama: yapı denetimi, zorunlu alanlar, Markdown/YAML linter.
Otomatik yayınlama: birleştirmeden sonra - HTML/wiki/gösterge tabloları oluşturma.
Değişiklik günlüğü: Tarihler ve yazarlar ile değişikliklerin otomatik geçmişi.
Uyarı hatırlatıcıları: Her N günde bir belge revizyonu (SLA tarafından).

7) CI/CD entegrasyonu

Lint kontrolleri: Markdown sözdizimi, YAML geçerliliği, sahip/sürüm alanları.
Link-check: URL'leri ve dahili bağlantıları kontrol etme.
Docs-build: HTML/Confluence/portal'a dönüştürme.
Diff analizi: Belgelerin son yayınlanmasından bu yana neler değişti?
Otomatik senkronizasyon: Grafana, Ops UI, Slack panolarındaki bağlantıları günceller.
İnceleme botları: Eski bölümler veya eksik sahipler için ipuçları.

8) Operasyonel araçlarla entegrasyon

Grafana/Kibana: doğrudan panelden ilgili çalışma kitabına ek açıklamalar ve bağlantılar.
Incident Manager: Bilet oluştururken "Open Runbook" butonu.
Çağrı portalı: Mevcut SOP'ların ve oyun kitaplarının olay kategorisine göre verilmesi.
AI asistanları: depo arama, TL üretimi; DR ve eylem ipuçları.
BCP panelleri - Bir komut dosyası etkinleştirildiğinde DR talimatlarını otomatik olarak yükler.

9) Belge Yaşam Döngüsü Yönetimi

10) Otomasyon ve senkronizasyon

Docs bot: Hangi belgelerin güncel olmadığını kontrol eder.
Versiyon rozeti: '! [Son inceleme: 2025-05] 'tam kapağında.
Runbook-finder: uyarı ile istenen belgeyi etiketle açar.
Templates-generator: şablona göre yeni SOP'lar oluşturur ('make new-sop "Deployment"').
Audit-sync: SOP sürümünü sistem sürümü ve commit-ID ile ilişkilendirir.

11) Güvenlik ve gizlilik

Depo başına RBAC: yalnızca alan adı sahipleri düzenleyebilir.
Sırlar ve PII: Açık belgelerde saklanamaz; Sadece korunan kasalara bağlantılar.
Denetim: Tüm değişikliklerin, incelemelerin ve yayınların günlüğü.
Güncelleme Politikası: SOP'ların her 6 ayda bir gözden geçirilmesi.
Yedeklemeler: DR bölgesinde düzenli arşiv anlık görüntüleri ve portal önbellekleri.

12) Olgunluk metrikleri

13) Anti-desenler

Belgeler, sürümler ve sahipler olmadan Google Dokümanlar'da saklanır.
Runbook sürümlerden sonra güncellenmez.
SOP, eski komutları/araçları ifade eder.
CI doğrulaması yok: Hatalarla ve kırık bağlantılarla işaretleme.
Aynı talimatları farklı konumlarda çoğaltın.
Sahiplerin eksikliği ve inceleme süreci.

14) Uygulama kontrol listesi

• Etki alanı sahiplerini ve belge sahiplerini tanımlayın.
• Git deposu 'ops-docs/'ve SOP/runbook/playbook şablonları oluşturun.
• CI kontrollerini ve astarlarını (Markdown/YAML) yapılandırın.
• Portal veya Wiki'ye Otomatik Yayınlama Yapılandırması.
• Grafana/Olay Yöneticisi ile entegre edin.
• Hatırlatıcılar ve SLA revizyonları için bir Ops bot ekleyin.
• Dokümanları kod olarak eğit iş akışı komutları.

15) 30/60/90 - uygulama planı

• Depo yapısı, şablonlar, CI linter ve PR inceleme süreci oluşturun.
• Önemli SOP'ları ve 5-10 kritik runbook'ları taşıyın.
• Portalda otomatik oluşturma ayarlayın.

• Olay Yöneticisi ve Grafana ile entegrasyonlar uygulayın.
• Denetimler ve raporlama için Connect Ops botu.
• Ölüm sonrası şablonunu güncelleyin ve pano olayına bağlantı verin.

• SOP/runbook'un tam kapsamı (% ≥90).
• KPI girin: Kapsam, İnceleme SLA, Kullanım.
• "Kod olarak dokümanlar" sürecinin rahatlığı ve kalitesi üzerine Retro.

16) SOP şablonu örneği (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) Diğer süreçlerle entegrasyon

Operasyonel analiz: Kapsam ve SLA denetim raporları.
Operatör eğitimi: Gerçek runbooklara dayalı eğitim.
Postmortems: SOP ve playbook'a otomatik bağlantı ekleme.
Yönetişim etiği: Değişimin şeffaflığı ve yazarlık.
AI asistanları: bağlam arama ve TL; Depodan DR.

18) SSS

S: Birleşim varsa neden Git?
A: Git sürümleri, inceleme, otomasyon ve tekrarlanabilirlik verir. Birleşme nihai vitrin olabilir, ancak gerçeğin kaynağı değildir.

S: Eski talimatlardan nasıl kaçınılır?
A: Revizyon için SLA (180 gün) + Ops-hatırlatma botları + son kontrolün otomatik rozeti.

S: CI belgelere bağlanabilir mi?
A: Evet. Sözdizimi, gerekli alanlar ve bozuk referanslar, kod testlerine benzer şekilde standart boru hattı olarak kontrol edilir.