Kubernetes-Hetzner集群中自定义域名与API证书的配置实践

问题背景

在使用Kubernetes-Hetzner（简称Kube-Hetzner）Terraform模块部署集群时，许多用户会遇到一个典型场景：当为已部署的集群配置自定义域名后（如cp.example.com），虽然kubeconfig文件正确指向了新域名，但kubectl连接时会出现证书验证失败的错误。错误信息显示API服务器的TLS证书不包含用户配置的自定义域名。

技术原理分析

Kubernetes API证书机制

Kubernetes API服务器在启动时会自动生成TLS证书，该证书包含一组Subject Alternative Names(SANs)。默认情况下，这些SANs包括：

• 控制平面节点的主机名（如control-plane-fsn1-rfa）
• 内部Kubernetes服务域名（kubernetes、kubernetes.default等）
• 本地地址（localhost）
• 节点IP地址

Kube-Hetzner的证书管理

Kube-Hetzner模块通过Terraform配置管理这些证书参数，但遵循"显式优于隐式"的原则：

1. kubeconfig_server_address参数：仅用于配置kubeconfig文件中的服务器地址
2. additional_tls_sans参数：专门用于扩展API证书的SAN列表

这两个参数在设计上是解耦的，这是为了避免在复杂网络环境下产生意外的证书配置。

典型问题场景

当用户完成以下操作时会出现证书错误：

1. 为已有集群配置自定义域名：

   kubeconfig_server_address = "cp.example.com"
   

2. 但未更新证书SAN列表：

   # 缺少对应的additional_tls_sans配置
   

此时kubectl会报错：

x509: certificate is valid for control-plane-node1, kubernetes, ..., not cp.example.com

解决方案

正确的配置方式是在additional_tls_sans中显式声明所有需要包含在证书中的自定义域名：

kubeconfig_server_address = "cp.example.com"
additional_tls_sans       = ["cp.example.com"]

配置生效机制

1. 初始部署：在集群创建时，Terraform会将additional_tls_sans中的域名写入API服务器证书
2. 已有集群更新：需要手动触发证书轮换或重建集群

最佳实践建议

1. 域名规划阶段：

   • 提前规划好API服务器的访问域名
   • 同时配置DNS记录和证书参数

2. 生产环境建议：

   kubeconfig_server_address = "k8s-api.example.com"
   additional_tls_sans = [
     "k8s-api.example.com",
     "k8s-api.internal.example.com",
     "backup-api.example.com"  # 备用访问域名
   ]
   

3. 多环境管理：

   • 为开发、测试、生产环境使用不同的子域名
   • 通过变量统一管理这些域名

技术思考

这种设计虽然增加了配置步骤，但带来了以下优势：

1. 明确性：清楚地知道哪些域名被包含在证书中
2. 灵活性：可以配置与kubeconfig不同的额外访问域名
3. 安全性：避免自动包含可能不安全的临时域名

对于自动化要求高的场景，可以通过封装模块或使用CI/CD流程自动保持这两个参数的同步。

总结

Kube-Hetzner项目通过分离kubeconfig地址配置和证书SAN配置，提供了灵活而明确的集群访问管理方式。理解这一设计理念后，用户可以更自信地管理生产环境中的Kubernetes集群访问安全。记住：任何自定义API访问域名都需要同时在DNS记录和证书SAN列表中正确配置，这是确保集群安全可用的关键。