#配置自定义 CA 证书

当你的连接器需要访问那些提供由内部或私有证书颁发机构（CA）签名的 TLS 证书的工具时，你可以配置平台信任这些 CA，而无需完全禁用证书验证。

本指南涵盖以下内容：

• 启用自定义 CA 证书功能开关
• 配置适用于所有连接器的全局 CA 证书
• 配置按连接器生效的 CA 证书
• 通过 CACertReady condition 验证配置

#前提条件

• 正在运行的 Connectors 部署（controller、proxy 和可选的 extensions）。
• 对 Connectors 组件运行所在的系统 namespace 具有 cluster admin 访问权限（通常是 connectors-system）。
• 一个或多个 PEM 编码的 CA 证书，这些证书用于签署你的工具的 server 证书。

#第 1 步：启用功能开关

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

编辑系统 namespace 中的 connectors-config ConfigMap，并将该开关设置为 true：

apiVersion: v1
kind: ConfigMap
metadata:
  name: connectors-config
  namespace: connectors-system
  labels:
    group: connectors.alauda.io
data:
  enable-custom-ca-certs: "true"

使用以下命令应用：

kubectl -n connectors-system patch configmap connectors-config \
  --type merge -p '{"data":{"enable-custom-ca-certs":"true"}}'

切换功能开关会立即生效——该设置会在请求时被读取。当该开关为 false 时，CACertReady condition 不会添加到 Connector status 中，组件会保留旧版 TLS 行为以兼容旧版本。

#第 2 步：配置全局 CA 证书

全局 CA 证书适用于集群中的所有连接器。系统会通过为系统 namespace 中的 Secret 添加标签自动发现这些证书。

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

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 pool——连接器 reverse-proxy transports 会按连接器缓存，TTL 为 5 分钟。若要立即刷新，请重启 connectors-proxy Deployment。

你可以创建多个带标签的 Secret——它们包含的所有证书都会聚合到全局 CA pool 中。添加或删除带标签的 Secret 会触发受影响连接器的自动重新协调。

#第 3 步：配置按连接器生效的 CA 证书（可选）

对于需要使用不与其他连接器共享的特定 CA 的工具，你可以从 Connector 资源本身引用一个 CA Secret。该 Secret 必须位于 Connector 的相同 namespace 中（不允许跨 namespace 引用）。

首先，在连接器的 namespace 中创建 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

按连接器生效的 CA 是附加式的——它会被追加到全局 CA pool 中（system CAs + 全局带标签的 Secrets + 按连接器的 Secret）。

#第 4 步：验证配置

检查 Connector status 上的 CACertReady condition：

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 condition 仅用于信息提示——其状态不会影响顶层 Ready condition。这意味着，配置错误的 CA Secret 会以警告形式显现，但不会阻止连接器重新协调。有关完整状态参考，请参阅 Connector 概念页面中的 CA Certificate Status。

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

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

#常见问题

#Connector status 显示 CACertReady=False, reason=SecretNotFound

spec.caCertSecretRef.name 中指定的 Secret 不存在于连接器的 namespace 中。请验证 Secret 名称和 namespace：

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

#Connector status 显示 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 condition

请确保在切换功能开关后已重启 controller、proxy 和 API deployments。CA pool 会在组件启动时加载。

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

#配置 CA 后工具仍然拒绝连接

CA pool 以附加层方式构建：system CAs + 全局带标签的 Secrets + 按连接器的 Secret。请确保为工具 server 证书签名的 CA 至少存在于这些层中的一个。你可以通过列出带标签的 Secret 来验证全局 pool 是否已填充：

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

#刚更改 CA Secret 后连接仍然失败

reverse-proxy 会将 CA pool 缓存 5 分钟。如果你刚刚更新了全局带标签的 Secret 或按连接器的 Secret，请等待 TTL 过期，或者重启 connectors-proxy 以立即获取新的 pool：

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

#更多内容

• Connector concepts: CA Certificates
• Connector status conditions reference