如何配置动态表单
功能概览
动态表单配置功能允许您以声明方式为 Pipeline 和 Task 等资源配置友好的交互体验。无需编写前端代码,只需在资源的 annotations 中添加 style.tekton.dev/descriptors 配置,即可实现:
- 动态生成表单:自动为资源参数生成交互式表单,在编排和执行 Pipeline 与 Task 时提供更好的体验。
- 丰富的组件支持:提供文本框、选择器、开关、YAML 编辑器等多种表单组件。
- 字段验证:内置验证规则,确保用户输入符合要求。
- 动态获取数据:支持通过 API 动态加载选项数据。
- 字段链接:为特定字段添加产品或外部链接。
- 仅元数据配置:在不覆盖字段默认组件的情况下,添加标签、描述、工具提示、禁用状态、预览或链接。
- 结构化数组编辑:将字符串数组中的每一项拆分为一个或多个可编辑字段。
- 组合输入:为一个 Pipeline 参数呈现多个相关控件,并在执行前合并这些控件的值。
- 嵌套表单:加载所选资源的配置,并在当前表单中呈现其参数。
- 本地化元数据:以多种语言维护显示名称、描述和工具提示,同时保留原始的 Tekton 名称和值。
动态表单行为可在主要 Pipeline 工作流中复用:
如果字段没有受支持的描述符,产品将保留其常规
输入控件和原生 Tekton 行为。
使用场景
- Pipeline 编排/运行时:在编排或触发
Pipeline 时,允许用户通过友好的表单填写 namespace 和 secrets 等参数
- Task 复用:在
Task 或 Pipeline 模板级别,为常用参数提供默认值、下拉选项和验证
- 多环境选择:通过 API 动态查询可用环境或配置,并将其用作选择选项
- 结构化配置:编辑
KEY=VALUE、JSON 字符串或其他结构化数组项等值,无需手动格式化每个字符串
- 基于资源的配置:选择资源并在行内配置其参数,例如为所选模板配置值
- 一致的 Pipeline 编写和执行:在 Pipeline 编辑、Task 配置、PipelineRun 和 TaskRun 表单中复用相同的参数元数据和动态控件
快速入门
基本配置结构
所有配置都通过 style.tekton.dev/descriptors 中的 annotations 字段定义:
metadata:
annotations:
style.tekton.dev/descriptors: |
- path: params.parameter-name
x-descriptors:
- configuration-item1
- configuration-item2
配置说明
path:根据所描述的资源字段,使用 params.<parameter-name>、workspaces.<workspace-name> 或
results.<result-name>。
x-descriptors:配置项数组,每个配置项以 urn:alm:descriptor: 开始
简单示例
为 Task 参数配置一个必填文本输入框:
apiVersion: tekton.dev/v1
kind: Task
metadata:
name: simple-task
annotations:
style.tekton.dev/descriptors: |
- path: params.gitURL
x-descriptors:
- urn:alm:descriptor:label:zh:GitRepo
- urn:alm:descriptor:com.tectonic.ui:text
- urn:alm:descriptor:placeholder:zh:Git URL
- urn:alm:descriptor:com.tectonic.ui:validation:required
spec:
params:
- name: gitURL
type: string
steps:
- name: clone
image: alpine/git
script: |
git clone $(params.gitURL)
能力选择指南
使用下表选择符合需求的最小描述符集合。
表单标签
# Label for the form
- urn:alm:descriptor:label:en:English Name
- urn:alm:descriptor:label:zh:Chinese name
表单描述
# Description for the form
- urn:alm:descriptor:description:en:English Description
- urn:alm:descriptor:description:zh:Chinese Description
占位符提示
# Placeholder for the form
- urn:alm:descriptor:placeholder:en:This is a Placeholder
- urn:alm:descriptor:placeholder:zh:This is a Placeholder
表单帮助工具提示
# Help tooltip for the form
- urn:alm:descriptor:tooltip:en:This is a Help Tip
- urn:alm:descriptor:tooltip:zh:This is a Help Tip
表单禁用状态
# Whether the form is disabled
- urn:alm:descriptor:com.tectonic.ui:disabled
您可以配置字段元数据和增强功能,而无需声明表单组件,例如 text、select 或 widgets:select。
在此模式下,UI 会保留参数输入项的默认呈现组件,仅应用受支持的描述符增强功能。当您希望改善显示文本或添加帮助链接,但不改变参数的输入行为时,此模式非常有用。
- path: params.mailSubject
x-descriptors:
- urn:alm:descriptor:label:en:Mail Subject
- urn:alm:descriptor:label:zh:Mail Subject
- urn:alm:descriptor:description:en:Used to render the notification title.
- urn:alm:descriptor:description:zh:Used to render the notification title.
- urn:alm:descriptor:tooltip:en:Rendered at runtime.
- urn:alm:descriptor:tooltip:zh:Rendered at runtime.
仅元数据模式支持以下描述符:
urn:alm:descriptor:label:*
urn:alm:descriptor:description:*
urn:alm:descriptor:tooltip:*
urn:alm:descriptor:com.tectonic.ui:disabled
urn:alm:descriptor:enhance:preview:* 和 urn:alm:descriptor:preview:*
urn:alm:descriptor:enhance:docLink:* 和 urn:alm:descriptor:docLink:*
以下描述符需要显式组件能力,在仅元数据模式下不适用:
urn:alm:descriptor:placeholder:*
urn:alm:descriptor:com.tectonic.ui:validation:*
urn:alm:descriptor:expression:props.default*
urn:alm:descriptor:expression:props.options:*
urn:alm:descriptor:widgets:*
如果需要占位符、验证、动态选项、默认值或特定控件行为,请显式声明相应组件。
要将仅元数据字段设为只读,请添加禁用描述符:
- urn:alm:descriptor:com.tectonic.ui:disabled
高级和基本表单模式
对于使用受支持动态表单描述符的参数,产品可以显示使用已配置控件或小组件的 Advanced 表单。当不需要高级控件,或高级控件无法在当前上下文中使用时,Basic 表单仍可作为回退选项。
切换模式不会改变实际的 Pipeline 参数值。模式只会改变值的编辑方式。这样,用户可以在可用时使用便捷的选择器或结构化编辑器,同时保留直接输入方法,以便进行故障排除或输入特殊值。
当参数已经由 Pipeline Integration 提供时,表单可以先显示 Integration 配置。移除 Integration 绑定后,参数可以恢复为其描述符定义的动态控件。
动态表单元数据不仅限于参数输入控件。Pipeline
作者还可以为 Pipeline 参数、Workspace 和 Result 配置显示名称、描述和
工具提示。
打开 Pipeline 配置表单,选择 Param、Workspace 或 Result,然后
打开 Advanced Form Configuration。你可以在 Form
模式下维护元数据,或在 YAML 模式下编辑完整的描述符。
元数据会复用于:
- Pipeline 和 Task 详情。
- Pipeline 和 Task 执行表单。
- Pipeline 任务配置。
- Result 变量建议。
原始 Tekton 名称仍会与配置的显示名称一起显示,插入 Pipeline 定义的引用
仍会使用原始 Tekton 名称。例如,显示为 Artifact URL 的 Result 仍会插入
$(tasks.build.results.artifact-url)。
多语言
Form 编辑器默认使用英语。当描述符包含多种语言的元数据时,会显示语言选择器。
你可以选择一种语言并更新其显示名称、描述和工具提示,而不会覆盖其他语言。
当需要维护完整描述符(包括组件、验证、动态选项或小组件设置)时,请使用 YAML
模式。Form 模式用于常见的显示元数据,并会保留描述符其余配置不变。
Workspace 和 Result 边界
Workspace 和 Result 描述符仅用于增强显示信息。它们不会将 Workspace 或
Result 转换为输入控件,其组件、验证、默认值、动态选项和小组件设置也不会应用。
Workspace 和 Result 的必需或可选行为仍由 Pipeline 声明提供。
Run Template 行为
Run Template 使用 Pipeline 描述符作为其参数的基础配置。当特定模板需要不同的
标签、控件、默认值或可见性时,Run Template 可以提供自己的描述符配置。
编辑 Run Template 时,所有 Pipeline 参数都可供配置。使用 Set at Runtime
标识应在运行模板时提供的值。在执行期间,用户会看到 Run Template 为运行时输入
公开的参数;固定值仍是已保存模板的一部分。
更改 Pipeline 描述符不会自动替换 Run Template 的特定配置。更改 Pipeline 后,
请检查 Run Template,尤其是在添加参数或更改其运行时行为时。
描述符源取决于表单上下文。Pipeline 和 Task 表单从选定的 Pipeline 或 Task
读取描述符。Integration 表单从选定的 ResourceInterface 或 Connector 读取
Integration 描述符。Trigger 和 ScheduledTrigger 表单复用 Run Template 配置;
其事件变量值通过 TriggerBinding 和相应的启动方法维护。
Workspace 和 Result 的元数据示例
- path: workspaces.source
x-descriptors:
- urn:alm:descriptor:label:en:Source Workspace
- urn:alm:descriptor:description:en:Workspace used for source files
- urn:alm:descriptor:tooltip:en:Provide storage that contains the source code
- path: results.image-url
x-descriptors:
- urn:alm:descriptor:label:en:Published Image
- urn:alm:descriptor:description:en:Image produced by the Pipeline
- urn:alm:descriptor:tooltip:en:Use this Result in downstream tasks
这些描述符仅用于改善显示效果。Pipeline 在其定义和变量引用中仍使用原始的
source Workspace 和 image-url Result 名称。
组件类型
文本输入
# value: string
- urn:alm:descriptor:com.tectonic.ui:text
多行文本输入
# value: string
- urn:alm:descriptor:com.tectonic.ui:textarea
标签输入
# value: array
- urn:alm:descriptor:com.tectonic.ui:tagsInput
单选框
# Declare a radio option with value "option-a"
- urn:alm:descriptor:com.tectonic.ui:radio:option-a
# Set the English display label of option-a to "Option A"
- urn:alm:descriptor:com.tectonic.ui:radio:option-a:en:Option A
# Set the Chinese display label of option-a to "Option A(zh)"
- urn:alm:descriptor:com.tectonic.ui:radio:option-a:zh:Option A(zh)
# Declare a radio option with value "option-b"
- urn:alm:descriptor:com.tectonic.ui:radio:option-b
# Set the English display label of option-b to "Option B"
- urn:alm:descriptor:com.tectonic.ui:radio:option-b:en:Option B
# Set the Chinese display label of option-b to "Option B(zh)"
- urn:alm:descriptor:com.tectonic.ui:radio:option-b:zh:Option B(zh)
# Set the default selected option to "option-a"
- urn:alm:descriptor:com.tectonic.default:option-a
开关
# value: boolean
- urn:alm:descriptor:com.tectonic.ui:booleanSwitch
# Map value to specified string
# When switch is on, value is True
- urn:alm:descriptor:props:booleanSwitch:true:True
# When switch is off, value is False
- urn:alm:descriptor:props:booleanSwitch:false:False
YAML 编辑器
# value: string
- urn:alm:descriptor:com.tectonic.ui:yaml
选择框
基本内容配置
# value: string
- urn:alm:descriptor:com.tectonic.ui:select
# Options
- urn:alm:descriptor:props:select:options:valueA
- urn:alm:descriptor:props:select:options:valueB
# Set the select box to multiple selection mode
# value: array
- urn:alm:descriptor:props:select:multiple
# Manually entered content can be used as selection items
- urn:alm:descriptor:props:select:allowCreate
# Content can be cleared
- urn:alm:descriptor:props:select:clearable
API 动态选项配置
当表单控件需要根据当前环境动态加载可用选项(例如可用的 namespace、secret 等)时,可以使用 API 动态配置,从后端接口实时获取下拉选项。
在此模式下,API URL 通常与上下文变量结合使用,根据用户当前的集群、namespace、项目或已填写的参数动态构造请求路径。例如:
# Use ${context.cluster} variable in URL to dynamically retrieve namespace list for current cluster
- urn:alm:descriptor:expression:props.options:api:apiPath
- urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces
可用的上下文变量
在动态 API 路径中,可以使用 ${variable} 引用运行时上下文信息。
对于 Integration 表单,${context.connectorClass} 是选中的
ConnectorClass 对象。Schema 表达式可以通过
context.connectorClass 访问同一对象,例如在从 ConnectorClass 定义解析 OpenAPI schema 时使用。
这些变量通常与 API URL 结合使用,以便在不同环境中动态构造请求地址,从而实现与环境相关的选项加载逻辑。例如:
- urn:alm:descriptor:expression:props.options:api:apiPath
- urn:alm:descriptor:expression:props.options:api:/api/v1/${context.namespace}/deployments?repo=${context.params.repo}
配置返回数据的数据路径
- urn:alm:descriptor:expression:props.options:path:spec.items
当 API 返回复杂结构时,例如:
{
"spec": {
"items": [ ... ]
}
}
可以使用 path 指定如何从该结构中提取选项数组。
配置选项的标签和值映射字段
如果返回的数据对象较为复杂,需要将内部字段指定为“显示名称”和“选项值”,可以使用:
- urn:alm:descriptor:expression:props.options:label:path:metadata.name
- urn:alm:descriptor:expression:props.options:value:path:metadata.name
当 API 返回简单的 string[] 数组时,无需进行此配置。
配置 API 查询参数
如果需要向 API 请求传递查询参数(例如搜索关键字或过滤条件),可以使用:
# Add query parameter named "search" with user input as value
- urn:alm:descriptor:widgets:select
- urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/apis/tekton.dev/v1/namespaces/${context.namespace}/pipelineruns
- urn:alm:descriptor:expression:props.options:path:items
- urn:alm:descriptor:expression:props.options:label:path:metadata.name
- urn:alm:descriptor:expression:props.options:value:path:metadata.name
- urn:alm:descriptor:expression:props.options:api:params:search:${current.search}
当用户在下拉框中输入“test”时,实际请求将为:
/kubernetes/.../pipelineruns?search=test
基于 Schema 的选项
在 Integration 场景中,选择框可以使用选中 Connector 暴露的 OpenAPI schema,而无需手动描述每个 API 请求和选项映射:
- urn:alm:descriptor:widgets:select
- urn:alm:descriptor:expression:props.options:schema:openapi:context.connectorClass.spec.api.openapi:listProjects
平台使用该 schema 构建可用选项及其表单行为。当 Connector 为项目、分支、标签或合并请求提供标准 API 时,这种方式非常有用。
计算选项字段
对于更复杂的响应,可以使用表达式计算选项列表,或计算每个选项的标签、值和描述:
- urn:alm:descriptor:expression:props.options:path.exp:$.items.flatMap(item => item.spec.targets || [])
- urn:alm:descriptor:expression:props.options:label:path.exp:`${$.name} (${$.status})`
- urn:alm:descriptor:expression:props.options:value:path.exp:$.id
- 'urn:alm:descriptor:expression:props.options:description:path.exp:`Target: ${$.name}`'
表达式会将当前选项作为 $ 接收。表达式还可以使用当前表单上下文(例如 context.params)来计算值。
高级用法:支持 JavaScript 表达式,例如:
${Object.keys(context.params || {}).join(',')}
增强功能
参数默认值
固定默认值
- urn:alm:descriptor:expression:props.default:default-value
基于表达式的动态默认值
可用变量:
-
option:选项原始数据
-
index:选项索引
-
length:选项总数
-
context:上下文参数
# Select options with specific labels
- urn:alm:descriptor:expression:props.default.exp:option.metadata.labels['default']==='true'
# Default to select the first item
- urn:alm:descriptor:expression:props.default.exp:index === 0
# Default to select the last item
- urn:alm:descriptor:expression:props.default.exp:index === length - 1
# Default to select when there is only one option
- urn:alm:descriptor:expression:props.default.exp:length === 1
# Default to select the current namespace
- urn:alm:descriptor:expression:props.default:${context.namespace}
# Complex conditions
- urn:alm:descriptor:expression:props.default.exp:option.metadata.name.includes('test') && option.status.conditions.some(c => c.status==='True')
支持配置各种验证规则,并且可以同时应用多个规则。
必填验证
- urn:alm:descriptor:com.tectonic.ui:validation:required
长度验证
# Minimum length
- urn:alm:descriptor:com.tectonic.ui:validation:minLength:6
# Maximum length
- urn:alm:descriptor:com.tectonic.ui:validation:maxLength:64
数值范围验证
# Minimum value (applicable to numeric types)
- urn:alm:descriptor:com.tectonic.ui:validation:minimum:1
# Maximum value
- urn:alm:descriptor:com.tectonic.ui:validation:maximum:100
正则表达式验证
# Positive integer
- urn:alm:descriptor:com.tectonic.ui:validation:pattern:[1-9]\d*
# Kubernetes resource name (lowercase letters, numbers, hyphens)
- urn:alm:descriptor:com.tectonic.ui:validation:pattern:[a-z0-9]([-a-z0-9]*[a-z0-9])?
组合示例:为密码字段配置完整的验证规则
- path: params.password
x-descriptors:
- urn:alm:descriptor:label:zh:password
- urn:alm:descriptor:com.tectonic.ui:text
- urn:alm:descriptor:description:zh:At least 8 characters, including letters and numbers.
- urn:alm:descriptor:com.tectonic.ui:validation:required
- urn:alm:descriptor:com.tectonic.ui:validation:minLength:8
- urn:alm:descriptor:com.tectonic.ui:validation:maxLength:32
预览组件
预览组件允许用户直接在表单中预览所选资源的 YAML 内容。这在用户需要先验证资源配置,再将其用于 Pipeline 的场景中特别有用,例如检查 ConfigMap 内容、验证 Secret 数据,或查看 Task/Pipeline YAML 定义。
例如,当用户从下拉框中选择 ConfigMap,并将其用作 Task 中的卷挂载或环境变量来源时,可以直接在表单中预览 ConfigMap 的数据,以确保选择了正确的资源。
配置
# Enable preview - show button when parameter has value
- urn:alm:descriptor:enhance:preview:context.params.<param-name>
# API endpoint to fetch resource content
- urn:alm:descriptor:preview:resource:api:<api-url>
# JSONPath or JS expression to extract content from response
- urn:alm:descriptor:preview:resource:path:<jsonpath>
- urn:alm:descriptor:preview:resource:path.exp:<js-expression>
示例:配置一个用于选择 ConfigMap 的下拉框,并添加用于查看其 YAML 内容的预览按钮。
- path: params.configmap
x-descriptors:
# Form label
- urn:alm:descriptor:label:en:ConfigMap
- urn:alm:descriptor:label:zh:ConfigMap
# Dropdown to select ConfigMap from current namespace
- urn:alm:descriptor:com.tectonic.ui:select
- urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces/${context.namespace}/configmaps
- urn:alm:descriptor:expression:props.options:path:items
- urn:alm:descriptor:expression:props.options:label:path:metadata.name
- urn:alm:descriptor:expression:props.options:value:path:metadata.name
- urn:alm:descriptor:com.tectonic.ui:validation:required
# Preview feature
- urn:alm:descriptor:enhance:preview:context.params.configmap
- urn:alm:descriptor:preview:resource:api:/kubernetes/${context.cluster}/api/v1/namespaces/${context.namespace}/configmaps?fieldSelector=metadata.name%3D${context.params.configmap}
- urn:alm:descriptor:preview:resource:path:items[0]
UI 中的工作方式:
- 用户从下拉框中选择 ConfigMap(例如
my-config)。
- 下拉框旁边会显示预览按钮。
- 单击预览按钮,从 Kubernetes API 获取所选 ConfigMap。
- 原始 YAML 内容会显示在带有语法高亮的预览面板中。
预览请求可以使用 GET 或 POST。POST 预览可以根据当前表单值构建
PipelineRun 或 TaskRun 请求,并显示服务器返回的
结果。
预览内容可以显示为:
- YAML 或其他资源表示形式。
- 包含主题和 HTML 正文的文章,例如渲染后的通知
消息。
预览用于在执行前检查结果。预览上下文中不可用的仅运行时变量可能仍处于未解析状态,因此预览应被视为参考,而不是最终执行输出的保证。
链接配置
链接配置会向特定字段添加可点击链接。当用户填写参数时需要快速访问相关指南、产品文档、外部参考页面或其他系统 URL 时,可以使用此配置。
链接可以与表单组件结合使用,也可以在仅元数据模式下使用;在仅元数据模式下,你只需添加帮助文本和链接,而无需更改字段的默认输入组件。
配置
# Enable an internal product link
- urn:alm:descriptor:enhance:docLink:productDoc
# Product link path. Product documentation pages are a common use case.
- urn:alm:descriptor:docLink:link:alauda-devops-pipelines/pipelines/how_to/configure_dynamic_forms.html
# Optional link tooltip label. The UI uses a built-in default when omitted.
- urn:alm:descriptor:docLink:label:en:Open guide
- urn:alm:descriptor:docLink:label:zh:Open guide
对于完整 URL 链接,请使用 external 链接类型,并提供完整的 http 或 https URL:
- urn:alm:descriptor:enhance:docLink:external
- urn:alm:descriptor:docLink:link:https://example.com/docs
- urn:alm:descriptor:docLink:label:en:External reference
- urn:alm:descriptor:docLink:label:zh:External reference
示例:为 Git 仓库 URL 字段添加指向参数指南的链接。
- path: params.gitURL
x-descriptors:
- urn:alm:descriptor:label:en:Git Repository URL
- urn:alm:descriptor:label:zh:Git Repository URL
- urn:alm:descriptor:description:en:Enter the source repository URL.
- urn:alm:descriptor:description:zh:Enter the source repository URL.
- urn:alm:descriptor:com.tectonic.ui:text
- urn:alm:descriptor:enhance:docLink:productDoc
- urn:alm:descriptor:docLink:link:alauda-devops-pipelines/pipelines/how_to/configure_dynamic_forms.html
- urn:alm:descriptor:docLink:label:en:Open parameter guide
- urn:alm:descriptor:docLink:label:zh:Open parameter guide
配置规则
- 一个字段只能使用一种链接类型:
productDoc 或 external。
productDoc 使用产品链接路径,例如 alauda-devops-pipelines/pipelines/how_to/configure_dynamic_forms.html。
external 仅接受完整的 http 或 https URL。
- 如果链接无效,或类型与链接值不匹配,UI 不会渲染该链接。
高级组件
在复杂的 CI/CD 场景中,以下高级表单组件可以帮助您处理更复杂的配置需求。
组合组件
在复杂的 CI/CD 场景中,您可能会遇到这样的情况:单个数组参数需要从多个不同来源(不同 API)收集数据。例如,workloads 参数可能需要同时包含“Deployments”和“StatefulSets”,而这两者需要从完全不同的 Kubernetes API 获取数据。
为实现这一目标,您可以使用组合组件(widgets:combine)。它允许您在 UI 中将单个参数拆分为多个相互独立的子表单控件(例如,用于选择资源类型的单选按钮,以及用于选择实际资源的选择框),然后在提交到 Pipeline 之前,通过 JavaScript 表达式将它们的值组合成最终的数组或 JSON 对象。
配置
# Declare the use of the combine widget
- urn:alm:descriptor:widgets:combine
# Parent combine logic: defines how to merge all sub-component values into the final parameter
# Available variable: items (contains all sub-component values)
# Example: (items.deployments || []).concat(items.statefulsets || []) - merge multiple arrays into one
- urn:alm:descriptor:combine:value.exp:<js-expression>
# Parent: define sub-components
- urn:alm:descriptor:combine:items:
- path: <sub-component-name-1>
x-descriptors:
# Child split logic: defines how to extract this sub-component's value from the parent for echo display
# Available variable: parent (the current parameter value)
# Example: (parent || []).filter(p => p.startsWith('deploy:')) - extract items with 'deploy:' prefix
- urn:alm:descriptor:combine:value.exp:<js-expression>
# ... other descriptors for this sub-component
- path: <sub-component-name-2>
x-descriptors:
# Child split logic: defines how to extract this sub-component's value from the parent for echo display
- urn:alm:descriptor:combine:value.exp:<js-expression>
# ... other descriptors for this sub-component
有关更多 js-expression 语法,请参阅 JavaScript 语法。
示例:配置多选参数 target_resources,允许用户从 Deployments 和 StatefulSets 中选择资源。最终参数值将是一个组合了两个 API 中所选资源的数组,并应用特定前缀以区分其类型(例如,["deploy:app-v1", "sts:db-v1"])。
- path: params.target_resources
x-descriptors:
# Declare the use of the combine widget
- urn:alm:descriptor:widgets:combine
# [Parent] Combine logic: concat the arrays from both 'deployments' and 'statefulsets' sub-components
- urn:alm:descriptor:combine:value.exp:(items.deployments || []).concat(items.statefulsets || [])
# Define sub-components
- urn:alm:descriptor:combine:items:
# Sub-component 1: Select Deployments
- path: deployments
x-descriptors:
# [Child 1] Split logic: extract items starting with 'deploy:' from the parent array
- urn:alm:descriptor:combine:value.exp:(parent || []).filter(p => p.startsWith('deploy:'))
- urn:alm:descriptor:label:en:Deployments
- urn:alm:descriptor:label:zh:Deployments
- urn:alm:descriptor:widgets:select
- urn:alm:descriptor:props:select:multiple
- urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/apis/apps/v1/namespaces/${context.namespace}/deployments
- urn:alm:descriptor:expression:props.options:path:items
- urn:alm:descriptor:expression:props.options:label:path:metadata.name
# Prepend 'deploy:' prefix
- urn:alm:descriptor:expression:props.options:value:path.exp:'deploy:'+$.metadata.name
# Sub-component 2: Select StatefulSets
- path: statefulsets
x-descriptors:
# [Child 2] Split logic: extract items starting with 'sts:' from the parent array
- urn:alm:descriptor:combine:value.exp:(parent || []).filter(p => p.startsWith('sts:'))
- urn:alm:descriptor:label:en:StatefulSets
- urn:alm:descriptor:label:zh:StatefulSets
- urn:alm:descriptor:widgets:select
- urn:alm:descriptor:props:select:multiple
- urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/apis/apps/v1/namespaces/${context.namespace}/statefulsets
- urn:alm:descriptor:expression:props.options:path:items
- urn:alm:descriptor:expression:props.options:label:path:metadata.name
# Prepend 'sts:' prefix
- urn:alm:descriptor:expression:props.options:value:path.exp:'sts:'+$.metadata.name
UI 中的工作方式:
-
用户会同时看到两个独立的多选框:“Deployments”和“StatefulSets”。
-
Deployments 框从 Deployment API 获取数据,StatefulSets 框从 StatefulSet API 获取数据。
-
当用户在 Deployments 中选择 dummy 和 alm,并在 StatefulSets 中选择 db-1 时,提交到 Task 的最终 target_resources 数组会自然组合为:
- name: target_resources
value:
- deploy:dummy
- deploy:alm
- sts:db-1
数组表格组件
数组表格组件(widgets:arrayTable)将字符串数组编辑为结构化行。当每个数组项包含多个业务值时,请使用此组件,例如 KEY=VALUE、name|protocol|description 或 JSON 字符串。
Pipeline 参数仍然是 string[]。表单只会改变每个项的编辑方式,并在 Pipeline 启动前将每一行转换回一个字符串。
- path: params.buildArgs
x-descriptors:
- urn:alm:descriptor:widgets:arrayTable
- urn:alm:descriptor:arrayTable:separator:=
- urn:alm:descriptor:arrayTable:items:
- path: key
x-descriptors:
- urn:alm:descriptor:label:en:Key
- urn:alm:descriptor:com.tectonic.ui:text
- path: value
x-descriptors:
- urn:alm:descriptor:label:en:Value
- urn:alm:descriptor:com.tectonic.ui:text
对于 MESSAGE=left=middle=right,第一个分隔符用于分隔键,剩余文本会保留在值中。这样可以避免最后一个字段中的其他分隔符丢失。
布局会根据行字段数量进行调整:
- 一个字段:显示为全宽行,不单独显示表头。
- 两个字段:字段以列的形式显示,并共享一个表头。
- 多于两个字段:字段垂直显示,每行带有标签。
对于无法通过分隔符表示的 JSON 或其他格式,请定义 urn:alm:descriptor:arrayTable:parse.exp: 和 urn:alm:descriptor:arrayTable:stringify.exp:。解析表达式会接收 parent(存储的字符串)和 context,并且必须返回一个包含所有已配置项路径的对象。字符串化表达式会接收 items(当前行值)和 context,并且必须返回一个字符串。
例如,可以将 JSON 数组项编辑为两个字段,然后再转换回存储的字符串:
- path: params.jsonItems
x-descriptors:
- urn:alm:descriptor:widgets:arrayTable
- urn:alm:descriptor:arrayTable:items:
- path: key
x-descriptors:
- urn:alm:descriptor:label:en:Key
- urn:alm:descriptor:com.tectonic.ui:text
- path: value
x-descriptors:
- urn:alm:descriptor:label:en:Value
- urn:alm:descriptor:com.tectonic.ui:text
- 'urn:alm:descriptor:arrayTable:parse.exp:parse(parent)'
- 'urn:alm:descriptor:arrayTable:stringify.exp:stringify(items)'
无效的转换结果会显示为表单错误,不会静默覆盖原始值。
对于简单的独立字符串列表,请勿使用数组表格。此时应使用标准数组输入或 tagsInput。
内联表单组件(widgets:inlineForm)会在当前参数字段中显示所选资源的参数。当一次选择决定下一组输入时,此组件非常有用,例如先选择消息模板,然后输入该模板的变量。
内联表单可以从 API 加载资源,也可以从当前表单上下文中已有的值加载资源。描述符会标识:
- 要加载的资源。
- 包含所选对象的资源路径。
- 资源的参数路径和描述符路径。
- 如何将嵌套表单值转换为父参数值,以及如何执行反向转换。
示例:
- path: params.templateValues
x-descriptors:
- urn:alm:descriptor:widgets:inlineForm
- urn:alm:descriptor:inlineForm:resource:api:/kubernetes/${context.cluster}/api/v1/namespaces/kube-public/configmaps?fieldSelector=metadata.name%3D${context.params.templateName}
- urn:alm:descriptor:inlineForm:resource:path:items[0]
- 'urn:alm:descriptor:inlineForm:params:path.exp:parse($.metadata.annotations["style.tekton.dev/descriptors"] || "")?.map(d => ({type: "string", name: d.path.split("params.")[1]}))'
- 'urn:alm:descriptor:inlineForm:stringify:$?.length ? stringify($.reduce((acc, cur) => { acc[cur.name] = cur.value; return acc; }, {})) : ""'
- 'urn:alm:descriptor:inlineForm:parse:Object.entries(parse($ || "") || {}).map(([name, value]) => ({name, value}))'
当资源或其参数发生变化时,内联表单会针对当前上下文进行刷新。嵌套验证结果会传递到父字段,因此 Pipeline 无法在内联配置无效的情况下提交。
内联表单可以与预览组件结合使用。例如,用户可以配置所选模板的变量,然后预览渲染结果,而无需离开 Pipeline 表单。
完整示例
在 Task 中配置仅元数据动态表单
示例:添加标签、描述、工具提示和字段链接,而无需声明表单组件。
效果:UI 会保留每个参数的默认输入行为,仅应用已配置的元数据和链接。
apiVersion: tekton.dev/v1
kind: Task
metadata:
name: metadata-only-demo-task
namespace: <your namespace>
annotations:
style.tekton.dev/descriptors: |
- path: params.mailSubject
x-descriptors:
- urn:alm:descriptor:label:en:Mail Subject
- urn:alm:descriptor:label:zh:Mail Subject
- urn:alm:descriptor:description:en:Used to render the notification title.
- urn:alm:descriptor:description:zh:Used to render the notification title.
- urn:alm:descriptor:tooltip:en:Rendered at runtime.
- urn:alm:descriptor:tooltip:zh:Rendered at runtime.
- path: params.runtimeNote
x-descriptors:
- urn:alm:descriptor:label:en:Runtime Note
- urn:alm:descriptor:label:zh:Runtime Note
- urn:alm:descriptor:description:en:No component descriptor is configured for this parameter.
- urn:alm:descriptor:description:zh:No component descriptor is configured for this parameter.
- urn:alm:descriptor:tooltip:en:The UI should keep the parameter entry's default rendering component.
- urn:alm:descriptor:tooltip:zh:The UI should keep the parameter entry's default rendering component.
- urn:alm:descriptor:enhance:docLink:productDoc
- urn:alm:descriptor:docLink:link:alauda-devops-pipelines/pipelines/how_to/configure_dynamic_forms.html
- urn:alm:descriptor:docLink:label:en:Open form guide
- urn:alm:descriptor:docLink:label:zh:Open form guide
spec:
params:
- name: mailSubject
type: string
default: Metadata-only subject
- name: runtimeNote
type: string
default: This parameter has no explicit form component descriptor.
steps:
- name: print-values
image: ubuntu
env:
- name: MAIL_SUBJECT
value: $(params.mailSubject)
- name: RUNTIME_NOTE
value: $(params.runtimeNote)
script: |
#!/usr/bin/env sh
set -eu
echo "mailSubject=${MAIL_SUBJECT}"
echo "runtimeNote=${RUNTIME_NOTE}"
在 Task 中配置动态表单
示例:为 Task 的 image 参数提供用于选择命名空间的下拉框。
效果:当用户通过 UI 编排 Pipeline 或 TaskRun 时,此 Task 的 namespace 参数支持通过下拉框选择命名空间。
apiVersion: tekton.dev/v1
kind: Task
metadata:
name: demo-task
namespace: <your namespace>
annotations:
style.tekton.dev/descriptors: |
- path: params.namespace
x-descriptors:
- urn:alm:descriptor:label:en:namespace
- urn:alm:descriptor:label:zh:namespace(zh)
- urn:alm:descriptor:com.tectonic.ui:select
- urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces
- urn:alm:descriptor:expression:props.options:path:items
- urn:alm:descriptor:expression:props.options:label:path:metadata.name
- urn:alm:descriptor:expression:props.options:value:path:metadata.name
- urn:alm:descriptor:com.tectonic.ui:validation:required
spec:
params:
- name: namespace
type: string
steps:
- name: demo
image: ubuntu
script: |
#!/bin/sh
pwd
在 Pipeline 中配置动态表单
示例:为 Pipeline 的 target-namespace 参数提供用于选择命名空间的下拉框。
效果:当用户通过 UI 触发 Pipeline,或需要在其他资源(Trigger、TriggerTemplate)中关联此 Pipeline 并配置运行时参数时,target-namespace 参数支持通过下拉框选择命名空间。
apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
annotations:
style.tekton.dev/descriptors: |
- path: params.target-namespace
x-descriptors:
- urn:alm:descriptor:label:en:target-namespace
- urn:alm:descriptor:label:zh:target-namespace(zh)
- urn:alm:descriptor:com.tectonic.ui:select
- urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces
- urn:alm:descriptor:expression:props.options:label:path:metadata.name
- urn:alm:descriptor:expression:props.options:value:path:metadata.name
- urn:alm:descriptor:expression:props.options:path:items
- urn:alm:descriptor:com.tectonic.ui:validation:required
name: demo-pipelines
namespace: <your namespace>
spec:
params:
- name: target-namespace
type: string
tasks:
- name: kubectl
taskRef:
resolver: hub
params:
- name: kind
value: task
- name: catalog
value: catalog
- name: name
value: kubectl
- name: version
value: "0.1"
故障排除
- 表单未显示或配置未生效:检查
style.tekton.dev/descriptors 的 YAML 格式是否正确,确认 path 是否根据需要配置为 params.parameter-name、workspaces.workspace-name 或 results.result-name,并验证每个描述符是否以 - urn:alm:descriptor: 开头
- 动态选项未加载:确认 API 路径是否正确,检查当前用户是否有权访问指定的 API 资源,验证
path、label 和 value 配置是否指向返回数据中存在的字段
- 默认值未生效:确认固定默认值使用
expression:props.default:value 格式,表达式默认值使用 === 而不是 =,并检查表达式中的变量(option、index、length、context)拼写是否正确
- 上下文变量未解析:验证变量名称是否正确(例如使用
context.namespace 而不是 context.namespaces),确认变量是否用于支持表达式的描述符中,并检查 JavaScript 表达式语法是否存在错误
- 链接未显示:确认
enhance:docLink 使用的是 productDoc 或 external,验证是否存在 docLink:link,并确保外部链接使用完整的 http 或 https URL
- 字段已显示但无法编辑:检查是否为该字段配置了
urn:alm:descriptor:com.tectonic.ui:disabled
- 高级控件未显示:检查描述符路径是否与现有参数匹配,是否具备所需的控件能力,以及当前条目是否支持配置的控件。使用 Basic 表单单独验证底层值。
- 数组表格无法渲染:检查
arrayTable:items 是否至少包含一个具有唯一且非空 path 的项。无效的项定义会回退到常规数组表单。
- 数组值更改未保存:检查分隔符或
parse.exp 和 stringify.exp 表达式。转换失败或嵌套字段无效时,不会覆盖原始数组值。
- 内联表单为空:检查所选资源、资源路径、参数路径和描述符路径是否能在当前上下文中解析。同时验证当前用户是否可以读取资源 API。
- 预览结果与最终运行结果不同:检查预览是否依赖仅在运行时可用的变量。当执行上下文不可用时,预览结果仅供参考。
- Workspace 或 Result 控件未改变:Workspace 和 Result 描述符仅提供显示元数据。必填、可选和绑定行为仍由 Pipeline 声明提供。