连接器

概述

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

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

例如,以下定义展示了一个 Git 类型的连接器:

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

认证信息

认证信息定义了访问工具所需的凭证。根据工具类型的不同,可以配置不同的认证方式。该认证方式在 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,系统将为每个 Connector 分配一个代理地址。

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

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

例如,以下示例描述了一个带有代理地址的连接器:

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 的路径。

例如,以下示例描述了一个带有代理地址的连接器:

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 Condition

表示 Connector 的 Secret 状态信息。

StatusReasonDescription
TrueSecretOptionalConnectorClass 将认证信息标记为可选,且当前 Connector 未配置认证信息
TrueSecret 已配置且存在
FalseSecret 已配置,但在检查 Secret 是否存在时发生错误
Unknown正在检查已配置的 Secret 是否正常

AuthReady Condition

表示 Connector 的认证状态信息。

StatusReasonDescription
TrueNonAuthProbeConnectorClass 未指定 Auth Probe 信息
True凭证检查有效
False凭证检查失败
Unknown正在进行凭证检查

LivenessReady Condition

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

StatusReasonDescription
TrueNonLivenessProbeConnectorClass 未指定 Liveness Probe 信息
True工具访问正常
False工具访问异常
Unknown正在检查工具访问状态

ProxyServiceReady Condition

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

StatusReasonDescription
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: ""

有关 Condition 的更多信息,请参阅 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"

使用 SSH Authentication 的 Git Connector

##  Create SSH Key
apiVersion: v1
kind: Secret
metadata:
  name: git-ssh
  namespace: default
type: kubernetes.io/ssh-auth
data:
  ssh-privatekey: LS0tLS1CRUdJTi...  ##  Base64 encoded private key
---
##  Create Connector
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github-ssh
  namespace: default
spec:
  connectorClassName: git
  address: "git@github.com"
  auth:
    name: ssh-auth
    secretRef:
      name: git-ssh
      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"