Kubernetes OOMKilled Runbook 实战解析：以 checkout-svc 内存限值修复为例

Kubernetes OOMKilled Runbook 实战解析：以 checkout-svc 内存限值修复为例

【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks

本文以 Claude Cookbooks 仓库中的 SRE 值班演示为背景，逐条拆解 runbooks/oom.md 这份 OOMKilled runbook 的编写逻辑与落地过程。runbook 是"故障特征 → 排查路径 → 标准修复"的结构化浓缩：它以 exit 137 与 OOMKilled 事件为症状入口，给出确认击杀来源、检查 Deployment 内存 limit、比对工作集并提升限值、约束 request 与 limit 关系的四步分诊流程。本文同时结合仓库内配套的 checkout-deploy.yaml 清单、alert.json 告警负载，以及 sre_incident_responder.ipynb 的完整 agent 会话，说明 runbook 如何被值班 agent（Skill 机制）读取、执行并收敛到"只改限值、不开 PR 不热修"的合规动作上。读完本文，你将掌握：如何识别容器 OOMKilled 的可靠信号、如何阅读 Deployment 的 resources 段判断根因、内存 request/limit 的合理配比，以及这类 runbook 应如何撰写才能被人工与 Agent 共同准确执行。

这份 OOMKilled runbook 在演示中扮演的角色

仓库将这份 runbook 放在 SRE 事件响应演示的工作区（workspace）中，与告警、基础设施清单并列，共同构成一个自包含、无需外部服务的离线演练场景，相关文件均位于managed_agents/example_data/sre/下：

• runbooks/oom.md —— 按故障特征组织的人肉/Agent 双读排查手册（本文主体）；
• infra/k8s/checkout-deploy.yaml —— "基础设施仓库"中被抽查的目标清单；
• alert.json —— 触发会话的 PagerDuty V3 风格告警事件。

这份 runbook 被 sre_incident_responder.ipynb 以file类型资源挂载到会话目录runbooks/oom.md，同时通过一个名为incident-runbooks的 Skill（SKILL.md）向 Agent 宣告团队约定："runbooks 按故障特征组织（如oom.md、5xx.md、latency.md），每份列出该类故障的排查步骤与通常需要改动的配置；任何基础设施修复都必须以引用所遵循 runbook 的 PR 形式提出，禁止直接热修线上资源。" 也就是说，oom.md 既是给人看的文档，也是 Skill 让 Agent 知道"该去哪里查、按什么顺序查"的路标。仓库 example_data/OVERVIEW.md 说明这类 fixture 刻意保持短小并埋有可被真正发现的问题（此处即过低的 128Mi 内存 limit），目的是让 Agent 有东西可推敲，而非一次就成功的玩具。

症状识别：把 OOMKilled 从其它失败中分离出来

runbook 开头用三行定义了本手册适用的故障特征集合，这是"按失败特征组织 runbook"的核心：

理解这些信号需要一点 Kubernetes 背景：容器被杀后，docker inspect/kubectl describe pod返回的退出码 137 = 128 + 9（SIGKILL），是 kubelet 内建 OOM killer 判死刑的标准印记；而"OOMKilled"会作为 Pod 的 Last State Reason 出现在 Pod 事件里。真正属于本手册管辖范围的，是内核/kubelet 层的内存击杀，而不是 JVM/Go runtime 等应用自身抛出OutOfMemoryError后自主退出或靠应用级限流兜底的情况——runbook 第一步就要求把二者分开，这决定了后续动作完全不同。

在演示会话中，Agent 正是按这个特征集去匹配的：它从挂载日志中识别出OutOfMemoryError、堆从 101MB 快速爬升到 118→121MB、GC 停顿达 412ms、随后容器以 exit 137 被 OOMKilled、约每 2 分钟重复一轮（5 分钟内重启 7 次）——这正是 alert.json 中restarts_5m: 7与标题checkout-svc pods crash-looping (CrashLoopBackOff)所指的现场。告警负载data.details携带cluster: prod-us-east、namespace: shop、deployment: checkout-svc等字段，这些字段在后续定位清单时被直接复用。

分诊四步：从确认击杀到修正限值

runbook 的中段给出了严格有序的分诊流程，每一步都有明确产出，适合逐条照做：

1. 确认击杀来源是 kubelet 的 OOM killer（exit 137），而非应用自身限制。这一步过滤掉"应用自己管理堆、自己退出"的假阳性，避免把配置问题误诊成资源问题。
2. 打开 Deployment 清单（runbook 标注的路径模板为infra/k8s/<service>-deploy.yaml），检查spec.template.spec.containers[].resources.limits.memory。在演示中即 checkout-deploy.yaml：

   resources: requests: cpu: 250m memory: 128Mi limits: cpu: 500m memory: 128Mi

   对照上述 L21-L27，可确认清单把 request 与 limit 都压在 128Mi，而服务在定价缓存（pricing cache）预热到约 1.4 万条目后堆占用已达 121MB，占 limit 的 94%——limit 几乎与工作集齐平，任何 GC 或突发分配都会立刻触发击杀。

3. 对照服务文档化的工作集判断：runbook 给出明确基准——checkout-svc 在定价缓存预热后需要约 400Mi 工作集；若 limit 低于该基准则上调，且 512Mi 是"标准下一档"（standard next tier）。这是一个把经验沉淀进手册的范例：不给模糊的"调大一点"，而是给出可验证的数字与档位。
4. 保持requests.memory≤ 新 limit。这是 Kubernetes 调度语义的硬约束——request 决定节点调度与 QoS 归类，limit 决定运行时上限；若 request 反而高于 limit，Pod 无法被正确调度或会陷入非预期状态。演示中的修复即遵循该约束：request 提到 256Mi、limit 提到 512Mi，两者都低于节点容量且留有 4 倍余量。

修复约束：只走 PR，不热修

runbook 结尾给出与 Skill 中"不得热修"约定一致的硬性流程要求：

Fix:open a PR against the infra repo with the corrected limit. Do not hot-patch the live deployment.

这条规则的价值在于强制变更可审、可回滚、可审计。在演示会话中，Agent 依此先备份原始文件、就地编辑，再用diff -u生成 unified diff，最终形成的修复即把 resources 段的两处 128Mi 分别改为 256Mi（request）与 512Mi（limit）。随后 agent 调用自定义工具open_pull_request(title, body, diff)提交 PR、调用request_approval(summary)等待值班人决策，只有收到{"decision": "approved"}后才允许调用merge_pull_request(pr_number)合并——系统提示词中明令：未获批准绝不 merge，且修复保持最小化、不重构无关配置。这正是 runbook "改最小可证正确的量"原则在 Agent 执行层的落地。

从一份 runbook 到一套可执行手册的写作要点

回到仓库本身可以提炼出这类 runbook 的通用结构，便于自建团队手册：

1. 症状区（What you see）：用机器可匹配的精确特征定义适用范围。退出码、事件名、日志错误类（如OOMKilled/ exit 137 / heap-exhausted）远比散文描述更适合人机共读；Agent 正是靠这些特征把日志指纹对到oom.md这一份手册上的。
2. 分诊区（How to triage）：步骤化、可执行，每一步包含"做什么、在哪看、期望看到什么"。演示中的步骤 2 直接给出 YAML 路径模板infra/k8s/<service>-deploy.yaml，使任何服务都能套用同一路径查找。
3. 决策基准（Numbers）：明确工作集期望值（约 400Mi）与标准档位（512Mi），避免临场拍脑袋；同时写明 request/limit 关系约束。
4. 动作边界（What not to do）：明确禁止热修、强制 PR 流程，与团队 Skill 中的约定互为呼应。

想要亲手复现这份 runbook 的完整执行链路，可运行仓库中的 sre_incident_responder.ipynb：配置ANTHROPIC_API_KEY后，notebook 会完成 Skill 上传、Agent 创建、环境与资源挂载、用 alert.json 触发会话、应答自定义工具调用直至人工审批并合并的全过程，最终可在 Console 的 Sessions 视图回放每一步事件。注意演示把 PagerDuty/GitHub/Datadog 均以本地 fixture 模拟，生产接入时按 notebook 末尾说明将自定义工具替换为 GitHub MCP、将审批投递到 Slack 按钮即可。

小结

oom.md 演示了一类高质量 runbook 应有的密度：短到几分钟可读完，却完整覆盖了"信号识别 → 定位配置 → 数字比对 → 合规动作"的闭环。它对人类值班员是速查卡，对挂载了 incident-runbooks Skill 的 Claude 值班 Agent 则是可逐条执行的指令序列——二者最终收敛到同一个最小修复：把 checkout-svc 的内存 request/limit 从 128Mi 提升到 256Mi/512Mi，并以 PR 而非热修的方式落地。

【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks