配置自定义 CA 证书
当你的 connectors 需要访问那些呈现由内部或私有 Certificate Authority (CA) 签名的 TLS 证书的工具时,你可以配置平台信任这些 CA,而无需完全禁用证书验证。
本指南涵盖以下内容:
- 启用自定义 CA 证书功能开关
- 配置适用于所有 connectors 的全局 CA 证书
- 配置按 connector 生效的 CA 证书
- 通过
CACertReady条件验证配置
目录
前提条件第 1 步:启用功能开关第 2 步:配置全局 CA 证书第 3 步:配置按 Connector 生效的 CA 证书(可选)第 4 步:验证配置常见问题Connector 状态显示CACertReady=False, reason=SecretNotFoundConnector 状态显示 CACertReady=False, reason=InvalidPEM启用该开关后仍未出现 CACertReady 条件配置 CA 后工具仍拒绝连接刚修改 CA Secret 后连接仍失败更多内容前提条件
- 一个正在运行的 Connectors 部署(controller、proxy 以及可选扩展)。
- 对运行 Connectors 组件的系统命名空间拥有集群管理员访问权限(通常为
connectors-system)。 - 一个或多个 PEM 编码的 CA 证书,这些证书用于签署你的工具的服务器证书。
第 1 步:启用功能开关
自定义 CA 证书支持由 enable-custom-ca-certs 功能开关控制,默认禁用,以保持向后兼容性。
将该开关以声明式方式设置到集群单例 ConnectorsConfig 上,这样该值在 reconciliation 后仍可保留。不要直接编辑受管理的 connectors-config ConfigMap——它会在下一次 reconcile 时从 ConnectorsConfig 重新同步回来。
或者以交互方式编辑 ConnectorsConfig:
完整的更新语法请参见 Feature Flags。
切换功能开关会立即生效——该设置会在请求时读取。当该开关为 false 时,不会向 Connector 状态中添加 CACertReady 条件,并且组件会保留旧版 TLS 行为以实现向后兼容。
第 2 步:配置全局 CA 证书
全局 CA 证书适用于集群中的所有 connectors。它们会通过为系统命名空间中的 Secret 添加标签自动发现。
在系统命名空间中创建一个 Secret,添加标签 connectors.cpaas.io/ca-cert: "true",并在 data 键中放入一个或多个 PEM 编码证书。仅会加载以 .crt 或 .pem 结尾的键,或者其值中包含 PEM 头的键——其他键会被忽略。
使用以下命令应用:
注意: 更新带全局标签的 Secret 后,reverse proxy 可能最多需要 5 分钟才能获取新的 CA 池——connector reverse-proxy transports 按 connector 缓存,TTL 为 5 分钟。若要立即刷新,请重启
connectors-proxyDeployment。
你可以创建多个带标签的 Secret——它们的所有证书都会聚合到全局 CA 池中。添加或移除带标签的 Secret 会触发受影响 connectors 的自动重新 reconciliation。
第 3 步:配置按 Connector 生效的 CA 证书(可选)
对于需要特定 CA、且不与其他 connectors 共享的工具,你可以直接在 Connector 资源中引用一个 CA Secret。该 Secret 必须位于与 Connector 相同的命名空间中(不允许跨命名空间引用)。
首先,在 connector 的命名空间中创建 CA Secret:
然后在 Connector 中引用它:
按 connector 生效的 CA 是追加式的——它会附加到全局 CA 池中(system CAs + 全局带标签的 Secrets + 按 connector 的 Secret)。
第 4 步:验证配置
检查 Connector 状态中的 CACertReady 条件:
有效配置的预期输出:
CACertReady 条件是信息性的——它的状态不会影响顶层 Ready 条件。这意味着配置错误的 CA Secret 会显示为警告,但不会阻塞 connector reconciliation。完整状态参考请参见 Connector concepts 页面中的 CA Certificate Status。
如果 CA Secret 缺失或包含无效的 PEM 数据,controller 会在 Connector 对象上发出 Kubernetes Warning Event。使用以下命令查看事件:
常见问题
Connector 状态显示 CACertReady=False, reason=SecretNotFound
spec.caCertSecretRef.name 中指定的 Secret 不存在于 connector 的命名空间中。请验证 Secret 名称和命名空间:
Connector 状态显示 CACertReady=False, reason=InvalidPEM
Secret 存在,但其数据中不包含有效的 PEM 编码证书。请验证 Secret 内容:
输出应以 -----BEGIN CERTIFICATE----- 开头,并以 -----END CERTIFICATE----- 结尾。
启用该开关后仍未出现 CACertReady 条件
请确保在切换开关后,已经重启了 controller、proxy 和 API 部署。CA 池会在组件启动时加载。
配置 CA 后工具仍拒绝连接
CA 池采用追加式分层构建:system CAs + 全局带标签的 Secrets + 按 connector 的 Secret。请确保签署工具服务器证书的 CA 至少存在于其中一层。你可以通过列出带标签的 Secrets 来验证全局池是否已填充:
刚修改 CA Secret 后连接仍失败
reverse-proxy 会以 5 分钟 TTL 缓存 CA 池。如果你刚更新了全局带标签的 Secret 或按 connector 的 Secret,请等待 TTL 过期,或重启 connectors-proxy 以立即获取新的池: