Hetzner-k3s 项目中使用外部 PostgreSQL 作为 K3s 数据存储的实践指南

背景介绍

在 Kubernetes 集群部署中，数据存储的选择至关重要。Hetzner-k3s 是一个用于在 Hetzner 云平台上快速部署 K3s 集群的工具，默认使用 etcd 作为数据存储。然而，在某些场景下，用户可能希望使用外部 PostgreSQL 数据库作为替代方案。

配置外部 PostgreSQL 数据存储

要在 Hetzner-k3s 中使用 PostgreSQL 作为 K3s 的数据存储，需要在配置文件中进行以下设置：

datastore:
  mode: external
  external_datastore_endpoint: postgresql://用户名:密码@数据库私有IP:5432/数据库名

关键点说明：

1. mode 必须明确设置为 external
2. 连接字符串必须使用 postgresql:// 前缀而非 postgres://
3. 数据库服务器必须预先创建好，并确保网络连通性

常见问题与解决方案

1. 连接超时问题

当配置了 IPv6 网络但未正确设置 NAT 网关时，节点可能无法访问互联网，导致安装过程失败。解决方案：

• 确保从运行 hetzner-k3s 命令的机器可以访问私有网络
• 或者启用 IPv4 接口（会产生额外费用）
• 或者正确配置 NAT 网关实现互联网访问

2. 数据库初始化问题

PostgreSQL 数据库需要预先创建，但表结构不需要手动创建 - K3s 会在首次连接时自动初始化所需的表结构。如果发现数据库为空，可能是连接配置有误或权限不足。

3. 上下文不存在错误

当出现 error: no context exists with the name: "k3s-cluster-master1" 错误时，通常表示控制平面未能成功启动。这可能由以下原因导致：

• 数据库连接字符串格式错误
• 网络连接问题
• 数据库权限不足

最佳实践建议

1. 网络规划：

   • 确保所有节点和数据库服务器位于同一私有网络
   • 测试节点到数据库的网络连通性
   • 考虑使用 Hetzner 私有网络功能简化网络配置

2. 数据库准备：

   • 预先创建数据库用户并授予适当权限
   • 测试从节点到数据库的连接
   • 考虑数据库高可用方案

3. 配置验证：

   • 使用 psql 命令行工具验证连接字符串
   • 检查数据库日志以排查连接问题
   • 逐步测试配置变更

注意事项

1. 数据存储类型一旦确定，就不能在集群创建后更改。如需更换存储类型，必须重建集群。

2. 使用外部数据存储时，确保数据库的性能和可靠性满足生产需求，特别是对于关键业务集群。

3. 定期备份数据库，防止数据丢失。

通过以上配置和注意事项，用户可以成功在 Hetzner-k3s 中使用 PostgreSQL 作为 K3s 的数据存储，满足特定场景下的需求。