Patroni连接外部etcd集群时的TLS认证问题解析

在使用Patroni管理PostgreSQL高可用集群时，与etcd分布式配置存储的集成是一个关键环节。本文将深入分析Patroni连接外部etcd v3集群时可能遇到的TLS认证问题，特别是当etcd启用了客户端TLS认证时出现的"CommonName将被忽略"错误。

问题背景

当配置Patroni使用外部etcd v3集群时，管理员可能会遇到以下典型错误信息：

ERROR: Failed to get list of machines from https://etcd-1.xx:2379/v3: <Unknown error: 'CommonName of client sending a request against gateway will be ignored and not used as expected', code: 2>

这个错误通常出现在以下场景：

• etcd集群启用了客户端TLS认证
• 客户端证书中包含CommonName字段
• Patroni尝试通过HTTPS协议连接etcd集群

根本原因分析

gRPC-gateway的作用

Patroni使用Python编写，而Python对gRPC的原生支持有限。因此，Patroni实际上是通过etcd内置的gRPC-gateway（一种代理）与etcd集群通信。这个网关负责在JSON和gRPC协议之间进行转换。

CommonName的处理机制

当etcd集群启用了客户端TLS认证且客户端证书包含CommonName时，etcd会期望使用这个CommonName作为用户名进行认证。然而，通过gRPC-gateway连接时，etcd会明确拒绝这种认证方式，认为这是一种不安全的行为，因此返回错误信息。

解决方案

方案一：移除客户端证书中的CommonName

最直接的解决方案是重新生成客户端证书，确保不包含CommonName字段。这样etcd就不会尝试使用CommonName进行认证，从而避免了错误。

方案二：使用用户名/密码认证

虽然文档说明可以同时使用TLS客户端认证和用户名/密码认证，但实际上etcd会优先使用用户名/密码认证。如果必须保留TLS客户端认证，可以：

1. 在Patroni配置中明确指定用户名和密码
2. 确保etcd集群中已创建相应用户并授予适当权限

配置示例

以下是经过验证的有效配置示例：

etcd3:
  hosts: etcd-1.xx:2379,etcd-2.xx:2379,etcd-3.xx:2379
  protocol: https
  username: pg-1-test
  password: xxxxx
  cert: /etc/postgresql/certs/tls.crt
  key: /etc/postgresql/certs/tls.key

最佳实践建议

1. 证书管理：如果必须使用TLS客户端认证，确保证书不包含CommonName字段
2. 认证方式选择：根据安全需求选择适合的认证方式，在测试环境中可以使用用户名/密码认证简化配置
3. 协议选择：明确指定protocol为https，避免自动检测带来的不确定性
4. 多节点配置：始终配置多个etcd节点地址以提高可用性

总结

理解Patroni与etcd集成的底层机制对于解决这类认证问题至关重要。通过调整证书内容或选择合适的认证方式，可以有效解决"CommonName将被忽略"的错误。在实际生产环境中，建议根据安全策略选择最合适的认证方案，并确保所有组件配置一致。