配置自定义 CA 证书

当你的 connectors 需要访问那些呈现由内部或私有 Certificate Authority (CA) 签名的 TLS 证书的工具时,你可以配置平台信任这些 CA,而无需完全禁用证书验证。

本指南涵盖以下内容:

  • 启用自定义 CA 证书功能开关
  • 配置适用于所有 connectors 的全局 CA 证书
  • 配置按 connector 生效的 CA 证书
  • 通过 CACertReady 条件验证配置

前提条件

  • 一个正在运行的 Connectors 部署(controller、proxy 以及可选扩展)。
  • 对运行 Connectors 组件的系统命名空间拥有集群管理员访问权限(通常为 connectors-system)。
  • 一个或多个 PEM 编码的 CA 证书,这些证书用于签署你的工具的服务器证书。

第 1 步:启用功能开关

自定义 CA 证书支持由 enable-custom-ca-certs 功能开关控制,默认禁用,以保持向后兼容性。

将该开关以声明式方式设置到集群单例 ConnectorsConfig 上,这样该值在 reconciliation 后仍可保留。不要直接编辑受管理的 connectors-config ConfigMap——它会在下一次 reconcile 时从 ConnectorsConfig 重新同步回来。

kubectl patch connectorsconfig connectors-config -n connectors-operator --type merge \
  -p '{"spec":{"components":{"core":{"spec":{"featureFlags":{"enable-custom-ca-certs":"true"}}}}}}'

或者以交互方式编辑 ConnectorsConfig:

apiVersion: operator.connectors.alauda.io/v1alpha1
kind: ConnectorsConfig
metadata:
  name: connectors-config
spec:
  components:
    core:
      spec:
        featureFlags:
          enable-custom-ca-certs: "true"

完整的更新语法请参见 Feature Flags。

切换功能开关会立即生效——该设置会在请求时读取。当该开关为 false 时,不会向 Connector 状态中添加 CACertReady 条件,并且组件会保留旧版 TLS 行为以实现向后兼容。

第 2 步:配置全局 CA 证书

全局 CA 证书适用于集群中的所有 connectors。它们会通过为系统命名空间中的 Secret 添加标签自动发现。

在系统命名空间中创建一个 Secret,添加标签 connectors.cpaas.io/ca-cert: "true",并在 data 键中放入一个或多个 PEM 编码证书。仅会加载以 .crt 或 .pem 结尾的键,或者其值中包含 PEM 头的键——其他键会被忽略。

apiVersion: v1
kind: Secret
metadata:
  name: my-internal-ca
  namespace: connectors-system
  labels:
    connectors.cpaas.io/ca-cert: "true"
type: Opaque
stringData:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    MIIDazCCAlOgAwIBAgIUF+...
    -----END CERTIFICATE-----

使用以下命令应用:

kubectl apply -f my-internal-ca.yaml

注意: 更新带全局标签的 Secret 后,reverse proxy 可能最多需要 5 分钟才能获取新的 CA 池——connector reverse-proxy transports 按 connector 缓存,TTL 为 5 分钟。若要立即刷新,请重启 connectors-proxy Deployment。

你可以创建多个带标签的 Secret——它们的所有证书都会聚合到全局 CA 池中。添加或移除带标签的 Secret 会触发受影响 connectors 的自动重新 reconciliation。

第 3 步:配置按 Connector 生效的 CA 证书(可选)

对于需要特定 CA、且不与其他 connectors 共享的工具,你可以直接在 Connector 资源中引用一个 CA Secret。该 Secret 必须位于与 Connector 相同的命名空间中(不允许跨命名空间引用)。

首先,在 connector 的命名空间中创建 CA Secret:

apiVersion: v1
kind: Secret
metadata:
  name: my-tool-ca
  namespace: my-namespace
type: Opaque
stringData:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    MIIDazCCAlOgAwIBAgIUF+...
    -----END CERTIFICATE-----

然后在 Connector 中引用它:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: my-tool-connector
  namespace: my-namespace
spec:
  connectorClassName: my-tool
  address: https://my-tool.internal.example.com
  auth:
    name: bearerToken
    secretRef:
      name: my-tool-credentials
  caCertSecretRef:
    name: my-tool-ca

按 connector 生效的 CA 是追加式的——它会附加到全局 CA 池中(system CAs + 全局带标签的 Secrets + 按 connector 的 Secret)。

第 4 步:验证配置

检查 Connector 状态中的 CACertReady 条件:

kubectl -n my-namespace get connector my-tool-connector \
  -o jsonpath='{.status.conditions[?(@.type=="CACertReady")]}'

有效配置的预期输出:

{
  "type": "CACertReady",
  "status": "True",
  "reason": "Valid",
  "message": "CA certificate loaded from secret \"my-tool-ca\"",
  "severity": "Info"
}

CACertReady 条件是信息性的——它的状态不会影响顶层 Ready 条件。这意味着配置错误的 CA Secret 会显示为警告,但不会阻塞 connector reconciliation。完整状态参考请参见 Connector concepts 页面中的 CA Certificate Status。

如果 CA Secret 缺失或包含无效的 PEM 数据,controller 会在 Connector 对象上发出 Kubernetes Warning Event。使用以下命令查看事件:

kubectl -n my-namespace describe connector my-tool-connector

常见问题

Connector 状态显示 CACertReady=False, reason=SecretNotFound

spec.caCertSecretRef.name 中指定的 Secret 不存在于 connector 的命名空间中。请验证 Secret 名称和命名空间:

kubectl -n my-namespace get secret my-tool-ca

Connector 状态显示 CACertReady=False, reason=InvalidPEM

Secret 存在,但其数据中不包含有效的 PEM 编码证书。请验证 Secret 内容:

kubectl -n my-namespace get secret my-tool-ca -o jsonpath='{.data.ca\.crt}' | base64 -d

输出应以 -----BEGIN CERTIFICATE----- 开头,并以 -----END CERTIFICATE----- 结尾。

启用该开关后仍未出现 CACertReady 条件

请确保在切换开关后,已经重启了 controller、proxy 和 API 部署。CA 池会在组件启动时加载。

kubectl -n connectors-system rollout restart deployment connectors-proxy connectors-controller-manager connectors-api

配置 CA 后工具仍拒绝连接

CA 池采用追加式分层构建:system CAs + 全局带标签的 Secrets + 按 connector 的 Secret。请确保签署工具服务器证书的 CA 至少存在于其中一层。你可以通过列出带标签的 Secrets 来验证全局池是否已填充:

kubectl -n connectors-system get secret -l connectors.cpaas.io/ca-cert=true

刚修改 CA Secret 后连接仍失败

reverse-proxy 会以 5 分钟 TTL 缓存 CA 池。如果你刚更新了全局带标签的 Secret 或按 connector 的 Secret,请等待 TTL 过期,或重启 connectors-proxy 以立即获取新的池:

kubectl -n connectors-system rollout restart deployment connectors-proxy

更多内容