连接器

概述 Connector 地址基本 URL 格式带路径前缀的 URL Connector 地址扩展 Connector 参数认证信息配置认证信息可选认证认证检查自定义 CA 证书每个 Connector 的 CA 证书引用全局 CA 证书代理地址状态信息示例使用基本认证的 Git Connector 无认证的 Git Connector

概述

Connector 是一个命名空间级资源，用于定义工具与平台之间的连接配置。它包括：

工具的访问地址
工具的认证信息
工具的状态信息

例如，以下定义展示了一个 Git 类型的 connector：

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github
  namespace: default
spec:
  connectorClassName: git  ##  Specify the connector type as git, this ConnectorClass must exist
  address: "https://github.com"  ##  Access address of the tool
  auth:
    name: basicAuth
    secretRef:  ##  Reference to authentication information
      name: github-secret

Connector 地址

address 字段指定 Connector 将集成的目标工具 URL 端点。它既支持根 URL，也支持带路径前缀的 URL。

基本 URL 格式

对于可通过根域访问的工具：

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github
spec:
  connectorClassName: git
  address: "https://github.com"
  # ...

带路径前缀的 URL

对于部署在反向代理后面或通过特定路径访问的工具：

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-gitlab
spec:
  connectorClassName: git
  address: "https://internal-tool.com/gitlab"
  # ...

注意

基于 http 的认证探针和存活探针不会针对路径前缀执行。如果您希望针对路径前缀执行探针，可以使用认证检查表达式和存活检查表达式。

有关更多信息，请参阅存活探针和认证探针。

Connector 地址扩展

spec.addressExtensions 定义了 Connector 实例上的其他命名地址。可用名称来自 ConnectorClass 地址扩展。

spec.addressExtensions[].name：扩展名称。在一个 Connector 中必须唯一。
spec.addressExtensions[].value：扩展值。必须是非空的 http/https URL。

准入校验同时强制执行语法和 class 约束：

必须提供 ConnectorClass 所要求的扩展（没有 default）。
Connector 不能提供 ConnectorClass 中未声明的扩展名称。
扩展名称在 Connector 中必须唯一。
扩展值不得与 spec.address 重复。

运行时行为：

Connectors API 可以通过扩展名称或 x-openapi-address 直接 URL 选择后端地址。
Connectors Proxy 可以将 spec.address 和 spec.addressExtensions[*].value 视为凭证注入目标地址。

示例

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: github-demo
spec:
  connectorClassName: github
  address: "https://github.com"
  addressExtensions:
    - name: api
      value: "https://api.github.com"

Connector 参数

Connector 参数使您能够向 Connector 实例传递额外的配置信息。这些参数首先在 ConnectorClass 规范中定义，然后可以在创建单个 Connector 资源时进行配置。

您可以使用 spec.params 字段在 Connector 中指定参数值。

spec.params[].name：参数名称，必须与对应 ConnectorClass 中定义的参数名称匹配。
spec.params[].value：参数值。值类型必须与 ConnectorClass 中定义的参数类型匹配。当前仅支持 string 类型。

如果某个参数在 ConnectorClass 中定义了默认值，则在创建 Connector 时可以省略该参数，系统将使用默认值。

有关在 ConnectorClass 中定义参数的更多信息，请参阅 ConnectorClass 参数。

示例

以下示例演示了一个配置了 sslVerify 参数的 Connector：

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-gitlab
spec:
  connectorClassName: git-example
  address: "https://private-gitlab.example.com"
  params:
    - name: sslVerify
      value: "false"
---
apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: git-example
spec:
  # ...
  params:
    - name: sslVerify
      type: string
      default: "true"

认证信息

认证信息定义了访问该工具所需的凭证。根据工具类型的不同，可以配置不同的认证方法。该认证方法在 ConnectorClass 中定义。有关更多细节，请参阅 ConnectorClass 中认证信息的说明。

配置认证信息

认证信息按以下方式配置：

根据 ConnectorClass 定义指定所使用的认证类型名称。
创建一个包含凭证的 Secret。
通过 spec.auth.secretRef 在 Connector 中引用该 Secret。
指定认证检查期间所需的参数信息。

例如，要配置基本认证：

##  Create a Secret containing username and password
apiVersion: v1
kind: Secret
metadata:
  name: github-secret
  namespace: default
type: kubernetes.io/basic-auth
data:
  username: dXNlcm5hbWU=  ##  Base64 encoded username
  password: cGFzc3dvcmQ=  ##  Base64 encoded password
---
##  Reference the Secret in the Connector
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github
spec:
  connectorClassName: git
  address: "https://github.com"
  auth:
    name: basic-auth
    secretRef:
      name: github-secret
      namespace: default

可选认证

某些工具支持无需认证即可访问。在这种情况下，可以省略 spec.auth.secretRef。

例如，访问一个公开的 Git 仓库：

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-public
spec:
  connectorClassName: git
  address: "https://github.com"
  auth:
    name: basic-auth ##  Authentication for git connectorclass basic-auth is optional

认证检查

Connector 支持验证认证信息的有效性。检查的配置通过 spec.auth.params 设置，其中包含认证检查所需的参数。

例如，要检查对 Git 仓库的访问权限：

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github
spec:
  connectorClassName: git
  address: "https://github.com"
  auth:
    name: basic-auth
    secretRef:
      name: github-secret
      namespace: default
    params:
    - name: repository  ##  Specify the repository to be checked
      value: "org/repo.git"

请注意，一旦 ConnectorClass 指定了认证检测参数，connector 中的参数就必须提供；即使创建 Connector 时没有指定 secret 信息，也必须传入 spec.auth.params。

自定义 CA 证书

当工具的 TLS 证书由内部或私有 Certificate Authority (CA) 签名时，可以配置 Connector 平台信任这些 CA，而无需禁用证书校验。

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

当该开关启用时，平台会构建一个由三层叠加组成的 CA 池：

系统默认 CA 池 — 容器镜像中内置的操作系统级信任存储。
全局自定义 CA 证书 — connectors-system 命名空间中带有 connectors.cpaas.io/ca-cert: "true" 标签的 Secret。多个 Secret 会被聚合。
每个 Connector 的 CA 证书 — 通过 Connector 上的 spec.caCertSecretRef.name 引用的可选 Secret。该 Secret 必须位于与 Connector 相同的命名空间中。

构建出的 CA 池用于：

控制器对工具执行存活和认证探针
proxy 组件通过 proxy 连接工具
控制器执行 ConnectorClass 可访问性检查
适用时用于扩展代理（OCI、Harbor、Git HTTPS 等）

每个 Connector 的 CA 证书引用

要为单个 Connector 信任特定 CA，请设置 spec.caCertSecretRef.name：

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

引用的 Secret 必须至少包含一个 PEM 编码的 CA 证书。只有以 .crt 或 .pem 结尾的键，或包含 PEM 头部的值，才会被加载到池中——其他键（例如误放在同一个 Secret 中的 token 或 password）会被忽略。

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

全局 CA 证书

集群管理员可以通过在 connectors-system 命名空间中创建带有标签 connectors.cpaas.io/ca-cert: "true" 的 Secret，为所有 connector 配置 CA 证书。平台会自动发现所有匹配的 Secret，并将其证书聚合到全局 CA 池中。

添加或删除带标签的 Secret 会触发受影响 Connector 的自动重新调和——在启用该功能开关后，全球 CA 变更无需重启组件。

分步说明请参阅如何配置自定义 CA 证书。

代理地址

如果 Connector 指向的 ConnectorClass 配置了 proxy 能力，系统将为每个 Connector 分配一个代理地址。

客户端可以使用该代理地址以无凭证方式访问工具。

代理地址的默认格式为 http://c-{connector-name}.{namespace}.svc.cluster.local，可通过 status.proxy 获取。

例如，以下示例描述了一个带代理地址的 connector：

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: harbor
  namespace: default
spec:
  address: https://example.com
status:
 proxy:
    httpAddress:
      url: http://c-harbor.default.svc.cluster.local

当 ConnectorClass 配置的 proxy resolver 类型为 path 时，代理地址格式为 http://c-{connector-name}.{namespace}.svc.cluster.local/namespaces/{namespace}/connectors/{connector-name}，其中 {path} 为 Connector 的路径。

例如，以下示例描述了一个带代理地址的 connector：

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: harbor
  namespace: default
spec:
  address: https://example.com
status:
 proxy:
    httpAddress:
      url: http://c-harbor.default.svc.cluster.local/namespaces/default/connectors/harbor

状态信息

Connector 的状态信息记录在 status 字段中，包含代理地址、API 地址和条件：

status.conditions：Connector 的条件。
status.proxy：Connector 的代理地址。
status.api：Connector 的 API 地址。

代理地址

proxy 字段包含 Connector 的代理地址。

status.proxy.httpAddress.url：当前 Connector 的 HTTP 代理地址。

您可以将该地址与现有工具客户端一起使用，以在集群内无凭证访问该工具。更多信息请参阅 Connector Proxy。

如果 ConnectorClass 没有配置 proxy 能力，则 status.proxy 字段为空。

API 地址

api 字段包含 Connector 的 API 地址。

status.api.path：当前 Connector 的 API 相对路径（相对于集群 ingress 访问入口）。

您可以在集群外使用该路径，通过当前 Connector 访问工具的原始 API。更多信息请参阅 Connector API。

条件

conditions 类型包括：

ConnectorClassReady：表示 connector 类型是否正确。
SecretReady：表示认证信息是否正确配置。
LivenessReady：表示工具是否可访问。
AuthReady：表示认证信息是否有效。
ProxyServiceReady：表示当前 Connector 的代理地址是否成功分配。
CACertReady：信息性条件——表示自定义 CA 证书配置的状态。该条件不会影响顶层 Ready 条件。
Ready：表示整体状态。

SecretReady 条件

表示 Connector 的 secret 状态信息。

状态	原因	描述
True	SecretOptional	ConnectorClass 将认证信息标记为可选，且当前 Connector 未配置认证信息
True		已配置 Secret 且 Secret 存在
False		已配置 Secret，但在检查 Secret 是否存在时发生错误
Unknown		正在检查已配置的 Secret 是否正常

AuthReady 条件

表示 Connector 的认证状态信息。

状态	原因	描述
True	NonAuthProbe	ConnectorClass 未指定 Auth Probe 信息
True		凭证检查有效
False		凭证检查失败
Unknown		凭证检查进行中

LivenessReady 条件

表示 Connector 的存活状态信息。

状态	原因	描述
True	NonLivenessProbe	ConnectorClass 未指定 Liveness Probe 信息
True		工具访问正常
False		工具访问异常
Unknown		工具访问检查进行中

ProxyServiceReady 条件

表示 Connector 的 proxy service 状态信息。

状态	原因	描述
True	NonProxy	ConnectorClass 未指定 Proxy Service 信息，当前 Connector 不具备 Proxy 能力
True		Connector proxy service 创建成功
False		Proxy service 处于异常状态
Unknown		Proxy service 检查进行中

CACertReady 条件

信息性条件——表示自定义 CA 证书配置的状态。该条件不属于标准就绪条件集，severity: Info，并且不会影响顶层 Ready 条件。只有在启用 enable-custom-ca-certs 功能开关时才会出现。

状态	原因	描述
True	Valid	已设置 `caCertSecretRef`，且引用的 Secret 已成功加载
True	NoCACert	未设置 `caCertSecretRef`；connector 仅使用全局 CA 池
False	SecretNotFound	已设置 `caCertSecretRef`，但引用的 Secret 不存在于 connector 的命名空间中
False	InvalidPEM	引用的 Secret 存在，但不包含任何有效的 PEM 编码证书数据

当该条件为 False 时，控制器还会在 Connector 对象上发出 Kubernetes Warning Event，原因是 CACertSecretNotFound 或 InvalidCACert，可通过 kubectl describe connector <name> 查看。

当功能开关被禁用时，CACertReady 条件完全不会出现。

例如：

status:
  conditions:
  - type: ConnectorClassReady
    status: "True"
    message: ""
  - type: SecretReady
    status: "True"
    message: ""
  - type: LivenessReady
    status: "True"
    lastProbeTime: "2024-10-16T02:27:44Z"
    message: ""
  - type: AuthReady
    status: "True"
    lastProbeTime: "2024-10-16T02:27:44Z"
    message: ""
  - type: ProxyServiceReady
    status: "True"
    lastProbeTime: "2024-10-16T02:27:44Z"
    message: ""
  - type: CACertReady           ##  Only present when enable-custom-ca-certs feature flag is enabled
    status: "True"
    severity: Info              ##  Informational — does not affect Ready
    reason: Valid
    message: 'CA certificate loaded from secret "my-tool-ca"'
  - type: Ready
    status: "True"
    message: ""

示例

使用基本认证的 Git Connector

##  Create authentication information
apiVersion: v1
kind: Secret
metadata:
  name: git-auth
  namespace: default
type: kubernetes.io/basic-auth
data:
  username: dXNlcm5hbWU=
  password: cGFzc3dvcmQ=
---
##  Create Connector
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github
  namespace: default
spec:
  connectorClassName: git
  address: "https://github.com"
  auth:
    name: basic-auth
    secretRef:
      name: git-auth
      namespace: default
    params:
    - name: repository
      value: "org/repo.git"

无认证的 Git Connector

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-public
  namespace: default
spec:
  connectorClassName: git
  address: "https://github.com"
  auth:
    name: basic-auth
  params:
    - name: repository
      value: "org/repo.git"

#连接器

#目录

#概述

#Connector 地址

#基本 URL 格式

#带路径前缀的 URL

#Connector 地址扩展

#Connector 参数

#认证信息

#配置认证信息

#可选认证

#认证检查

#自定义 CA 证书

#每个 Connector 的 CA 证书引用

#全局 CA 证书

#代理地址

#状态信息

#示例

#使用基本认证的 Git Connector

#无认证的 Git Connector

连接器

目录

概述