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

#Обзор функциональности

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

• Динамическую генерацию формы: автоматически создавайте интерактивные формы для параметров ресурса, обеспечивая более удобный опыт при оркестрации и запуске Pipeline и Task.
• Поддержку богатого набора компонентов: предоставляет различные элементы формы, такие как текстовые поля, селекторы, переключатели, 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)

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

#Подпись формы

# 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

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

#Текстовый ввод

# 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

#Radio

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

#Switch

# 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 Editor

# 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

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

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

# 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

Доступные context variables

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

• Общие context variables

• Context variables, связанные с Pipeline/Task

Эти переменные обычно используются вместе с 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, чтобы указать, как извлекать массив options из структуры.

Настройка полей сопоставления label и value для options

Если возвращаемый объект данных сложный и требуется указать внутренние поля как "display name" и "option value", можно использовать:

- urn:alm:descriptor:expression:props.options:label:path:metadata.name
- urn:alm:descriptor:expression:props.options:value:path:metadata.name

Когда API возвращает простой массив string[], эта конфигурация не требуется.

Настройка параметров запроса API

Если нужно передать в запрос API параметры query string (например, поисковые ключевые слова или фильтры), можно использовать:

# 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

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

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

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

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

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

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

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

• option: исходные данные option

• index: индекс option

• length: общее количество options

• 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

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

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

Пример: предоставление выпадающего списка для выбора namespaces для параметра 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

Пример: предоставление выпадающего списка для выбора namespaces для параметра 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, проверьте, что каждый descriptor начинается с - urn:alm:descriptor:
• Динамические options не загружаются: убедитесь, что путь API указан верно, проверьте, есть ли у текущего пользователя права на доступ к указанному API resource, убедитесь, что конфигурации path, label и value указывают на поля, которые существуют в возвращаемых данных
• Значение по умолчанию не применяется: убедитесь, что фиксированное значение по умолчанию использует формат expression:props.default:value, а значение по умолчанию на основе выражения использует === вместо =, проверьте правильность написания переменных (option, index, length, context) в выражении
• Context variables не разрешаются: проверьте, что имена переменных указаны верно (например, context.namespace, а не context.namespaces), убедитесь, что переменные используются в descriptors, которые поддерживают выражения, проверьте, нет ли ошибок в синтаксисе JavaScript-выражения