kube-apiserver启动失败，如何排查？

Question

kube-apiserver启动失败时，常见问题之一是证书配置错误。例如，apiserver使用的server.crt或ca.crt路径不正确、证书过期或签发不匹配，会导致TLS握手失败，进而使服务无法启动。此时查看日志（如journalctl -u kube-apiserver）通常会显示“x509 certificate signed by unknown authority”或“failed to load key pair”。需检查/etc/kubernetes/pki/下相关证书的权限、有效期及SAN（Subject Alternative Name）是否包含节点IP和域名。使用openssl x509 -in server.crt -text -noout可验证证书内容。重建证书可使用kubeadm init phase certs apiserver重新生成。确保kubeconfig中引用的证书路径与实际一致，是排查此类问题的关键步骤。

Answer 1

1. 问题背景与现象分析

在Kubernetes集群中，kube-apiserver作为核心组件，负责暴露API接口并处理所有REST请求。当其因证书配置错误而启动失败时，典型表现是服务无法绑定到端口6443，且进程反复重启。通过查看系统日志：
journalctl -u kube-apiserver -f
常见错误信息包括：

• x509: certificate signed by unknown authority
• failed to load key pair: tls: failed to find any PEM data in certificate input
• certificate has expired or is not yet valid

这些提示明确指向TLS证书验证环节的问题，通常涉及路径、权限、有效期或签发链不匹配。

2. 常见证书错误类型分类

错误类型	可能原因	典型日志输出
证书路径错误	配置文件中指定的--tls-cert-file或--tls-private-key-file路径不存在或拼写错误	failed to load key pair
CA信任链断裂	ca.crt未被正确签发或缺失，客户端kubelet/kubectl使用了不同CA	x509: certificate signed by unknown authority
证书过期	默认kubeadm生成的证书有效期为1年	certificate has expired
SAN缺失IP/域名	新节点IP未包含在server.crt的Subject Alternative Name中	subject doesn't match

3. 深度排查流程图

```mermaid
graph TD
    A[kube-apiserver启动失败] --> B{检查systemd日志}
    B --> C[journalctl -u kube-apiserver]
    C --> D[定位错误关键词]
    D --> E{x509相关?}
    E -- 是 --> F[检查/etc/kubernetes/pki/apiserver.*]
    E -- 否 --> G[转向其他模块排查]
    F --> H[openssl x509 -in server.crt -text -noout | grep 'Subject Alternative Name']
    H --> I[确认IP/DNS是否覆盖当前节点]
    I --> J[检查文件权限: 600 for key, 644 for cert]
    J --> K[验证CA签发关系: openssl verify -CAfile ca.crt server.crt]
    K --> L{验证通过?}
    L -- 否 --> M[重建证书]
    L -- 是 --> N[检查kubeconfig引用路径一致性]
```

4. 关键诊断命令清单

以下命令应按顺序执行以全面评估证书状态：

1. ls -la /etc/kubernetes/pki/{apiserver.crt,apiserver.key,ca.crt} —— 验证文件存在性与权限
2. openssl x509 -in /etc/kubernetes/pki/apiserver.crt -noout -dates —— 查看有效起止时间
3. openssl x509 -in /etc/kubernetes/pki/apiserver.crt -text -noout | grep "Subject Alternative Name" -A 5 —— 确认SAN列表
4. openssl rsa -in /etc/kubernetes/pki/apiserver.key -check 2>/dev/null && echo "Key is valid" —— 私钥完整性检测
5. openssl verify -CAfile /etc/kubernetes/pki/ca.crt /etc/kubernetes/pki/apiserver.crt —— 验证签发链
6. grep -r "tls-cert-file\|tls-private-key-file" /etc/kubernetes/manifests/kube-apiserver.yaml —— 核对实际加载路径
7. cat /etc/kubernetes/controller-manager.conf | grep client-certificate —— 确保kubeconfig引用正确证书
8. kubeadm certs check-expiration —— 批量检查所有控制平面证书过期情况
9. ps aux | grep apiserver | grep -oP '--tls-cert-file=\S+' —— 实际运行参数抓取
10. diff <(openssl x509 -in ca.crt -pubkey -noout) <(openssl pkey -in apiserver.key -pubout) —— 公私钥匹配校验（高级）

5. 解决方案与自动化修复策略

根据排查结果，可采取如下措施：

• 证书重建：使用kubeadm重新生成apiserver证书
  kubeadm init phase certs apiserver --apiserver-advertise-address=192.168.10.10 \
--apiserver-cert-extra-sans=lb.example.com,192.168.10.11
• 批量更新场景：若整个集群证书接近过期，建议执行
  kubeadm certs renew all
  并配合sudo systemctl restart kubelet触发重载。
• 手动替换证书后，务必确保静态Pod被重新创建：
  mv /etc/kubernetes/manifests/kube-apiserver.yaml /tmp/ && sleep 20 && mv /tmp/kube-apiserver.yaml /etc/kubernetes/manifests/
• 权限修复脚本示例：

#!/bin/bash
PKI_DIR="/etc/kubernetes/pki"
chmod 600 $PKI_DIR/apiserver.key
chmod 644 $PKI_DIR/apiserver.crt $PKI_DIR/ca.crt
chown root:root $PKI_DIR/apiserver.*