Kubesphere安装过程中x509证书验证问题分析与解决

问题概述

在使用Kubesphere 3.4.1版本在阿里云ECS上部署Kubernetes集群(v1.22.12)时，执行./kk create cluster -f config-sample.yaml命令后出现x509证书验证错误。错误信息显示Kubernetes API Server的证书仅对内部IP地址(10.233.0.1, 172.20.0.251, 127.0.0.1)有效，而无法验证公网IP地址(116.62.163.2)。

问题背景分析

在Kubernetes集群部署过程中，API Server会生成一个TLS证书用于安全通信。默认情况下，这个证书只包含集群内部使用的IP地址和域名。当尝试通过外部IP地址访问API Server时，由于证书中不包含该IP地址，就会触发x509证书验证错误。

根本原因

1. 证书SAN配置不足：Kubernetes API Server的证书没有包含公网IP地址作为Subject Alternative Name (SAN)
2. 网络配置问题：在阿里云环境下，通常使用SLB(负载均衡)暴露API Server服务，但证书没有包含SLB的IP地址
3. Kubekey配置缺失：在创建集群时，没有正确配置控制平面的externalIPs或certSANs参数

解决方案

方法一：修改Kubekey配置文件

在config-sample.yaml中添加以下配置：

spec:
  controlPlaneEndpoint:
    domain: lb.kubesphere.local
    address: "116.62.163.2"
    port: 6443
  kubernetes:
    apiServer:
      certSANs:
        - 116.62.163.2
        - 10.233.0.1
        - 172.20.0.251
        - 127.0.0.1

方法二：手动更新API Server证书

如果集群已经部分创建，可以手动更新证书：

1. 备份现有证书：

   sudo cp -r /etc/kubernetes/pki /etc/kubernetes/pki-backup
   

2. 编辑kubeadm-config ConfigMap：

   kubectl -n kube-system edit cm kubeadm-config
   

   在apiServer部分添加certSANs配置

3. 重新生成证书：

   kubeadm init phase certs apiserver --config /etc/kubernetes/kubeadm-config.yaml
   

4. 重启API Server：

   docker restart $(docker ps | grep kube-apiserver | awk '{print $1}')
   

最佳实践建议

1. 预规划网络拓扑：在部署前明确所有需要访问API Server的IP地址和域名
2. 完整证书配置：确保证书包含以下SAN：
   • 所有节点IP(包括公网和内网)
   • 负载均衡IP
   • 可能的DNS名称
   • 127.0.0.1和localhost
3. 使用内部域名：建议使用内部域名而非直接IP访问API Server
4. 证书自动更新：配置证书自动更新机制，避免证书过期问题

总结

在云环境部署Kubesphere时，正确处理API Server证书的SAN配置是关键。通过预先规划网络架构、正确配置Kubekey参数，可以避免此类证书验证问题，确保集群部署顺利进行。对于已经出现的问题，可以通过修改配置或手动更新证书的方式解决。