Как настроить динамические формы

Содержание

Обзор функции Сценарии использования Быстрый старт Базовая конфигурация формы Метка формы Описание формы Подсказка-заполнитель Всплывающая подсказка помощи Отключенное состояние формы Поддерживаемые типы полей Текстовое поле Многострочное текстовое поле Ввод тегов Радиокнопки Переключатель Редактор YAML Выпадающий список Базовая конфигурация содержимого Конфигурация динамических опций через API Значения параметров по умолчанию Валидация формы Обязательная валидация Валидация длины Валидация числового диапазона Валидация по регулярному выражению Примеры использования Настройка динамических форм в Task Настройка динамических форм в Pipeline Устранение неполадок

Обзор функции

Функция конфигурации динамических форм позволяет декларативно настроить удобный интерактивный интерфейс для ресурсов, таких как Pipeline и Task. Без написания фронтенд-кода, просто добавив конфигурацию style.tekton.dev/descriptors в annotations ресурса, вы можете добиться:

Автоматической генерации форм: Автоматически создавать интерактивные формы для параметров ресурса, обеспечивая лучший опыт при оркестрации и выполнении Pipelines и Tasks.
Поддержки различных компонентов: Предоставляет различные компоненты формы, такие как текстовые поля, селекторы, переключатели, редакторы YAML и др.
Валидации полей: Встроенные правила валидации для обеспечения соответствия ввода пользователя требованиям.
Динамической загрузки данных: Поддерживает динамическую загрузку данных опций через API.

Сценарии использования

Оркестрация/выполнение Pipeline: Позволяет пользователям заполнять параметры, такие как namespace и secrets, через удобные формы при оркестрации или запуске Pipeline.
Повторное использование Task: Предоставляет значения по умолчанию, варианты выбора и валидацию для общих параметров на уровне шаблона Task или Pipeline.
Выбор из нескольких окружений: Динамически запрашивает доступные окружения или конфигурации через API и использует их как варианты выбора.

Быстрый старт

Базовая структура конфигурации

Все конфигурации задаются через поле 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
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)

Базовая конфигурация формы

Метка формы

# Метка для формы
- urn:alm:descriptor:label:en:English Name
- urn:alm:descriptor:label:zh:Chinese name

Описание формы

# Описание для формы
- urn:alm:descriptor:description:en:English Description
- urn:alm:descriptor:description:zh:Chinese Description

Подсказка-заполнитель

# Заполнитель для формы
- urn:alm:descriptor:placeholder:en:This is a Placeholder
- urn:alm:descriptor:placeholder:zh:This is a Placeholder

Всплывающая подсказка помощи

# Всплывающая подсказка для формы
- urn:alm:descriptor:tooltip:en:This is a Help Tip
- urn:alm:descriptor:tooltip:zh:This is a Help Tip

Отключенное состояние формы

# Форма отключена или нет
- urn:alm:descriptor:com.tectonic.ui:disabled

Поддерживаемые типы полей

Текстовое поле

# 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

Радиокнопки

# value: string
- urn:alm:descriptor:com.tectonic.ui:radio:valueA
- urn:alm:descriptor:com.tectonic.ui:radio:valueB

Переключатель

# value: boolean
- urn:alm:descriptor:com.tectonic.ui:booleanSwitch

# Отображение значения в строку
# При включенном переключателе значение True
- urn:alm:descriptor:props:booleanSwitch:true:True
# При выключенном переключателе значение 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
# Опции
- urn:alm:descriptor:props:select:options:valueA
- urn:alm:descriptor:props:select:options:valueB
# Установить множественный выбор
# value: array
- urn:alm:descriptor:props:select:multiple
# Разрешить ввод вручную в качестве опций
- urn:alm:descriptor:props:select:allowCreate
# Разрешить очистку выбора
- urn:alm:descriptor:props:select:clearable

Конфигурация динамических опций через API

Когда элементы формы должны динамически загружать доступные опции в зависимости от текущего окружения (например, доступные namespaces, secrets и т.д.), можно использовать динамическую конфигурацию API для получения опций из бэкенд-интерфейсов в реальном времени.

В этом режиме URL API обычно комбинируются с контекстными переменными для динамического построения пути запроса на основе текущего кластера, namespace, проекта или заполненных параметров пользователя. Например:

# Использование переменной ${context.cluster} в URL для динамического получения списка namespaces текущего кластера
- urn:alm:descriptor:expression:props.options:api:apiPath
- urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces

Доступные контекстные переменные

В динамических API-путях можно использовать ${variable} для ссылки на информацию контекста во время выполнения.

Общие контекстные переменные

Переменная	Описание
`${context.cluster}`	Текущее имя кластера
`${context.namespace}`	Текущий namespace
`${context.project}`	Текущий проект
`${current.search}`	Получить текущий ввод поиска из выпадающего списка

Контекстные переменные, связанные с Pipeline/Task

Переменная	Описание
`${context.params}`	Объект параметров, например, `${context.params.repo}` ссылается на текущее значение параметра `repo` в форме

Эти переменные обычно используются вместе с URL API для динамического построения адресов запросов в разных окружениях, что позволяет реализовать логику загрузки опций с учётом окружения. Например:

- 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 (например, ключевые слова поиска или фильтры), можно использовать:

# Добавить параметр запроса с именем "search" и значением из пользовательского ввода
- 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

Продвинутое использование: Поддерживаются JavaScript-выражения, например:

${context.params.map(p => p.name).join(',')}

Значения параметров по умолчанию

Фиксированное значение по умолчанию

- urn:alm:descriptor:expression:props.default:default-value

Динамическое значение по умолчанию на основе выражения

Доступные переменные:

option: Исходные данные опции
index: Индекс опции
length: Общее количество опций

context: Параметры контекста

# Выбрать опции с определёнными метками
- urn:alm:descriptor:expression:props.default.exp:option.metadata.labels['default']==='true'
# По умолчанию выбрать первый элемент
- urn:alm:descriptor:expression:props.default.exp:index === 0
# По умолчанию выбрать последний элемент
- urn:alm:descriptor:expression:props.default.exp:index === length - 1
# По умолчанию выбрать, если опция одна
- urn:alm:descriptor:expression:props.default.exp:length === 1
# По умолчанию выбрать текущий namespace
- urn:alm:descriptor:expression:props.default:${context.namespace}
# Сложные условия
- urn:alm:descriptor:expression:props.default.exp:option.metadata.name.includes('test') && option.status.conditions.some(c => c.status==='True')

INFO

Для правил синтаксиса условных выражений в сложных сценариях смотрите JavaScript syntax.

Валидация формы

Поддерживается настройка различных правил валидации, можно применять несколько правил одновременно.

Обязательная валидация

- urn:alm:descriptor:com.tectonic.ui:validation:required

Валидация длины

# Минимальная длина
- urn:alm:descriptor:com.tectonic.ui:validation:minLength:6
# Максимальная длина
- urn:alm:descriptor:com.tectonic.ui:validation:maxLength:64

Валидация числового диапазона

# Минимальное значение (для числовых типов)
- urn:alm:descriptor:com.tectonic.ui:validation:minimum:1
# Максимальное значение
- urn:alm:descriptor:com.tectonic.ui:validation:maximum:100

Валидация по регулярному выражению

# Положительное целое число
- urn:alm:descriptor:com.tectonic.ui:validation:pattern:[1-9]\d*
# Имя ресурса Kubernetes (строчные буквы, цифры, дефисы)
- 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:Не менее 8 символов, включая буквы и цифры.
    - 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

Примеры использования

Настройка динамических форм в Task

Пример: Предоставить выпадающий список для выбора namespace для параметра image Task.

Эффект: При оркестрации Pipeline или TaskRun через UI параметр namespace этого 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

Пример: Предоставить выпадающий список для выбора namespace для параметра target-namespace Pipeline.

Эффект: При запуске Pipeline через UI или при связывании этого pipeline с другими ресурсами (Trigger, TriggerTemplate) и настройке параметров времени выполнения параметр target-namespace поддерживает выбор из списка 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"

Устранение неполадок

Форма не отображается или конфигурация не работает: Проверьте корректность YAML формата style.tekton.dev/descriptors, убедитесь, что path настроен как params.parameter-name, проверьте, что каждый дескриптор начинается с - urn:alm:descriptor:
Динамические опции не загружаются: Убедитесь, что путь API правильный, проверьте, есть ли у текущего пользователя права доступа к указанному API ресурсу, проверьте, что настройки path, label и value указывают на существующие поля в возвращаемых данных
Значение по умолчанию не применяется: Убедитесь, что фиксированное значение по умолчанию использует формат expression:props.default:value, выражение по умолчанию использует === вместо =, проверьте правильность написания переменных (option, index, length, context) в выражении
Контекстные переменные не разрешаются: Проверьте правильность имён переменных (например, context.namespace, а не context.namespaces), убедитесь, что переменные используются в дескрипторах, поддерживающих выражения, проверьте отсутствие ошибок в синтаксисе JavaScript выражений

#Как настроить динамические формы

#Содержание

#Обзор функции

#Сценарии использования

#Быстрый старт

#Базовая конфигурация формы

#Метка формы

#Описание формы

#Подсказка-заполнитель

#Всплывающая подсказка помощи

#Отключенное состояние формы

#Поддерживаемые типы полей

#Текстовое поле

#Многострочное текстовое поле

#Ввод тегов

#Радиокнопки

#Переключатель

#Редактор YAML

#Выпадающий список

#Базовая конфигурация содержимого

#Конфигурация динамических опций через API

#Значения параметров по умолчанию

#Валидация формы

#Обязательная валидация

#Валидация длины

#Валидация числового диапазона

#Валидация по регулярному выражению

#Примеры использования

#Настройка динамических форм в Task

#Настройка динамических форм в Pipeline

#Устранение неполадок