Apache APISIX 使用自签名证书访问 etcd 集群的配置实践

问题背景

在分布式系统中，Apache APISIX 作为高性能 API 网关，通常需要与 etcd 集群协同工作。当 etcd 集群启用了 TLS 加密通信时，APISIX 需要正确配置才能与之建立安全连接。特别是在使用自签名证书的环境中，配置不当会导致 Prometheus 插件无法获取 apisix_etcd_reachable 指标的问题。

核心问题分析

当 APISIX 尝试通过 HTTPS 连接 etcd 集群时，会进行主机名验证（hostname verification）。如果 etcd 服务器证书中的 Subject Alternative Name (SAN) 不包含 APISIX 连接时使用的主机名，就会出现 "certificate host mismatch" 错误。

解决方案详解

1. 正确生成 etcd 服务器证书

在创建 etcd 服务器证书时，必须在证书的 SAN 字段中包含所有 etcd 节点的主机名。这可以通过调整证书签名请求(CSR)文件实现：

{
    "hosts": [
        "etcd-node-1",
        "etcd-node-2",
        "etcd-node-3",
        "其他必要的主机名或IP地址"
    ],
    "其他证书配置项": "..."
}

关键点：

• 必须包含所有 etcd 节点的主机名
• 如果通过 IP 地址访问，也需要包含相应 IP
• 建议同时包含节点名和 IP 地址以提高兼容性

2. 配置 APISIX 的 etcd TLS 连接

在 APISIX 配置文件中，需要正确设置 etcd 的 TLS 参数，特别是 SNI(Server Name Indication)字段：

deployment:
  etcd:
    tls:
      cert: /pki/client.pem
      key: /pki/client-key.pem
      sni: etcd-node-1
      verify: true

配置说明：

• cert 和 key 指定客户端证书和私钥路径
• sni 指定 TLS 握手时发送的服务器名称，必须与证书中的 SAN 匹配
• verify 设置为 true 启用证书验证

3. 证书链完整性

确保 APISIX 能够验证 etcd 服务器证书，需要：

1. 将 CA 证书放置在 APISIX 可访问的路径
2. 在配置中指定 CA 证书路径：

apisix:
  ssl:
    ssl_trusted_certificate: /pki/ca.pem

技术原理深入

SNI 的作用

SNI 是 TLS 协议的扩展，允许客户端在握手初期指明要连接的服务器的名称。这对于以下场景特别重要：

• 同一 IP 托管多个 TLS 服务
• 证书验证时需要匹配特定主机名
• 多节点 etcd 集群的 TLS 连接

证书验证流程

当 APISIX 连接 etcd 时：

1. 发送 ClientHello 消息，包含 SNI 扩展
2. 服务器返回证书链
3. 客户端验证：
   • 证书是否由信任的 CA 签发
   • 证书中的 SAN 是否包含 SNI 指定的主机名
   • 证书是否在有效期内
4. 验证通过后建立安全连接

最佳实践建议

1. 证书管理：

   • 为每个环境(开发/测试/生产)使用不同的 CA
   • 定期更新证书
   • 监控证书到期时间

2. 配置验证：

   • 使用 etcdctl 先验证连接
   • 逐步增加验证严格度(先关闭验证，再逐步开启)

3. 多环境支持：

   • 使用配置模板管理不同环境的证书路径
   • 考虑使用 Kubernetes Secrets 或类似机制管理证书

4. 监控与告警：

   • 确保 Prometheus 能够正确采集 apisix_etcd_reachable 指标
   • 设置适当的告警阈值

总结

正确配置 APISIX 与 TLS 保护的 etcd 集群连接需要关注证书的 SAN 字段和 SNI 配置。通过本文介绍的方法，可以解决 Prometheus 插件无法获取 etcd 可达性指标的问题，同时建立安全的 etcd 连接。在实际生产环境中，建议结合自动化工具管理证书生命周期，并建立完善的监控机制。