#架构

#Connector

Connector 是表示特定工具集成实例的资源。通过配置工具的访问 URL 和认证信息，可以创建该工具的集成实例。

例如，使用 GitHub Private Access Token 集成 https://github.com 就是通过 Connector 实现的。

在 Kubernetes 中，Connector 是命名空间级别的自定义资源。用户可以在同一命名空间内创建多个 Connector 来集成不同的工具。

例如，在 default 命名空间内，可以同时创建一个用于集成 https://github.com 的 Connector 和一个用于集成 https://example.harbor.com/ 的 Connector。

平台管理员可以通过管理 Connector 资源来实现跨集群的工具集成管理。

#ConnectorClass

ConnectorClass 定义了特定类型工具的访问方式和行为规范。它规定了集成某种类型工具时需要的参数，例如工具地址和认证信息。

例如，Git ConnectorClass 定义了集成 Git 工具时需要提供的配置项，包括 Git 服务地址和 Basic-Auth 认证信息。

在 Kubernetes 中，ConnectorClass 是集群级别的自定义资源。开发者可以通过定义新的 ConnectorClass 来扩展平台支持的工具类型。

例如，可以定义 Harbor ConnectorClass 支持集成 Harbor 镜像仓库，定义 MySQL ConnectorClass 支持集成 MySQL 数据库，或者定义 Jira ConnectorClass 支持集成 Jira 项目管理工具。

#Connectors Proxy

Connectors Proxy 是 Connectors 系统的核心能力，提供对集成工具的安全无密访问。它通常作为一个 HTTP 服务运行，可以作为客户端应用的正向代理或反向代理。

当客户端通过 Connectors Proxy 访问工具资源时，代理会自动注入所需的认证凭证，实现无缝访问，无需客户端直接处理凭证。这种方式带来了显著的安全优势：

• 无密访问：通过 Kubernetes 签发的短期令牌，避免将工具凭证直接分发给客户端，防止凭证在客户端环境（如日志或环境变量）中泄露。

为了满足不同工具的认证需求，平台支持内置和自定义代理实现。每个 ConnectorClass 可以提供自己的代理服务，灵活满足特定工具的认证需求。

#内置 Connectors Proxy

内置实现支持完整的 HTTP/HTTPS 协议，支持 Basic Auth 和 Bearer Token 认证方式，提供正向和反向代理功能，灵活性极高。

使用的 ConnectorClass：K8s ConnectorClass、Git ConnectorClass

#自定义 Connectors Proxy

对于需要特殊认证机制的工具，可以开发自定义代理实现。

示例：OCI ConnectorClass 使用自定义的 OCI 插件代理，支持 Harbor 和 CNCF Distribution Registry 等注册表的 OCI 协议和 Bearer Token 授权。

• 更多信息：Connectors Proxy

#Connectors Proxy 的权限控制

Connectors Proxy 代表对目标工具的真实运行时访问。实际上，这决定了工作负载是否可以从仓库克隆、拉取或推送制品，或通过无密运行时路径使用 Connector。

Connectors Proxy 的权限控制仅在启用 enable-connector-proxy-permissions 功能标志时生效。 默认情况下，该功能标志关闭时，客户端只需对 Connector 资源拥有 get 权限即可通过 Connectors Proxy 使用该 Connector。

由于 Connectors Proxy 代表对目标工具的真实运行时访问，代理访问通常被视为权限模型中更敏感的部分。客户端可能被允许查看 Connector，但仍无法使用其代理端点。

Connectors Approval 建立在此代理权限控制之上，其作用是进一步决定工作负载是否被允许使用受保护的 Connector 的 Connectors Proxy。

关于此权限划分的详细说明，请参见 Connectors Permission Model。

#Connectors API

Connectors API 提供基于 Connector 实例访问内部工具资源的能力。例如，对于 Git Connector，Connectors API 可以获取 Git 仓库中的分支列表（References）。

开发者可以通过 Connectors API 方便地访问工具内资源，无需关心具体工具地址和认证细节。

系统支持两种方式通过 API 访问工具资源：

• 原始工具 API：当 ConnectorClass 提供代理服务能力时，客户端可以通过 Connector API 直接访问工具的原始 API。系统自动将请求转发到工具的代理服务，完成认证注入，并返回工具的原始数据。
• 自定义 API：使用 ConnectorClass 提供的自定义 API，提供超出工具原始 API 的扩展能力。

该 API 在实际应用中非常有用，例如：

• 创建应用时获取容器镜像的标签列表
• Git 克隆操作时获取代码仓库的分支（References）列表
• 当 ConnectorClass 支持代理服务时，直接访问工具特定 API

Connectors API 的实现基于 ConnectorClass API 提供的底层能力。

#Connectors API 的权限控制

Connectors API 通常用于面向读取的发现场景，尤其是在平台 UI 流程中。典型示例包括列出分支、标签、项目、仓库或其他选择器数据。

Connectors API 的权限控制仅在启用 enable-connector-apis-permissions 功能标志时生效。 默认情况下，该功能标志关闭时，客户端只需对 Connector 资源拥有 get 权限即可通过 Connectors API 使用该 Connector。

启用 enable-connector-apis-permissions 后，用户可能能够发现 Connector，但如果其角色不允许，则无法通过 Connectors API 浏览工具数据。

在 Alauda Container Platform (ACP) 中，内置面向用户的角色通常已包含常见 UI 场景（如分支、标签、项目和仓库选择）所需的面向读取的 Connectors API 权限。

这种分离使平台在保持 Connector 发现便捷的同时，仍能控制哪些用户可通过 API 路径查询工具数据。详细说明见 Permissions for Connectors API。

#Connectors Permission Model

Connectors 系统将资源权限与能力权限分离。

• 对 Connector 和 ConnectorClass 的资源权限控制谁可以发现或管理集成定义。
• 能力权限控制谁可以通过 Connectors API 或 Connectors Proxy 使用这些定义。

这种划分允许平台使 Connectors 可被发现，而不自动授予对底层工具的运行时访问权限。

在该模型中，Connectors Approval 仅在工作负载通过 Connectors Proxy 使用 Connector 时生效。换言之，它控制工作负载是否可以实际使用该 Connector 完成克隆、拉取、推送或部署等运行时操作，并仅在通过必要检查后授予访问权限。

关于用户如何体验该模型以及内置 Alauda Container Platform (ACP) 权限如何影响它的详细说明，见 Connectors Permission Model。

#ConnectorClass API

ConnectorClass API 定义特定类型工具提供的 API。

不同类型的工具可以提供不同的 API 能力，例如：

• Git ConnectorClass API 可以提供获取代码仓库分支列表的能力
• OCI ConnectorClass API 可以提供获取制品仓库标签列表的能力

开发者可以为每个 ConnectorClass 定义独特的 API 能力，这些能力最终通过 Connectors API 向客户端暴露。

#Connectors CSI Driver

为了方便 K8S 工作负载更轻松地利用 Connectors-Proxy 能力，可以使用 Connectors CSI Driver。

Connectors CSI Driver 可以将 ConnectorClass 中维护的配置文件模板渲染内容挂载到工作负载中。配置文件可包含访问 Connectors Proxy 的信息，使用户能够以最小改动使用 Connectors Proxy 能力。

更多信息请参见 connectors csi driver

#Connectors Approval & Permission Gating

Connectors Approval & Permission Gating 扩展了标准 Connector 权限模型，用于敏感操作。它使用 AccessPolicy 定义谁可以通过 Connectors Proxy 使用 Connectors，既可以立即授予 defaultPermission，也可以在审批相关检查通过后才授予代理访问。

该功能依赖于 enable-connectors-approval 和 enable-connector-proxy-permissions 两个功能标志。

如果这两个功能标志未同时启用，则审批相关流程不生效。

• 如果 enable-connector-proxy-permissions 被禁用，系统不会应用代理能力权限层，因此审批无法限制代理使用。
• 如果 enable-connectors-approval 被禁用，系统不会创建或评估审批相关的运行时流程。

此时，工作负载使用正常的 Connector 访问模型，而非审批限制的代理访问。

如果用户不希望限制 Connector 的使用，仍可创建带有 defaultPermission 的 AccessPolicy，使匹配的工作负载无需等待审批即可通过 Connectors Proxy 使用 Connector。

Connectors Approval & Permission Gating 基于两个互补资源构建：

• AccessPolicy，定义覆盖哪些 Connectors、默认授予何种访问权限以及代理访问需要哪些检查
• AccessRequest，记录单个工作负载尝试使用 Connector 的情况，跟踪匹配的策略、检查结果和临时权限状态

常见流程是 Pod 或流水线任务通过 Connectors CSI Driver 挂载 Connector，系统评估匹配的 AccessPolicy，为该工作负载创建或更新 AccessRequest，等待所需检查，授予工作负载 Connectors Proxy 访问权限，工作负载完成后再撤销权限。

Connectors Approval & Permission Gating 适用于制品推广到生产注册表或其他受保护工具操作等场景，发现和实际使用应分开控制。

该能力的逐步说明见 Connectors Approval & Permission Gating，随后是 AccessPolicy，最后是 AccessRequest。

#ResourceInterface

ResourceInterface 是一种标准化抽象，定义了如何将外部资源（如 Git 仓库、OCI 容器镜像、制品仓库）集成到流水线工作流中。

构建 CI/CD 流水线时，用户传统上需要手动配置资源 URL、git 分支/标签、OCI 镜像标签、制品仓库及认证凭证等，过程复杂且易错，且流水线配置与具体工具实例高度耦合。

ResourceInterface 通过提供标准资源抽象如 “GitCodeRepository”、 “OCIArtifact” 和 “MavenArtifact” 解决了这一问题。用户无需手动输入如 https://github.com/myorg/myapp.git 之类的 URL，而是可以选择 Connector，通过 UI 浏览资源，系统自动生成正确的配置和凭证供流水线使用。

该方式在不同工具间提供一致且友好的体验，同时保持支持多种实现的灵活性。

更多信息请参见 ResourceInterface。

如果您想在自定义 Pipeline 或 Task 中集成 Connector，请参阅 Pipeline Integration。