调试部署失败：识别常见的 YAML 和配置错误

Kubernetes 部署失败通常表现为 Pod 卡在 Pending、ImagePullBackOff、CrashLoopBackOff 或可用副本数为零。原因通常可以在事件中看到，但你需要按正确顺序检查 Deployment、ReplicaSet 和 Pod。

本指南将带你逐步检查，通常能发现 YAML 错误、镜像拉取问题、错误的探针、资源限制以及阻止部署正常运行的调度规则。

第一步：检查部署状态和事件

当部署失败时，你的第一步诊断应始终包括检查主资源本身及其管理的 ReplicaSet 和 Pod 相关事件。这提供了 Kubernetes 正在尝试做什么以及为什么失败的宏观视图。

1. 检查部署健康状况

使用 kubectl get deployments 查看整体状态。特别关注 READY、UP-TO-DATE 和 AVAILABLE 列。这里的差异表明底层 Pod 存在问题。

kubectl get deployments <deployment-name>

如果部署状态显示很少或零个就绪副本，请继续检查 ReplicaSet。

2. 查看 ReplicaSet 和 Pod 事件

ReplicaSet 管理所需数量的 Pod。如果部署失败，ReplicaSet 通常是错误级联的源头。使用 describe 命令检查 ReplicaSet，其名称通常为 <deployment-name>-<hash>：

kubectl describe rs <replicaset-name>

关键是要检查输出底部的 Events 部分。这部分详细说明了最近的操作，包括调度尝试、镜像拉取失败和卷挂载问题。这些事件通常是关键线索。

最后，检查 Pod 本身，因为它们报告了直接的失败：

kubectl get pods -l app=<your-app-label>
kubectl describe pod <pod-name>

查看 Pod 描述中的 State 和 Reason 字段。常见原因包括 ImagePullBackOff、ErrImagePull、CrashLoopBackOff 和 Pending。

YAML 清单中的常见配置错误

YAML 文件中的错误配置是部署失败的最常见原因。这些错误可能从简单的缩进错误到复杂的结构问题。

1. YAML 语法和结构错误

Kubernetes API 对正确的 YAML 语法（缩进、空格和数据类型）非常敏感。如果 YAML 无效，kubectl apply 通常会立即失败，并提示无法解析文件。

最佳实践：使用 Linter 在应用之前始终验证 YAML 语法。像 yamllint 或集成 IDE 支持等工具可以立即捕获基本语法错误。

常见结构错误示例： 错误的映射或缩进。

# 错误：containers 应属于 spec.template.spec，而不是直接属于 spec.template
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    metadata:
      labels:
        app: my-app
    containers:
      - name: my-app
        image: myregistry/myapp:v1

正确放置：

spec:
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: myregistry/myapp:v1
          ports:
            - containerPort: 8080

2. 镜像引用和拉取错误

如果 Pod 进入 ImagePullBackOff 或 ErrImagePull，问题与访问容器镜像有关。

镜像名称/标签拼写错误： 仔细检查镜像仓库、名称和标签的拼写。
私有仓库认证： 如果从私有仓库拉取，请确保已创建镜像拉取密钥，并在 Pod 规范中引用为 imagePullSecrets。

# 显示 ImagePullSecret 用法的片段
spec:
  imagePullSecrets:
    - name: my-registry-secret
  containers:
    - name: my-app
      image: private.example.com/my-app:v1

3. 资源请求和限制违规

如果 Pod 保持在 Pending 状态，并且事件提到资源不足，则集群节点无法满足 YAML 中定义的 CPU 或内存要求。

检查部署清单中指定的限制：

resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1"

故障排除步骤：

使用 kubectl describe nodes 查看可用容量。
如果你看到类似 0/3 nodes are available: 3 Insufficient cpu 的事件，你必须降低 YAML 中的 requests 或向集群添加更多节点。

高级配置问题

除了基本语法和镜像拉取之外，涉及网络、存储和调度的复杂配置可能导致难以诊断的失败。

1. 探针配置错误（存活和就绪）

如果 Pod 转换为 CrashLoopBackOff，通常意味着容器启动但立即失败检查，或者启动但反复失败就绪探针。

存活探针： 如果反复失败，Kubernetes 会重启容器。检查 kubectl describe pod <pod-name> 中的探针失败事件，并在重启后检查 kubectl logs <pod-name> --previous。
就绪探针： 如果失败，Pod 继续运行但被排除在 Service 端点之外。确保路径、端口和预期响应代码与应用程序实际提供的匹配。

常见就绪探针错误示例： 针对错误的端口，或期望 HTTP 而应用程序仅暴露 TCP。

2. 卷和 PersistentVolumeClaim (PVC) 失败

如果 Pod 因卷问题而挂起，请检查 PVC 状态：

kubectl get pvc <pvc-name>

如果 PVC 状态为 Pending，则表示集群找不到匹配的 StorageClass 或合适的 PersistentVolume 来绑定。检查 PVC 事件以获取特定的绑定错误。

3. 亲和性和反亲和性规则

复杂的调度规则，如 nodeAffinity 或 podAntiAffinity，可能会无意中阻止 Pod 调度，如果没有节点满足所有条件。如果 Pod 保持 Pending 并且事件提到调度限制，请检查这些规则。

例如，如果你要求 Pod 在具有特定标签（nodeSelector）的节点上运行，而现有节点没有该标签，则 Pod 将永远不会被调度。

# 示例：将部署限制到标记为 'disktype: ssd' 的节点
spec:
  nodeSelector:
    disktype: ssd
  containers:
  # ...

故障排除提示： 临时注释掉限制性的 nodeSelector 或 affinity 规则。如果 Pod 成功调度，你就知道问题出在选择标准上。

调试工作流程

面对失败的部署时，请遵循以下结构化路径：

部署状态： kubectl get deployments -> 副本是否报告就绪？
Pod 事件： kubectl describe pod <failing-pod> -> 检查 Events 部分以获取即时错误（ImagePull、OOMKilled、卷问题）。
容器日志： kubectl logs <failing-pod> -> 如果容器启动但崩溃（CrashLoopBackOff），则怀疑应用程序逻辑或存活探针。
资源检查： 如果 Pod 处于 Pending，检查资源限制（Insufficient cpu/memory）或失败的卷绑定（PVC 状态）。
配置验证： 检查 YAML 的缩进、正确的字段名称和有效的资源值（requests/limits）。

根据集群的证据而不是猜测来工作。按顺序检查状态、事件、日志、资源和清单结构，然后进行与发现的错误匹配的最小 YAML 更改。