Alauda DevOps Connectors Docs
  • 简体中文

    • 连接器

    目录

    概述连接器地址基本 URL 格式带路径前缀的 URLConnector 参数认证信息配置认证信息可选认证认证检查代理地址状态信息示例具有基本认证的 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

    连接器地址

    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 参数

    Connector 参数使你能够向 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. 指定认证检查期间所需的参数信息。

    例如，配置基本认证：

    ##  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 分配一个代理地址。

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

    代理地址的默认格式为 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 地址以及 conditions：

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

    代理地址

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

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

    你可以将此地址与现有工具客户端配合使用，以在集群内通过无凭证方式访问工具。更多信息请参考 Connector Proxy。

    如果 ConnectorClass 不具备代理能力，status.proxy 字段将为空。

    API 地址

    api 字段包含 Connector 的 API 地址。

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

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

    Conditions

    conditions 类型包括：

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

    SecretReady Condition

    指示 Connector 的 Secret 状态信息。

    StatusReasonDescription
    TrueSecretOptionalConnectorClass 将认证信息标记为可选，且当前 Connector 未配置认证信息
    True已配置 Secret 且存在
    False已配置 Secret，但在检查 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 代理服务创建成功
    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 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"