外观
云原生速记手册
摘要
以 Kubernetes 常见工作负载排障为范围。先看对象期望、状态、事件和实例日志,再沿调度、启动、网络及存储路径取证。API、控制器、CNI、CSI 和入口网关的行为依集群版本与插件实现确认。
快速入口
知识速记
| 知识点 | 结论与条件 |
|---|---|
| 控制循环 | 声明期望后由控制器逐步协调;API 写入成功不保证资源已就绪 |
| 容器隔离 | namespace 提供视图,cgroup 计账与限额;共享内核不等于独立虚拟机 |
| 镜像与写层 | 镜像层和容器可写层有不同生命周期;写入容器路径不自动持久化 |
| 调度 | requests 参与放置,节点标签、亲和性、污点与存储约束共同影响可调度性 |
| CPU 限制 | CPU quota 可造成 throttling;平均 CPU 不高不能排除短窗口限流 |
| 内存限制 | 超限可能导致内核终止,OOMKilled 与 JVM Heap OOM 不同;需要容器事件与实际计账 |
| 三类探针 | startup 保护启动期,readiness 控制就绪,liveness 失败可能触发重启;职责不可混用 |
| Service | 选择后端与实际转发是不同环节;EndpointSlice、就绪及数据面传播共同影响路径 |
| Pod 网络 | CNI 建立连接能力,跨节点路由/隧道、MTU 和策略依插件 |
| NetworkPolicy | 标准策略是允许规则的组合,需 CNI 执行支持;不是有对象就一定生效 |
| 存储 | PVC 是声明,PV 是资源,CSI 负责实现链路;Bound 不证明应用挂载和数据写入成功 |
| 配置与 Secret | 环境变量与文件挂载更新方式不同,应用还需重新加载;base64 编码不是加密 |
| 滚动发布 | 副本数、就绪、连接排空与终止共同决定连续服务;maxUnavailable=0 不独立保证无损 |
| HPA | 根据指标与目标计算期望副本,再受窗口及策略约束;副本更多不必然提升下游容量 |
Kubernetes 对象:期望与实际状态
Pod 是部署和调度的基本单元,可包含多个共享网络等资源的容器;Deployment 管理 ReplicaSet 与 Pod 副本;Service 为后端提供服务发现和转发入口。API 接受配置后,控制器与节点组件逐步协调,配置保存成功不等于进程启动、就绪或请求完成。
Pending 要读调度事件和 container 状态,不能只看列表文字。CrashLoopBackOff 是容器反复退出后的退避线索;ImagePullBackOff 是拉取退避;OOMKilled 是容器历史终止原因之一。前两者描述恢复行为,不是具体应用根因。
requests、limits 与调度
requests 用于资源放置等决策;CPU limit 常通过配额约束执行,memory limit 关联内存限制。CPU 平均不高仍可短时被 throttling;内存超限可能被内核终止,不会自动等到 JVM 保存 OOM 日志。
调度还看节点选择、亲和性、污点容忍、拓扑与卷等约束。“有空闲 CPU”不证明可调度:资源请求不够、节点限制或卷绑定都可能阻止放置。HPA 需要可用指标,资源利用率目标还涉及 requests;扩容速率、稳定窗口和上限限制期望副本变化,更多副本不保证数据库容量增加。
三类探针与常用参数
| 探针 | 判断什么 | 失败后的典型动作 |
|---|---|---|
| startup | 是否完成启动 | 达失败阈值后终止容器,按重启策略处理;成功前不启动相关 liveness/readiness 探测 |
| readiness | 是否适合接新流量 | 标记未就绪并影响普通就绪后端选择,不直接重启 |
| liveness | 是否进入需要重启恢复的状态 | 达阈值后终止,再按重启策略处理 |
periodSeconds 是探测间隔,timeoutSeconds 限制一次探测,failureThreshold 是连续失败阈值,successThreshold 是恢复成功阈值,initialDelaySeconds 是启动后初始延迟。间隔乘阈值只能作粗略判断窗口,不是精确故障响应保证。HTTP 检查响应规则,TCP 只证明可连接,exec 看退出码,gRPC 需健康协议及版本支持。
readiness 摘流量有传播延迟,不能瞬间中断所有旧连接,也不覆盖绕过 Service 的 Pod 直连。依赖暂时故障不宜无条件触发所有实例 liveness 重启。
Service、DNS、NetworkPolicy:直接沿路径查
Service selector 找匹配 Pod,EndpointSlice 记录地址及条件,数据面组件按模式转发。依次检查 selector → 实际 endpoints → readiness → port/targetPort → Pod 监听 → 数据面。Pod 能直接访问不能证明 Service 正常。
短名解析受 namespace、search 和 ndots 影响,CoreDNS 提供集群解析但应用也可能有自己的缓存。NetworkPolicy 的入站/出站允许规则需要插件支持;策略相加是允许集合,不是按列表“第一条命中拒绝”。确认两端隔离和 DNS 出站,不用策略对象存在证明实际生效。
存储、配置与 Secret
PVC 声明需求,PV 表示存储资源,CSI 负责驱动链路。Bound 只表示绑定,仍要验证调度、附加、挂载、权限与实际写入。访问模式不自动提供业务锁或跨节点数据一致性。容器写层重建后不承诺保留,持久数据应明确卷、回收策略及备份。
ConfigMap/Secret 通过环境变量注入时通常需要新进程才能拿新值;挂载文件可能随投射更新,但应用要重读,subPath 等方式还有限制。Secret base64 只是编码,RBAC、静态加密、传输、轮换与消费者更新分别保障。
重启、OOM、发布的直接操作顺序
重启先 describe 看历史 reason/exit code,再 previous 日志查应用退出,随后检查探针、配置及资源。OOMKilled 对齐 memory.events、容器 limit、非堆和节点压力,退出码 137 单独不充分。NodeNotReady 查节点条件、心跳、资源及网络,再判断驱逐和恢复,不立即删除所有 Pod。
滚动发布要让新实例真的就绪、旧实例停止接新请求、在途完成并退出。maxSurge 控制额外副本,maxUnavailable 控制不可用预算;maxUnavailable=0 不独立保证零错误。preStop、终止宽限与应用优雅关闭要配合,但固定睡眠不是排空证明。
kubectl get 看列表,describe 看原因与事件,logs --previous 看上一容器日志,EndpointSlice 查服务后端,rollout status 看控制器进度。每一步记录 cluster/context、namespace、Pod UID 和时间,返回成功后继续验证真实业务请求。
常见问题排查
探针职责参考 Kubernetes 探针文档,具体字段按集群版本确认。
| 现象 | 检查顺序 | 证据与下一步 |
|---|---|---|
| Pod Pending | describe 事件 → 调度条件 → requests、节点可用与 PVC | 区分无法调度和镜像/启动问题;根据事件修资源或约束,不盲目重启。 |
| CrashLoopBackOff | 看终止原因、退出码 → previous 日志 → 探针与配置 | 这是退避状态,不是根因;查应用异常、资源终止或探针重启。 |
| OOMKilled | 查容器历史状态与时间 → 查内存事件、limit、非堆与缓存 | 区分单容器超限、节点压力与应用 OOM,调限额前理解峰值及总预算。 |
| 请求慢而 CPU 均值低 | 同窗查 throttling → 看短时负载 → 查锁与下游 | CPU 限制不是唯一候选;用限流计数与延迟关联后再调资源。 |
| Service 没流量 | selector → EndpointSlice → 就绪 → 端口映射 → 实际数据面 | 逐层验证后端,直接 Pod 可达不证明 Service 路径正常。 |
| DNS 超时或名称不对 | 查 Pod resolv.conf → DNS 服务与 CoreDNS → 搜索域/ndots → 实际查询 | 记录查询名与协议,短名搜索放大不等于 DNS 服务本身故障。 |
| PVC Bound 仍挂载失败 | 查 Pod 与卷事件 → 查调度/附加/挂载 → 查驱动与权限 | 绑定、附加和挂载是不同阶段;不要直接删除 PVC 掩盖问题。 |
| 发布时 502 或断流 | 对齐终止时间 → 看就绪与端点传播 → 查连接排空与入口超时 | 只加 preStop 睡眠不能证明请求完整结束;真实负载验证旧实例退出。 |
高频问题:操作与结果判断
以下使用 Kubernetes 的 apps/v1、core/v1 与 discovery.k8s.io/v1;NS、POD、CONTAINER、DEPLOY、SVC 都要替换。先确认 kubectl context。
Pending:事件中的原因决定修改什么
bash
kubectl describe pod POD -n NS
kubectl get pod POD -n NS -o yaml
kubectl get pvc -n NS| 事件或状态 | 检查与动作 |
|---|---|
| FailedScheduling / Insufficient cpu 或 memory | 对照 requests、节点 allocatable 和已分配请求;优化合理请求或增加可用资源 |
| untolerated taint / node affinity 不匹配 | 核对工作负载期望落点,不为通过调度随意解除节点隔离 |
| unbound immediate PersistentVolumeClaims | 查 PVC 事件、StorageClass、供给器与绑定模式 |
| 已有 nodeName、容器仍 Waiting | 转查镜像、卷挂载和容器启动;不是调度器一直失败 |
调度使用请求量和约束,kubectl top 显示的低实时使用率不能证明能放下新 Pod。修改后验收 Pod 已调度、容器运行且 Ready,不只看 Pending 消失。
CrashLoopBackOff:查看上一次退出
bash
kubectl get pod POD -n NS -o yaml
kubectl logs POD -n NS -c CONTAINER --previous --tail=200
kubectl describe pod POD -n NS读 containerStatuses 中 restartCount 和 lastState.terminated 的 reason、exitCode、finishedAt,再关联 Events。应用异常退出:查 previous 日志与配置;探针终止:查 Unhealthy/Killing 和探针路径;OOMKilled:转内存预算。退出码 137 也可能来自其他 SIGKILL 来源,需要 reason 和平台记录支持。
previous 只保留可用的上一实例日志,日志不存在不证明没有异常。修复后跨多个原故障周期观察重启计数、Ready 和实际请求。
Service 无流量:先验证后端是否存在
bash
kubectl get service SVC -n NS -o yaml
kubectl get endpointslices -n NS -l kubernetes.io/service-name=SVC -o yaml
kubectl get pods -n NS --show-labels无 endpoint:比较 selector 与 Pod 标签。endpoint 存在但 ready=false:查 readiness;普通 selector Service 未设置 publishNotReadyAddresses 时按就绪选择后端。端点就绪但失败:查 Service port、targetPort 和容器监听地址,再从获准的同 namespace 客户端分别请求 Pod IP 和 Service 名称。
Pod IP 成功但 Service 失败:查服务转发和网络策略;Service IP 成功但名称失败:查 DNS;Pod IP 也失败:查监听、Pod 路径及两端策略。NetworkPolicy 生效依赖 CNI,不能用策略 YAML 代替连通证据。
发布中断:应用关闭预算必须落在 Pod 宽限期内
bash
kubectl rollout status deployment/DEPLOY -n NS --timeout=120s
kubectl get replicasets -n NS
kubectl describe deployment DEPLOY -n NS先看新旧 ReplicaSet 副本和可用数:新副本不 Ready 则查启动/探针,无法创建则查配额/调度/镜像。maxUnavailable=0 与 maxSurge=1 只是发布策略,仍需足够额外资源。
终止时 preStop 在 TERM 前执行,并计入 terminationGracePeriodSeconds;不能先睡满宽限期再期待应用慢慢排空。示例总宽限期 45s、preStop 留 5s 给传播、应用排空预算 30s、余量 10s,仅是预算示例。传播时间需真实测量,旧连接和长任务另设结束策略。
验收持续发送带请求 ID 的真实请求,关联旧 Pod 退出时间、入口 5xx、未完成任务和新实例 Ready;只看 rollout 成功不等于无损。
终止顺序与宽限期见 Pod 生命周期。多容器、sidecar 和自定义停止信号需另外核对,不能假定所有容器按同一顺序退出。
OOM 与 HPA:扩容前检查限制及指标
用 Pod YAML 看 memory limit 和终止记录,用 kubectl top pod POD -n NS --containers 看当前值;当前值不是退出前峰值。Java 堆、直接内存、线程和本地库都计入预算,增 Xmx 可能使容器更快被杀。
CPU 利用率 HPA 的基础计算为 ceil(当前副本数 × 当前利用率 / 目标利用率)。例如 3 副本、平均 90%、目标 60%,基础结果是 5;实际结果还受容差、缺失/未就绪样本、稳定窗口和策略限制。利用率以 requests 为分母,不能用 limit 替代;缺失资源请求可能使该指标无法计算。
kubectl describe hpa NAME -n NS 中看指标与 Conditions;指标不可用先修采集和请求配置,达到 maxReplicas 先核对容量与下游,再决定扩展。计算与修正规则见 HPA 算法,Pod 诊断见 Debug Pods。
工具与参数
先执行 kubectl config current-context,确认集群与 namespace。以下将 NS、POD、DEPLOY、SVC 替换为目标名称;状态读取需要相应 RBAC 权限。官方诊断入口见 Debug Pods。
| 命令 | 重点观察 | 条件与边界 |
|---|---|---|
kubectl get pods -n NS -o wide | 状态、重启、节点与 IP | 列表状态不代替 containerStatuses 和完整事件 |
kubectl describe pod POD -n NS | 调度、容器、卷与事件 | 事件有保留期限,重复失败需保存时间与原因 |
kubectl logs POD -n NS --tail=100 | 有界应用日志 | 多容器用 -c 指定;日志不覆盖所有平台终止原因 |
kubectl logs POD -n NS --previous --tail=100 | 上一容器实例日志 | 需要已有可读历史,不保证保留全部重启日志 |
kubectl get events -n NS --sort-by=.metadata.creationTimestamp | namespace 时间线 | 事件不是完整审计记录,时间需与应用和节点对齐 |
kubectl get endpointslices -n NS -l kubernetes.io/service-name=SVC | 服务发现的端点集合 | 端点存在不证明插件已传播,也不证明应用可处理请求 |
kubectl top pods -n NS | 资源观测 | 需要 Metrics API;平均采样无法代替峰值、限流和完整内存账本 |
kubectl rollout status deployment/DEPLOY -n NS --timeout=60s | 控制器发布状态 | 60 秒为示例等待预算,命令成功仍需业务验收 |
| requests / limits / terminationGracePeriodSeconds | 放置、约束与退出预算 | 单独改参数不能替代依赖容量及连接排空测试 |
易错点与记忆提示
- 写入成功看 API,就绪成功看控制器,业务成功看请求。
- Pending 看事件,重启看 previous,OOM 看计账:都要结合目标时间窗。
- readiness 不重启,liveness 不背锅:后端故障不宜无条件触发所有实例重启。
- Bound 不等于挂好,挂好不等于可恢复:还需写入、保留与恢复验证。
- Secret 编码不是加密:权限、静态加密、传输与轮换分别设计。
- 扩容前看下游:更多 Pod 可能扩大数据库连接和重试流量。
原理与完整示例
需要原因、源码或完整实验时再阅读:
- 06 - Pod 一直 Pending:Scheduler 如何过滤、评分并选择节点
- 07 - Pod 为什么不断重启:从进程退出到 CrashLoopBackOff
- 09 - Pod 被 OOMKilled,但 JVM 没有堆溢出:cgroup 内存控制原理
- 10 - CPU 利用率不高,接口为什么仍然超时:CPU Limit 与 Throttling
- 11 - Service 有 ClusterIP,流量到底去了哪里:EndpointSlice 与转发数据面
- 13 - 域名偶发解析失败:CoreDNS、搜索域与 ndots
- 16 - Pod 重建后数据为什么丢了:PV、PVC 与 CSI 存储链路
- 18 - 滚动发布为什么仍会中断请求:Deployment、Endpoint 与优雅终止
- 01 - 服务容器化后反而更不稳定:一次请求穿过云原生系统的完整链路
- 21 - Node NotReady 后 Pod 为什么没有立刻迁移:节点检测、驱逐与重新调度
- 17 - ConfigMap 已更新,应用为什么还是旧配置
- 24 - Pod CPU、内存都正常,接口为什么仍然慢:云原生可观测性体系
- 05 - 提交 YAML 后发生了什么:Kubernetes 声明式 API 与控制循环
- 02 - 容器不是轻量虚拟机:进程隔离、文件系统与资源限制的真实边界
- 03 - 镜像为什么越来越大:OverlayFS、镜像分层与写时复制原理
- 08 - 健康检查配错如何制造故障:Liveness、Readiness 与 Startup Probe
- 12 - Pod 之间如何通信:CNI、Veth、路由与跨节点网络
- 15 - NetworkPolicy 配了却没有生效:选择器、方向与 CNI 执行边界
- 22 - Secret 放进 Kubernetes 就安全了吗:凭据存储、传递与轮换
- 20 - HPA 为什么扩容太慢或反复抖动:指标、算法与容量边界