连接器

概述

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

注意

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

更多信息请参阅 liveness probe 和 authentication probe。

连接器参数

连接器参数可让你向 Connector 实例传递额外的配置信息。这些参数首先在 ConnectorClass 规范中定义,然后可以在创建单个 Connector 资源时进行配置。

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

  • 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 中认证信息的说明。

配置认证信息

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

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

例如,配置 Basic Authentication:

##  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 已配置 proxy capability,系统将为每个 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 type 为 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:指示连接器类型是否正确。
  • SecretReady:指示认证信息是否正确配置。
  • LivenessReady:指示工具是否可访问。
  • AuthReady:指示认证信息是否有效。
  • ProxyServiceReady:指示当前 Connector 的 代理地址 是否已成功分配。
  • Ready:指示整体状态。

SecretReady 条件

表示 Connector 的 Secret 状态信息。

状态原因描述
TrueSecretOptionalConnectorClass 将认证信息标记为可选,且当前 Connector 未配置认证信息
TrueSecret 已配置且存在
FalseSecret 已配置,但在检查 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 服务处于异常状态
UnknownProxy 服务检查进行中

例如:

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。

示例

使用 Basic Authentication 的 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"