Alauda DevOps Connectors Docs
  • 简体中文

    • Connector

    目录

    概述连接器地址基本 URL 格式带路径前缀的 URL连接器参数认证信息配置认证信息可选认证认证检查代理地址状态信息示例带基本认证的 Git 连接器无认证的 Git 连接器

    概述

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

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

    例如，下面的定义展示了一个 Git 类型的连接器：

    apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github
  namespace: default
spec:
  connectorClassName: git  ##  指定连接器类型为 git，该 ConnectorClass 必须存在
  address: "https://github.com"  ##  工具的访问地址
  auth:
    name: basicAuth
    secretRef:  ##  引用认证信息
      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 的认证探针和存活探针不会针对路径前缀执行。如果需要针对路径前缀执行探针，可以使用认证检查表达式和存活检查表达式。

    更多内容请参考存活探针和认证探针。

    连接器参数

    连接器参数允许您向 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. 在 Connector 中通过 spec.auth.secretRef 引用该 Secret。
    4. 指定认证检查时所需的参数信息。

    例如，配置基本认证：

    ##  创建包含用户名和密码的 Secret
apiVersion: v1
kind: Secret
metadata:
  name: github-secret
  namespace: default
type: kubernetes.io/basic-auth
data:
  username: dXNlcm5hbWU=  ##  Base64 编码的用户名
  password: cGFzc3dvcmQ=  ##  Base64 编码的密码
---
##  在 Connector 中引用该 Secret
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 ##  git connectorclass 的 basic-auth 认证为可选

    认证检查

    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  ##  指定要检查的仓库
      value: "org/repo.git"

    注意，一旦 ConnectorClass 指定了认证检测参数，Connector 中必须提供对应参数。即使创建 Connector 时未指定 secret 信息，也必须传递 spec.auth.params。

    代理地址

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

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

    代理地址的默认格式为 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 配置的代理解析器类型为 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 字段中，包含代理地址、API 地址和条件：

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

    代理地址

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

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

    您可以使用该地址配合现有工具客户端，在集群内以无密方式访问工具。详情请参见Connector 代理。

    如果 ConnectorClass 无代理能力，status.proxy 字段为空。

    API 地址

    api 字段包含 Connector 的 API 地址。

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

    您可以在集群外通过该路径访问工具的原始 API，详情请参见Connector API。

    条件

    conditions 类型包括：

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

    SecretReady 条件

    指示 Connector 的 Secret 状态信息。

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

    AuthReady 条件

    指示 Connector 的认证状态信息。

    状态原因描述
    TrueNonAuthProbeConnectorClass 未指定认证探针信息
    True凭证检查有效
    False凭证检查失败
    Unknown凭证检查进行中

    LivenessReady 条件

    指示 Connector 的存活状态信息。

    状态原因描述
    TrueNonLivenessProbeConnectorClass 未指定存活探针信息
    True工具访问正常
    False工具访问异常
    Unknown工具访问检查进行中

    ProxyServiceReady 条件

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

    状态原因描述
    TrueNonProxyConnectorClass 未指定代理服务信息，当前 Connector 无代理能力
    TrueConnector 代理服务创建成功
    False代理服务处于异常状态
    Unknown代理服务检查进行中

    例如：

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

    示例

    带基本认证的 Git 连接器

    ##  创建认证信息
apiVersion: v1
kind: Secret
metadata:
  name: git-auth
  namespace: default
type: kubernetes.io/basic-auth
data:
  username: dXNlcm5hbWU=
  password: cGFzc3dvcmQ=
---
##  创建 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 连接器

    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"