runbook-generator

ランブックジェネレーター

運用手順、インシデント対応、システムメンテナンス作業向けの、包括的で標準化されたランブックの作成に精通しています。

ランブックの構成

runbook_template:
  metadata:
    title: "Runbook title"
    version: "1.0"
    last_updated: "2024-01-15"
    owner: "Team/Person"
    reviewers: ["Name 1", "Name 2"]

  overview:
    purpose: "What this runbook accomplishes"
    scope: "Systems/services affected"
    audience: "Who should use this"

  prerequisites:
    access:
      - "AWS Console access"
      - "SSH key for production servers"
      - "Database credentials"
    tools:
      - "kubectl configured"
      - "AWS CLI installed"
      - "jq for JSON parsing"
    knowledge:
      - "Basic Kubernetes concepts"
      - "Understanding of service architecture"

  execution:
    estimated_time: "15-30 minutes"
    risk_level: "Medium"
    requires_change_ticket: true
    requires_approval: true
    can_be_automated: true

  steps: []  # Detailed steps below

  verification: []  # How to confirm success

  rollback: []  # How to undo changes

  troubleshooting: []  # Common issues

  contacts:
    primary_oncall: "PagerDuty"
    escalation: "Engineering Manager"
    subject_experts: ["DBA Team", "Platform Team"]

標準ランブックテンプレート

# [Runbook Title]

**Version:** 1.0
**Last Updated:** YYYY-MM-DD
**Owner:** Team Name
**Risk Level:** Low | Medium | High | Critical

## Overview

### Purpose
Brief description of what this runbook accomplishes.

### When to Use
- Trigger condition 1
- Trigger condition 2
- Alert: "Alert Name" fires

### Scope
Systems and services affected:
- Service A
- Database B
- External dependency C

## Prerequisites

### Required Access
- [ ] Production AWS Console
- [ ] Kubernetes cluster access
- [ ] Database read/write permissions

### Required Tools
```bash
# Verify kubectl
kubectl version --client

# Verify AWS CLI
aws sts get-caller-identity

# Verify database connectivity
psql -h $DB_HOST -U $DB_USER -c "SELECT 1"

必要な知識

• Kubernetes ポッドの管理
• サービスアーキテクチャの概要
• インシデント対応プロセス

実行前チェックリスト

• 変更チケットを作成済み：CHG-XXXXX
• 承認を取得済み：［名前］
• バックアップを確認済み（該当する場合）
• 関係者に通知済み
• メンテナンス時間を設定済み（該当する場合）

実行手順

ステップ 1：［アクション名］

目的： このステップが必要な理由

コマンド：

kubectl get pods -n production -l app=myservice

想定される出力：

NAME                        READY   STATUS    RESTARTS   AGE
myservice-abc123-xyz        1/1     Running   0          2d
myservice-def456-uvw        1/1     Running   0          2d

確認： すべてのポッドの STATUS が Running であることを確認します

想定外の場合： 「トラブルシューティング」セクションを参照してください

---

ステップ 2：［次のアクション］

目的： 説明

コマンド：

# Command with explanation
kubectl scale deployment myservice --replicas=3 -n production

想定される出力：

deployment.apps/myservice scaled

確認：

# Verify new replicas are running
kubectl get pods -n production -l app=myservice -w

待機条件： 3 つすべてのポッドのステータスが Running になるまで待ちます（通常 2～5 分）

---

実行後の確認

サービスの正常性を確認

# Check deployment status
kubectl rollout status deployment/myservice -n production

# Check service endpoints
kubectl get endpoints myservice -n production

# Verify application health
curl -s https://api.example.com/health | jq .

想定される結果：

{
  "status": "healthy",
  "version": "1.2.3",
  "uptime": "2h30m"
}

メトリクスを確認

• エラー率が正常値に戻っている（<0.1%）
• レイテンシが SLA の範囲内である（p99 <200ms）
• 新たに発生したアラートがない

ロールバック手順

ロールバックする条件

• エラー率が 1% を超える
• レイテンシが p99 で 500ms を超える
• 重要な機能に障害が発生している

ロールバックの手順

# Rollback to previous deployment
kubectl rollout undo deployment/myservice -n production

# Verify rollback
kubectl rollout status deployment/myservice -n production

# Confirm previous version
kubectl get deployment myservice -n production -o jsonpath='{.spec.template.spec.containers[0].image}'

トラブルシューティング

症状	考えられる原因	解決方法
ポッドが Pending のままになる	リソースの制約	ノードの容量を確認します：kubectl describe nodes
CrashLoopBackOff	アプリケーションエラー	ログを確認します：kubectl logs -f <pod>
ImagePullBackOff	レジストリの認証に関する問題	シークレットを確認します：kubectl get secret regcred
接続が拒否される	サービスの準備ができていない	Readiness Probe を待ち、エンドポイントを確認します

よくある問題

問題：デプロイがタイムアウトする

# Check pod events
kubectl describe pod <pod-name> -n production

# Check resource limits
kubectl top pods -n production

問題：データベース接続に失敗する

# Verify database connectivity
kubectl exec -it <pod> -n production -- psql -h $DB_HOST -c "SELECT 1"

# Check connection pool
kubectl logs <pod> -n production | grep -i "connection"

緊急連絡先

役割	連絡先	連絡が必要な状況
オンコールエンジニア	PagerDuty	あらゆる問題
データベースチーム	#dba-oncall	データベースの問題
プラットフォームチーム	#platform-oncall	インフラストラクチャの問題
エンジニアリングマネージャー	［名前］	エスカレーション

変更履歴

バージョン	日付	作成者	変更内容
1.0	2024-01-15	Author	初版

関連ドキュメント

• サービスアーキテクチャ
• インシデント対応プロセス
• 監視ダッシュボード

## Runbook Types

### Incident Response Runbook

```yaml
incident_runbook:
  sections:
    detection:
      alert_name: "High Error Rate - Payment Service"
      threshold: "Error rate > 5% for 5 minutes"
      severity: "P1"

    immediate_actions:
      - step: "Acknowledge alert"
        command: "In PagerDuty, acknowledge incident"
        time: "< 5 min"

      - step: "Assess impact"
        command: |
          # Check error rate
          curl -s "https://metrics.example.com/api/v1/query?query=rate(http_errors[5m])"
        time: "< 2 min"

      - step: "Notify stakeholders"
        action: "Post in #incident-channel"
        template: |
          🚨 INCIDENT: Payment Service High Errors
          Severity: P1
          Status: Investigating
          Impact: Payment processing affected
          IC: @oncall

    investigation:
      - "Check recent deployments"
      - "Review error logs"
      - "Check dependent services"
      - "Review infrastructure metrics"

    mitigation:
      options:
        - name: "Rollback deployment"
          when: "Error started after deploy"
          command: "kubectl rollout undo deployment/payment -n prod"

        - name: "Scale up"
          when: "Load-related errors"
          command: "kubectl scale deployment/payment --replicas=10 -n prod"

        - name: "Enable circuit breaker"
          when: "Downstream dependency failing"
          command: "Toggle feature flag: payment.circuit_breaker=true"

    resolution:
      checklist:
        - "[ ] Error rate < 0.1%"
        - "[ ] No P1 alerts"
        - "[ ] Stakeholders notified"
        - "[ ] Incident documented"

デプロイランブック

deployment_runbook:
  pre_deployment:
    checklist:
      - "[ ] Code review approved"
      - "[ ] CI/CD pipeline passed"
      - "[ ] Staging tested"
      - "[ ] Change ticket approved"
      - "[ ] Rollback plan documented"

    verification:
      - step: "Verify staging health"
        command: |
          curl -s https://staging.example.com/health

      - step: "Check deployment queue"
        command: |
          kubectl get pods -n staging -l app=myservice

  deployment:
    - step: "Apply deployment"
      command: |
        kubectl apply -f k8s/production/deployment.yaml

    - step: "Monitor rollout"
      command: |
        kubectl rollout status deployment/myservice -n production --timeout=10m

    - step: "Verify new version"
      command: |
        kubectl get deployment myservice -n production \
          -o jsonpath='{.spec.template.spec.containers[0].image}'

  post_deployment:
    - step: "Smoke test"
      command: |
        ./scripts/smoke-test.sh production

    - step: "Monitor metrics"
      duration: "15 minutes"
      watch:
        - "Error rate"
        - "Latency p99"
        - "Request rate"

    - step: "Update ticket"
      action: "Mark CHG ticket as completed"

メンテナンスランブック

maintenance_runbook:
  log_rotation:
    schedule: "Weekly, Sunday 02:00 UTC"

    steps:
      - step: "Connect to server"
        command: |
          ssh [email protected]

      - step: "Rotate logs"
        command: |
          sudo logrotate -f /etc/logrotate.d/application

      - step: "Verify rotation"
        command: |
          ls -la /var/log/application/
          # Should see rotated files with date suffix

      - step: "Clean old logs"
        command: |
          # Remove logs older than 30 days
          find /var/log/application/ -name "*.log.*" -mtime +30 -delete

      - step: "Verify disk space"
        command: |
          df -h /var/log
          # Should show > 20% free

  database_maintenance:
    schedule: "Monthly, first Sunday 03:00 UTC"

    steps:
      - step: "Check table sizes"
        command: |
          psql -c "
            SELECT tablename,
                   pg_size_pretty(pg_total_relation_size(tablename::text))
            FROM pg_tables
            WHERE schemaname = 'public'
            ORDER BY pg_total_relation_size(tablename::text) DESC
            LIMIT 10;
          "

      - step: "Run VACUUM ANALYZE"
        command: |
          psql -c "VACUUM ANALYZE;"

      - step: "Reindex if needed"
        command: |
          psql -c "REINDEX DATABASE mydb;"

執筆ガイドライン

principles:
  clarity:
    - "Use active voice"
    - "Be explicit, never assume"
    - "One action per step"

  completeness:
    - "Include all commands"
    - "Show expected output"
    - "Document verification"

  safety:
    - "Test in non-prod first"
    - "Include rollback steps"
    - "Document risks"

formatting:
  commands:
    - "Use code blocks with language"
    - "Include full paths"
    - "Add comments for complex commands"

  steps:
    - "Number sequentially"
    - "Include purpose"
    - "Show expected result"
    - "Note time estimate"

  variables:
    format: "$VARIABLE_NAME or <placeholder>"
    document: "List all variables at start"

品質チェックリスト

validation:
  structure:
    - "[ ] Clear title and metadata"
    - "[ ] Prerequisites listed"
    - "[ ] Steps numbered and clear"
    - "[ ] Expected outputs included"
    - "[ ] Verification steps present"
    - "[ ] Rollback documented"
    - "[ ] Troubleshooting section"
    - "[ ] Contacts listed"

  testing:
    - "[ ] All commands tested"
    - "[ ] Outputs verified"
    - "[ ] Rollback tested"
    - "[ ] Time estimates accurate"

  maintenance:
    - "[ ] Version number updated"
    - "[ ] Change log maintained"
    - "[ ] Quarterly review scheduled"
    - "[ ] Owner assigned"

ベストプラクティス

1. すべてをテストする — 各コマンドを検証する必要があります
2. 想定される出力を示す — 実行後に何が表示されるかをユーザーが把握できるようにします
3. ロールバック手順を含める — 常にロールバック計画を用意します
4. 最新の状態に保つ — 四半期ごとにレビューします
5. バージョン管理する — ランブックを git で管理します
6. 可能な場合は自動化する — 繰り返し行う手順を自動化します