Alauda DevOps Pipelines Docs
  • Русский

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

    Содержание

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

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

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

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

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

    • Оркестрация/выполнение Pipeline: Позволяет пользователям заполнять параметры, такие как namespace и секреты, через удобные формы при оркестрации или запуске 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

    Переключатель (Switch)

    # 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

    Выпадающий список (Select Box)

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

    # 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, секреты и т.д.), можно использовать динамическую конфигурацию 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

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