Kube-Hetzner项目中kubeconfig服务器地址与TLS证书的配置问题分析

问题背景

在使用Kube-Hetzner项目部署Kubernetes集群时，当用户尝试通过自定义域名访问集群时，可能会遇到TLS证书验证失败的问题。具体表现为kubectl工具无法连接集群，错误信息显示证书不包含用户指定的域名。

问题现象

用户配置了kubeconfig_server_address参数指向自定义域名后，kubectl返回如下错误：

x509: certificate is valid for ctrl1-kam, ctrl2-grm, ctrl3-zof, kubernetes, kubernetes.default, kubernetes.default.svc, kubernetes.default.svc.cluster.local, localhost, not my.domain-name.net

这表明Kubernetes API服务器生成的TLS证书中没有包含用户指定的域名，导致TLS握手失败。

技术原理

Kubernetes API服务器使用TLS证书来保护通信安全。证书中包含一个Subject Alternative Name(SAN)列表，只有列表中包含的域名或IP地址才能通过证书验证。

在K3s(轻量级Kubernetes发行版)中，可以通过--tls-san参数来指定额外的SAN条目。Kube-Hetzner项目通过Terraform配置这些参数。

解决方案

要解决这个问题，需要同时配置两个参数：

1. additional_tls_sans - 向K3s服务器证书添加额外的SAN条目
2. kubeconfig_server_address - 设置kubeconfig文件中使用的服务器地址

正确的配置示例如下：

additional_tls_sans       = ["cp.cluster.my.org"] 
kubeconfig_server_address = "cp.cluster.my.org"

配置建议

1. 确保两个参数使用相同的域名值
2. 域名解析应在集群创建前配置完成
3. 对于生产环境，建议使用权威CA签发的证书而非自签名证书
4. 多节点集群应考虑负载均衡器配置

实现细节

在Kube-Hetzner项目中，这些配置通过以下方式实现：

• additional_tls_sans参数会传递给K3s的--tls-san选项
• kubeconfig_server_address参数用于生成kubeconfig文件中的服务器地址
• 控制平面节点初始化时会将这些SAN信息写入API服务器证书

总结

正确配置Kubernetes集群的TLS证书是确保安全访问的关键。在Kube-Hetzner项目中，必须同时设置additional_tls_sans和kubeconfig_server_address参数才能通过自定义域名访问集群。理解这一机制有助于管理员更好地管理和维护集群的安全配置。