ResourceInterface
目录
概述解决的问题数据结构人类可读信息资源类别参数属性表达式语法依赖关系工作区配置多个 ConnectorConnectorClassSchema Version and Tekton CompatibilityCompatibility With Tekton ReleasesRecovering From the Broken-Form SymptomPreferred: Upgrade the Tekton operatorFallback: Cap the installed schema-version range动态表单概述扩展上下文变量动态表单配置方式直接配置 API引用 OpenAPI 显示 Schema示例后续步骤参考概述
ResourceInterface 是一种集群级资源,用于定义外部资源(例如 Git 仓库、OCI 构件和 Maven 构件)的标准化抽象,以及这些资源如何集成到流水线工作流中。它充当 connector 与流水线编排之间的桥梁,只需极少的手动配置即可实现资源的无缝集成。
以下示例定义了一个描述 Git 仓库访问的 GitCodeRepository 接口:
ResourceInterface 定义了资源集成的以下关键方面:
- 资源配置所需的输入参数
- 根据参数和 connector 信息计算的输出属性
- 用于卷和凭据的工作区定义
本文档提供 ResourceInterface 数据结构定义 和示例 ,帮助读者了解如何自定义 ResourceInterface。
除非您希望自定义 ResourceInterface,否则无需了解 ResourceInterface 的详细信息。
解决的问题
在构建 CI/CD 流水线时,用户通常会面临以下几个挑战:
手动输入资源:用户无法轻松浏览和添加 Git 仓库、OCI 仓库以及其他外部服务等外部资源。他们必须手动输入 URL 并设置工作区,这不仅容易出错,而且耗时。
重复配置执行:每次运行流水线时,用户都必须手动输入 Git 修订版本和目标 OCI 标签等版本详细信息,并重复配置工作区。
属性分散:同一远程资源的属性通常会分散到不同的参数中。例如,git-clone 任务需要单独的 url 和 revision 参数,以及用于凭据和源代码的工作区配置。
工作区选择复杂:流水线工作区选择流程会列出所有可用选项,但几乎不会说明每个工作区应使用哪种 connector 类型。
ResourceInterface 通过提供描述外部资源并将其集成到流水线工作流中的标准化方式,解决了这些问题。用户可以通过 UI 界面浏览和选择资源,同时自动生成正确的配置和凭据。
数据结构
ResourceInterface 是集群级 k8s 资源
- Kind:ResourceInterface
- API Version:connectors.alauda.io/v1alpha1
人类可读信息
ResourceInterface 是标准 k8s 资源,可以使用 annotations 添加人类可读信息。
您还可以使用 style.tekton.dev/descriptors annotation 描述动态表单的参数。
更多详细信息请参阅 dynamic-form。
资源类别
ResourceInterface 将资源组织到定义通用契约和行为的类别中。类别使用标签 resourceinterface.connectors.cpaas.io/category 标记。
多个 ResourceInterface 可以属于同一类别(例如,gitcoderepository 和 githubcoderepository 都属于 GitCodeRepository 类别)。同一类别中的资源必须提供相同的标准属性和工作区,以确保兼容性。
参数
参数定义资源集成到流水线时所需的输入数据。这些参数会影响输出属性的计算。
参数在 spec.params 中定义,并遵循 Tekton 参数类型:
- name:参数名称
- type:支持
string、array、object(与 Tekton ParamSpec 类型一致) - default:参数默认值(可选)
- description:用于 UI 显示的参数描述(可选)
例如:
属性
属性定义根据输入参数和 connector 信息计算出的输出值。流水线任务可以将其作为参数使用,也可以将其提升为流水线级参数。
属性在 spec.attributes 中定义:
- name:属性名称
- type:值类型,支持
string、array - expression:用于计算属性值的 JavaScript 表达式
- parameterize:参数化配置
- name:参数化时的默认参数名称
- disable:是否禁用参数化
- dependsOn:对参数或 connector 的依赖
例如:
表达式语法
表达式使用 JavaScript 语法,并支持:
- 字符串拼接:
params.organization + '/' + params.repository - 对象属性访问:
connector.metadata.name - 数组操作:
params.tags.map(tag => connector.spec.address + ':' + tag) - 内置函数:
url(connector.spec.address).host:获取地址的主机selectedConnectors():获取主 Connector 以及 Integration 中选择的所有额外 Connector,用于 CSIconnectors卷属性。请参阅多个 Connector。selectedConfigurationNames('<baseNames>'):获取工作区的基础configuration.names以及跨类型额外 Connector 所需的配置。需要 schema-version 3,该版本由 Tekton operator v4.14.0 及更高版本支持。请参阅多个 Connector。
同时支持其他 JavaScript 语法。
可用上下文:
connector:当前 connector 信息,connector 的结构请参阅 Connector 概念params:当前参数值
上下文数据结构如下:
安全性:前端在沙箱环境中执行 JavaScript 代码,仅允许使用安全的沙箱函数。
示例:
{connector.spec.address + '/' + params.repository}:获取仓库地址{url(connector.spec.address).host + '/' + params.repository + ':' + params.tag}:获取制品地址{params.tags.map(tag => url(connector.spec.address).host + '/' + params.repository + ':' + tag)}:通过遍历 tags 数组获取制品数组中的地址
依赖关系
依赖关系指定属性计算所依赖的参数或 connector 信息:
params.<param-name>:依赖特定参数值connector:依赖 connector 选择
工作区
工作区定义 ResourceInterface 提供的卷和凭据。它们支持为流水线任务自动配置所需资源。
工作区在 spec.workspaces 中定义:
- name:工作区名称
- workspaceMapping.name:添加到流水线工作区时的默认工作区名称
- value:工作区默认值(遵循 Tekton WorkspaceBinding 格式),与 Tekton WorkspaceBinding 类型一致
例如:
工作区值支持使用与属性相同的语法,通过表达式动态引用参数和 connector 值。
配置
spec.configurations 保存可选的、适用于整个 ResourceInterface 的设置。用户创建 Integration 时,Pipeline Integration UI 会读取这些设置。目前其中包含一个条目:multipleMergeConnectors。
多个 Connector
spec.configurations.multipleMergeConnectors 支持一个 Pipeline Integration 使用多个 Connector:一个主 Connector 加上额外 Connector。在使用 selectedConnectors() 列出所选 Connector 的每个工作区中,Connectors CSI Driver 会将它们的凭据和配置文件合并到该工作区中。仅引用主 Connector(不含 connectors 的 connector.name / connector.namespace)的工作区仍只使用主 Connector。例如,OCI 制品 ResourceInterface 中已弃用的 docker-credentials 工作区就是如此。
在一个 CSI 卷中挂载多个 Connector 需要 enable-multi-connector 功能标志。在 UI 中,仅当该标志和 enabled 均启用时,才会显示额外 Connector 选择器。
应接收额外 Connector 列表的工作区,会在 CSI connectors 卷属性中使用 selectedConnectors() 列出这些 Connector:
跨类型配置名称。其他类型的额外 Connector 需要自己的配置文件,例如 Maven Connector 需要 settings。固定的 configuration.names 列表无法预先了解这些配置。因此,当 allowCrossTypeConnectors 为 true 时,每个使用 selectedConnectors() 的工作区都应通过 selectedConfigurationNames(baseNames) 构建 configuration.names:
baseNames是工作区针对主类型自身的规则,使用与configuration.names相同的语法:配置名称以及可选的!<fileName>排除项。- 对于每个其他类型的额外 Connector,该函数会添加其 ConnectorClass 声明的所有配置名称(
spec.configurations[].name)。每个 ConnectorClass 只展开一次。 - 相同类型的额外 Connector 不会添加任何内容。对于这些 Connector,仅挂载
baseNames中指定的配置。 - 结果按基础名称、跨类型名称、再到
baseNames中的!排除项排序,并移除重复项。 - 排除项仅来自主 ResourceInterface 的
baseNames。例如,OCI 或 Harbor 工作区中的!ca.cert在添加 Maven Connector 时同样适用。不排除ca.cert的 Maven ResourceInterface 在添加 OCI Connector 时会保留该文件。 - 如果 UI 计算表达式时无法读取额外 Connector 或其 ConnectorClass,则该 Connector 不会添加任何配置名称,表达式本身也不会失败。此容错仅适用于计算
configuration.names。Pod 启动时,CSI Driver 必须读取connectors中列出的每个 Connector;如果其中任何一个无法读取,卷挂载将失败。
例如,基础 registry-config,!ca.cert 加上一个 ConnectorClass 声明了 settings 的额外 Maven Connector 后,工作区会挂载 registry-config,settings,!ca.cert。
selectedConfigurationNames 是 schema-version 3 表达式,因此跨类型 ResourceInterface 必须携带 resourceinterface.connectors.cpaas.io/schema-version: "3"(请参阅 Schema Version and Tekton Compatibility)。operator 会将较早的同类型 ResourceInterface 与其一同安装,以供较旧的前端使用。
跨类型 Multiple Connectors 的版本要求:
在较旧的 Tekton 版本中,行为取决于该版本是否理解 schema-version:
- 识别
schema-version但支持低于 3 的版本:UI 会跳过 schema-version 3 ResourceInterface,并选择该类别中较早的 ResourceInterface,因此额外 Connector 仍仅限于相同类型。无需执行任何操作。 - 早于对
schema-version的支持:UI 会将 schema-version 3 ResourceInterface 视为可渲染资源,但其 Integration 表单会损坏。请使用pipeline-integration安装标志("<=2")限制已安装的 schema-version,或升级 Tekton。请参阅 Upgrade the Tekton operator 和 Cap the installed schema-version range。
以下 ResourceInterface 启用了跨类型 Multiple Connectors:
ConnectorClass
ConnectorClass 通过标签 resourceinterface.connectors.cpaas.io/<resource-interface-name>: "true" 标记受支持的 ResourceInterface,例如:
这使系统能够将兼容的 Connector 与 ResourceInterface 进行匹配,并根据 ResourceInterface 定义提供适当的参数表单。
有关 ConnectorClass 的更多信息,请参阅 ConnectorClass 概念
Schema Version and Tekton Compatibility
ResourceInterface 包含两个与版本相关的标签,用于不同的目的:
省略时,两者均默认为 "1"。本节其余内容将介绍 schema-version 维度,这是 Tekton 兼容性体现的所在。
Compatibility With Tekton Releases
在能够识别 schema-version 标签的 Tekton 版本中,DevOps 前端会针对每个类别,自动选择 schema-version 不高于其自身支持级别的最高版本 ResourceInterface。无需配置 operator — 混合 schema 部署开箱即用。
在不支持 schema-version 的较旧 Tekton 版本中,前端会将所有已安装的 ResourceInterface 视为可渲染资源。当某个类别只有一个包含 schema-version > 1 的 ResourceInterface 时,选择 Connector 会生成损坏或空的 integration 表单 — 前端无法解析更高版本 schema 中的表达式、workspace 配置或表单控件。
Recovering From the Broken-Form Symptom
如果你在较旧的 Tekton 版本中遇到上述损坏表单问题,可以采取两种恢复路径,优先顺序如下:
Preferred: Upgrade the Tekton operator
将 Tekton 升级到能够识别 schema-version 标签的版本。这是根本性的修复方案:
- DevOps 前端随后会透明地选择其自身
currentSchema支持的最高版本 ResourceInterface,并静默跳过超出该版本的内容;无需对 Connectors operator 进行任何配置,损坏表单问题便会消失。 ConnectorsConfig.spec.installFlags保持为空(其默认值),因此每个已发布的 ResourceInterface 都会保持安装状态,并在 Tekton 能够渲染它时立即可用。- 不会引入技术债务 — 无需记住之后撤销紧急覆盖设置。
如果你的环境允许升级 Tekton,建议优先采用此路径,完成后即可停止此处的操作。
Fallback: Cap the installed schema-version range
如果暂时无法升级 Tekton,可以在集群单例 ConnectorsConfig 上限制要安装的 schema-version:
更高版本 schema 的 ResourceInterface 会从集群中移除;各类别将回退到 Tekton 能够渲染的版本。Tekton 升级后,提高上限(例如 "<=3")或移除该条目,以重新安装这些 ResourceInterface。
有关完整的 ConnectorsConfig 参考信息,请参阅
Installation → ConnectorsConfig。
动态表单
动态表单以声明方式为 Pipeline Integration 配置交互式 UI 组件。借助动态表单,用户可以直接通过 connector 浏览和选择 Git 仓库、修订版本等资源。
概述
使用 style.tekton.dev/descriptors 注解定义参数的动态表单行为。示例如下:
语法遵循 Pipeline Dynamic Forms 规范。建议在继续操作之前先熟悉相关文档。
除标准功能外,ResourceInterface 中的动态表单还支持:
- 用于访问 connector 和 ResourceInterface 数据的扩展上下文变量
- 在 ConnectorClass 中定义引用 OpenAPI 显示 schema,以集中配置 API,并在使用动态表单时引用 API 定义
扩展上下文变量
ResourceInterface 动态表单中提供以下上下文变量:
动态表单配置方式
在 ResourceInterface 中配置动态表单有两种方式:
-
直接配置 API:使用描述符表达式直接调用 connector API。这种方式简单直接,易于理解。Connectors System 提供用于列出仓库、Git 引用等内容的 Connector API 端点。
-
在 ConnectorClass 中引用 OpenAPI 显示 schema:使用
spec.api.openapi在 ConnectorClass 中定义 API 调用和显示映射。这种方式可以集中管理 API 定义和显示配置,避免在多个 ResourceInterface 之间重复配置。使用动态表单时,可以直接引用 ConnectorClass 中的 API 定义。
可以独立使用任一方式,也可以根据需要组合使用。
直接配置 API
示例:列出 GitLab 仓库
GitLab connector 会公开原生 GitLab API,可用于填充仓库选择器:
示例:列出 Git 引用
Git connector 提供用于列出分支和标签的 gitrefs 端点:
引用 OpenAPI 显示 Schema
要集中管理 API 定义和显示配置,请使用 spec.api.openapi 在 ConnectorClass 中定义这些内容。之后,动态表单即可直接引用这些定义,从而消除不同 ResourceInterface 之间的冗余配置。
前提条件
- 在 ConnectorClass 中定义 OpenAPI 规范。详情请参阅 ConnectorClass OpenAPI 描述。
- 添加
x-display-schema扩展,以定义 API 与动态表单的集成方式。
显示 Schema 结构
x-display-schema 扩展包含:
parameters[]:定义如何在运行时填充 API 参数。name:参数名称(必须与 API 参数名称匹配)value:参数值表达式。语法遵循 Pipeline Dynamic Forms。
descriptors:定义如何将 API 响应数据映射到表单选项。语法遵循 Pipeline Dynamic Forms。
示例:Git 引用 API
以下 ConnectorClass 配置定义了带显示 schema 的 GET /git/gitrefs API:
- 将
repositoryUrl参数设置为${context.connector.spec.address + "/" + context.params.repository + ".git"},并作为查询参数传递 - 将
search参数设置为${current.search},用于筛选结果 - 将响应中的
items数组映射为选择选项,并使用name同时作为标签和值
示例:
在 ResourceInterface 中引用 OpenAPI
在 ConnectorClass 中定义 API 后,可以使用以下语法在 ResourceInterface 中引用它:
- 使用
urn:alm:descriptor:widgets:select指定 widget 类型 - 使用
schema:openapi:context.connectorClass.spec.api.openapi:<operationId>引用 ConnectorClass 中的 API 定义
例如:
通过此配置,Pipeline Integration 中的 revision 字段会渲染为下拉列表,并从 listGitRefs API 获取选项。
示例
GitCodeRepository ResourceInterface
OCIArtifact ResourceInterface
后续步骤
- 了解 Pipeline Integration,以便在自定义 Pipeline 或 Task 中集成 Connector。