Terraform-HCloud-Kube-Hetzner项目中的Cloud-init故障排查指南

问题背景

在使用Terraform-HCloud-Kube-Hetzner项目部署Kubernetes集群时，用户遇到了cloud-init服务启动失败的问题。该问题表现为terraform部署过程中出现错误，导致集群初始化无法完成。本文将详细分析问题原因并提供解决方案。

故障现象

主要错误表现为：

1. cloud-init服务启动失败，日志显示YAML解析错误："unacceptable character #xdcfc"
2. terraform执行过程中报错："/etc/cloud/rename_interface.sh: No such file or directory"
3. 部分节点可能进入紧急模式

根本原因分析

经过深入排查，发现问题的根源主要来自以下几个方面：

1. SSH密钥注释中的非ASCII字符：在Hetzner云平台和本地SSH密钥的注释中使用了德文字符"ü"等非ASCII字符，导致cloud-init解析YAML配置时失败。

2. SSH known_hosts缓存问题：当反复销毁和重建集群时，Hetzner可能分配相同的IP地址给新实例，但密钥指纹已改变，导致SSH连接因"man-in-the-middle"警告而失败。

3. SELinux模块安装失败：在某些情况下，k3s的SELinux策略模块安装失败，导致控制平面节点初始化不完整。

详细解决方案

1. 处理SSH密钥注释问题

最佳实践：

• 避免在SSH密钥注释中使用任何非ASCII字符（如德文字符ü, ö, ä等）
• 检查Hetzner云平台中存储的SSH密钥描述信息，确保只使用ASCII字符
• 本地SSH密钥的注释也应遵循相同原则

验证方法：

# 查看本地SSH公钥注释
cat ~/.ssh/id_rsa.pub

# 检查Hetzner云平台中的SSH密钥描述
hcloud ssh-key list

2. 管理SSH known_hosts文件

解决方案：

• 在重新部署集群前，清理known_hosts文件中旧的记录：

ssh-keygen -f "/home/user/.ssh/known_hosts" -R "服务器IP地址"

自动化建议： 对于经常重建集群的用户，可以考虑在terraform部署脚本中加入自动清理known_hosts的步骤，或者在SSH配置中为Hetzner的IP范围禁用严格的主机密钥检查（仅限测试环境）。

3. 解决SELinux模块问题

临时解决方案： 如果遇到k3s的SELinux策略安装失败，可以尝试：

# 手动安装SELinux策略
sudo semodule -i /usr/share/selinux/packages/k3s.pp

# 或者临时禁用SELinux（不推荐用于生产环境）
sudo setenforce 0

长期解决方案： 确保使用最新版本的MicroOS镜像，并检查k3s安装包的完整性。

4. 非标准SSH端口配置

注意事项：

• 如果使用非标准SSH端口，必须确保：
  • 在terraform配置中正确定义了端口号
  • Hetzner防火墙规则允许该端口的入站连接
  • 本地SSH配置正确指定端口

推荐配置：

ssh_port = 2222  # 在kube.tf中定义

extra_firewall_rules = [
  {
    description = "Custom SSH port"
    direction  = "in"
    protocol   = "tcp"
    port       = "2222"
    source_ips = ["0.0.0.0/0", "::/0"]
  }
]

预防措施

1. 标准化SSH密钥管理：

   • 为Kubernetes集群创建专用SSH密钥对
   • 使用简单、无特殊字符的描述
   • 考虑使用SSH密钥管理工具

2. 环境清理脚本： 创建部署前的清理脚本，自动处理known_hosts和临时文件。

3. 镜像管理：

   • 定期更新Packer构建的MicroOS镜像
   • 验证镜像中的关键组件完整性

4. 日志收集： 配置集中式日志收集，便于分析部署过程中的问题。

总结

Terraform-HCloud-Kube-Hetzner项目在部署过程中遇到的cloud-init故障通常与环境和配置细节密切相关。通过规范SSH密钥管理、正确处理主机密钥缓存以及确保系统组件完整性，可以显著提高部署成功率。对于生产环境，建议建立标准化的部署前检查清单，并在测试环境中验证所有配置变更。

记住，基础设施即代码(IaC)环境中的小细节（如特殊字符）往往会导致意想不到的问题，保持配置简洁和标准化是避免这类问题的关键。