Bài 6 — Runbook tự động: biến tài liệu thành hành động

Mọi team đều có runbook — tài liệu "khi X xảy ra thì làm Y". Vấn đề: chúng nằm chết trong wiki, lỗi thời, và lúc 3h sáng chẳng ai nhớ. Agent biến runbook thành thực thi được (executable).

Ba dạng runbook cho agent

• Runbook mô tả (prose): viết bằng ngôn ngữ tự nhiên, agent LLM đọc-hiểu và suy luận bước. Linh hoạt nhưng khó đảm bảo.
• Runbook cấu trúc (structured): dạng YAML/JSON các bước rõ ràng. Ít linh hoạt, dễ kiểm soát.
• Hybrid: cấu trúc cho các bước, LLM cho phần quyết định phân nhánh. Đây là dạng thực chiến tốt nhất.

Ví dụ runbook hybrid

runbook: disk_full
trigger: alert == "DiskUsageHigh"
steps:
  - id: identify
    action: query
    cmd: "df -h | sort -k5 -r | head"
    output: mount_usage
  - id: decide
    type: llm_branch          # để agent suy luận
    prompt: "Dựa trên {mount_usage}, phân loại: log_bloat | data_growth | leak"
  - id: mitigate_log_bloat
    when: decide == "log_bloat"
    action: exec
    cmd: "find /var/log -name '*.log' -mtime +7 -delete"
    reversible: false          # cần review!
    require_approval: true
  - id: mitigate_data_growth
    when: decide == "data_growth"
    action: exec
    cmd: "scale_up_volume --size +20%"
    reversible: true
    autonomous: true

Các bước xây runbook tự động

• Bắt đầu từ runbook đã có. Chọn 3–5 runbook chạy thường xuyên nhất, độ rủi ro thấp.
• Đánh dấu mỗi bước: reversible? autonomous hay require_approval? Đây là guardrail nằm ngay trong runbook.
• Tách phần quyết định (LLM) và phần thực thi (deterministic). LLM chọn nhánh; thực thi là lệnh cố định, đã kiểm chứng.
• Test trên staging với dữ liệu giả. Cho alert giả bắn, xem agent chạy runbook đúng nhánh không.
• Ghi lại mỗi lần chạy để cải thiện runbook (bước nào agent chọn sai, bước nào thiếu).

Khung tư duy: runbook = code, cần vòng đời

Coi runbook như phần mềm:

• Versioned: để trong git, review qua PR.
• Tested: có test trên staging.
• Observable: mỗi lần chạy có log, biết bước nào fail.
• Iterated: cập nhật khi hệ thống đổi.

Runbook "chết" trong wiki thiếu cả 4 yếu tố này.

Ví dụ thực tế: certificate hết hạn

Alert CertExpiringSoon. Agent chạy runbook renew_cert:

• identify: xác định domain và cert path.
• renew: gọi certbot renew (autonomous, reversible — cert cũ vẫn dùng được tới khi hết hạn).
• validate: kiểm tra cert mới hợp lệ (openssl x509 -checkend).
• reload: nginx -s reload.
• Nếu bước validate fail → không reload, giữ cert cũ, báo người. Fail-safe: khi nghi ngờ, không làm hỏng trạng thái đang tốt.

Sai lầm thường gặp

• Runbook chỉ toàn LLM prose, không đánh dấu reversible/approval. Agent có thể chạy bước phá hoại mà không ai chặn.
• Không phân biệt bước quyết định và bước thực thi. Trộn lẫn khiến khó test và dễ sai.
• Không test trên staging. Lần chạy thật đầu tiên trên production là canh bạc.
• Runbook không versioned. Không biết ai sửa gì, không rollback được khi runbook sai.
• Quên nhánh fail-safe. Mọi runbook cần đường "nếu không chắc thì dừng và báo người".

Kiểm thử runbook trên staging

Lần chạy thật đầu tiên trên production là canh bạc. Thay vào đó, hãy dựng một "drill" trên staging: bắn alert giả và quan sát agent chạy runbook đúng nhánh không.

def test_runbook_disk_full():
    fake_alert = {"type": "DiskUsageHigh", "mount": "/var/log", "usage": 95}
    result = run_runbook("disk_full", fake_alert, dry_run=True)
    assert result.branch == "log_bloat"          # agent phân loại đúng
    assert result.action == "require_approval"    # bước xóa cần duyệt
    assert "kubectl delete namespace" not in result.commands  # không lệnh chết người

Mỗi runbook mới nên có ít nhất một test kiểu này trước khi lên production. Test cũng đóng vai "tài liệu sống": đọc test là hiểu runbook làm gì.

Runbook cần cập nhật khi hệ thống đổi

Runbook "chết" nguy hiểm hơn không có runbook, vì nó dẫn agent làm sai một cách tự tin. Ví dụ: runbook restart_service dùng systemctl nhưng hệ thống đã chuyển sang Kubernetes — lệnh sẽ fail hoặc tệ hơn là tác động nhầm chỗ. Hãy gắn runbook vào vòng đời hạ tầng: khi kiến trúc đổi, coi việc rà lại runbook liên quan như một phần của change đó. Một runbook nên có trường last_verified để bạn biết nó đã được kiểm chứng gần nhất khi nào.

Tóm tắt

Runbook tự động biến tài liệu chết thành hành động sống. Dùng dạng hybrid: LLM quyết định phân nhánh, lệnh deterministic thực thi. Đánh dấu reversible/approval ngay trong runbook, đối xử với runbook như code (versioned, tested trên staging, observable, có last_verified), và luôn có nhánh fail-safe.