连接器

概述

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

连接器地址

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/"
  # ...

注意:当指定了路径前缀时,它将成为该 Connector 执行的所有操作的默认基础路径,包括认证和 liveness 检查。

认证信息

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

配置认证信息

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

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

例如,要配置基本认证:

##  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。

代理地址

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

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

代理地址的默认格式为 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 字段中,包含以下内容:

  • ConnectorClassReady:指示 connector 类型是否正确。
  • SecretReady:指示认证信息是否已正确配置。
  • LivenessReady:指示工具是否可访问。
  • AuthReady:指示认证信息是否有效。
  • ProxyServiceReady:指示当前 Connector 的 代理地址 是否已成功分配。
  • Ready:指示整体状态。

SecretReady 条件

指示 Connector 的 Secret 状态信息。

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

AuthReady 条件

指示 Connector 的认证状态信息。

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

LivenessReady 条件

指示 Connector 的存活性状态信息。

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

ProxyServiceReady 条件

指示 Connector 的代理服务状态信息。

状态原因描述
TrueNonProxyConnectorClass 未指定 Proxy Service 信息,当前 Connector 不具备 Proxy 能力
TrueConnector 代理服务创建成功
FalseProxy 服务处于异常状态
Unknown正在进行 Proxy 服务检查

例如:

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: Ready
    status: "True"
    message: ""

有关条件的更多信息,请参阅 Connector Conditions。

示例

使用基本认证的 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"