#Настройка обзора задач с помощью шаблонов

В этом руководстве показано, как использовать шаблоны на основе ConfigMap для отображения расширенных HTML-отчетов во вкладке Overview для ваших TaskRuns и PipelineRuns.

Вместо того чтобы записывать полный HTML- или Markdown-отчет в один результат Task, ваши Tasks генерируют небольшие структурированные метрики, а UI использует шаблон из ConfigMap для отображения итогового обзора.

Используйте это руководство, если:

• Вы хотите получить единый, аккуратный обзор для Task (например, сводку сканирования кода).
• Ваш Markdown-обзор приближается к или превышает эффективный лимит размера результата Task.
• Вы хотите повторно использовать один и тот же макет для многих Tasks или кластеров.

Отрисовка шаблона — это альтернатива overview-markdown. Если Task всё ещё выводит результат с именем overview-markdown, UI предпочитает этот Markdown и пропускает отрисовку шаблона.

#Предварительные требования

• Установленные Tekton Pipelines в вашем кластере.
• Права на создание ConfigMaps в общем пространстве имён шаблонов kube-public.

#Как это работает

1. Ваш Task генерирует один или несколько результатов, содержащих метрики или сводные данные.
2. Метаданные вашего Task включают аннотации, которые сообщают UI:
   • Какой ConfigMap использовать в качестве шаблона (через селектор меток).
   • Какие результаты Task нужно считать и передать в шаблон.
3. UI:
   • Проверяет, есть ли у TaskRun результат с именем overview-markdown. Если есть, он отображает этот Markdown и останавливается.
   • В противном случае читает аннотации шаблона из TaskRun.
   • Находит подходящий ConfigMap и загружает template.ejs.
   • Считывает объявленные результаты из TaskRun и объединяет их в один JSON-пейлоад.
   • Выполняет EJS шаблон с этим пейлоадом и отображает сгенерированный HTML во вкладке Overview.

#Шаги

#1. Выберите между Markdown и шаблонами

Используйте результат overview-markdown, если:

• Содержимое короткое и легко укладывается в лимиты размера результата.
• Вам нужна очень простая форматировка.

Используйте шаблон ConfigMap, если:

• Вам нужен более сложный макет (колонки, бейджи, индикаторы прогресса и т.д.).
• У вас уже есть структурированные метрики и вы хотите более красивое представление.
• Вы хотите, чтобы один макет обзора использовался несколькими Tasks.

Если настроены оба варианта, выигрывает overview-markdown. Вы можете просмотреть вывод шаблона, просто не записывая ничего в результат overview-markdown.

#2. Создайте ConfigMap с шаблоном

Создайте ConfigMap, содержащий ваш EJS шаблон и метки, которые идентифицируют, к какому Task он относится.

EJS — это простой язык шаблонов, который позволяет генерировать HTML-разметку с помощью обычного JavaScript. Без навязанных правил организации. Без изобретения заново итераций и управления потоком. Просто обычный JavaScript. Подробнее смотрите:

• EJS
• Документация EJS
• mde/ejs на Github

Пример:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-task-0.1-overview-template
  # configmap должен находиться в пространстве имён kube-public
  namespace: kube-public
  labels:
    # Для какого Task этот шаблон
    style.tekton.dev/overview-template-task: my-task
    # Версия пары Task/шаблон
    style.tekton.dev/overview-template-task-version: "0.1"
    # Какой движок должен использовать UI
    style.tekton.dev/overview-template-engine: ejs
data:
  template.ejs: |
    <%
      const m = metrics || {};
      const asNumber = (value, fallback = 0) => {
        const parsed = Number(value);
        return Number.isFinite(parsed) ? parsed : fallback;
      };
    %>

    <div style="font:12px sans-serif;margin:8px 0">
      <div style="display:flex;align-items:center;margin-bottom:6px">
        <strong>My Task Summary</strong>
        <% if (m.report_url) { %>
          <a href="<%= m.report_url %>" target="_blank" rel="noreferrer" style="margin-left:8px">
            View report
          </a>
        <% } %>
        <span style="margin-left:auto;color:#5c1">
          Status: <%= m.status || "UNKNOWN" %>
        </span>
      </div>

      <div style="display:flex;flex-wrap:wrap;gap:6px;color:#666">
        <div style="flex:1;min-width:110px">
          <b><%= asNumber(m.total) %></b> Total
        </div>
        <div style="flex:1;min-width:110px">
          <b><%= asNumber(m.passed) %></b> Passed
        </div>
        <div style="flex:1;min-width:110px">
          <b><%= asNumber(m.failed) %></b> Failed
        </div>
      </div>
    </div>

Основные моменты:

• Имя файла шаблона всегда template.ejs.
• UI внедряет переменные из результатов в шаблон.
• Вы можете использовать обычный синтаксис EJS (<% %>, <%= %>) для простой логики и форматирования.

#3. Добавьте результат в ваш Task

Определите результат в вашем Task, который будет содержать метрики, используемые шаблоном.

Пример Task:

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: my-task
spec:
  results:
    - name: TASK_METRICS
      type: object
      description: Сводные метрики для шаблона обзора.
      properties:
        total: {}
        passed: {}
        failed: {}
        status: {}
        report_url: {}
  steps:
    - name: run-and-collect-metrics
      image: <your-image>
      script: |
        #!/usr/bin/env sh
        set -eu

        # TODO: замените на реальные значения
        total=10
        passed=9
        failed=1
        status="OK"
        report_url="https://example.com/report/123"

        printf '{"total": "%s", "passed": "%s", "failed": "%s", "status": "%s", "report_url": "%s"}' \
          "$total" \
          "$passed" \
          "$failed" \
          "$status" \
          "$report_url" \
          > "$(results.TASK_METRICS.path)"

Рекомендации:

• Держите результат маленьким и плоским. Используйте простые поля, такие как счётчики, проценты, статус и URL.
• Не встраивайте большие текстовые блоки.
• Если используете объектный результат, убедитесь, что шаг записывает валидный JSON (без лишних запятых, с правильным экранированием).

#4. Аннотируйте Task для привязки к шаблону

Используйте аннотации в Task, чтобы указать UI, какой шаблон использовать и какие результаты передавать.

Пример с одним результатом:

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: my-task
  annotations:
    # 1) Где найти ConfigMap с шаблоном
    style.tekton.dev/overview-template-selector: >
      style.tekton.dev/overview-template-task=my-task,
      style.tekton.dev/overview-template-task-version=0.1

    # 2) Какие результаты Task читать из TaskRun
    #    Здесь: expose TASK_METRICS как "metrics" в template.ejs
    #    Если псевдоним не указан, используется имя результата (TASK_METRICS).
    style.tekton.dev/overview-template-result-key: TASK_METRICS:metrics
    
spec:
  results:
    - name: TASK_METRICS
      type: object
  steps:
    - name: run-and-collect-metrics
      image: <your-image>
      # ...

Концептуально UI сформирует пейлоад:

{
  "metrics": {
    "total": "10",
    "passed": "9",
    "failed": "1",
    "status": "OK",
    "report_url": "https://example.com/report/123"
  }
}

Затем выполнит template.ejs с этим пейлоадом, чтобы вы могли использовать metrics.total, metrics.status и т.д.

Вы можете объединять несколько результатов Task в одну отрисовку шаблона. Это полезно, когда:

• Один результат содержит метрики.
• Другой результат содержит URL на полный отчет.

Пример:

metadata:
  annotations:
    style.tekton.dev/overview-template-selector: >
      style.tekton.dev/overview-template-task=sonarqube-scanner,
      style.tekton.dev/overview-template-task-version=0.5

    # Несколько результатов, разделённых запятыми
    # Псевдонимы:
    # - CODE_SCAN_METRICS -> metrics
    # - SCAN_RESULT_URL   -> SCAN_RESULT_URL (без псевдонима)
    # - SCAN_PROJECT      -> SCAN_PROJECT (без псевдонима)
    style.tekton.dev/overview-template-result-key: |
      CODE_SCAN_METRICS:metrics,SCAN_RESULT_URL,SCAN_PROJECT

UI сформирует пейлоад, похожий на:

{
  "metrics": {
    "bugs": "2",
    "vulnerabilities": "1"
  },
  "SCAN_RESULT_URL": "https://devops-sonar.example.net/dashboard?id=project&branch=main",
  "SCAN_PROJECT": ["foo", "bar"]
}

#5. Запустите Task и проверьте вкладку Overview

1. Примените ConfigMap и Task в вашем кластере.

2. Создайте TaskRun или PipelineRun, использующий этот Task, например:

   apiVersion: tekton.dev/v1
   kind: TaskRun
   metadata:
     name: my-task-run
   spec:
     taskRef:
       name: my-task

3. Дождитесь завершения выполнения.

4. Откройте выполнение в UI и выберите вкладку Overview.

Если всё настроено правильно, вы увидите HTML, сгенерированный вашим шаблоном.

Если Task также выводит overview-markdown, вместо шаблона будет показан Markdown.

#Советы и рекомендации

• Предпочитайте маленькие результаты с метриками. Рассматривайте результаты как компактное резюме.
• Держите логику шаблона простой. Сосредоточьтесь на презентации, а не на бизнес-логике. Избегайте тяжёлых вычислений в шаблоне.
• Обрабатывайте отсутствие данных защитно. Используйте значения по умолчанию в шаблоне, чтобы отсутствие полей не приводило к сбоям при отрисовке.

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

#Во вкладке Overview ничего не отображается

• Выводит ли Task пустой overview-markdown?
  • Если да, UI покажет этот пустой Markdown и проигнорирует шаблоны. Вы можете увидеть вывод шаблона, просто не записывая ничего в результат overview-markdown.
• Содержит ли TaskRun результаты, указанные в overview-template-result-key?
  • Проверьте YAML TaskRun и посмотрите .status.results.
• Соответствует ли селектор в overview-template-selector ровно одному ConfigMap в пространстве имён kube-public?
  • Проверьте с помощью kubectl get configmap -l <your-selector> -n kube-public.

#Шаблон отрисовывается, но данные пустые или неправильные

• Если вы используете объектный результат, убедитесь, что результат валиден и содержит поля, ожидаемые шаблоном.
• Проверьте, что имена в overview-template-result-key точно совпадают с именами результатов Task.

#Лимиты размера результата или сообщения о завершении

• Удалите из результатов несущественные поля.
• Помещайте подробные отчёты по файлам в логи или внешние системы, а в результат включайте только сводные числа и URL.
• Помните, что каждый Task всё ещё делит общий лимит сообщения о завершении между всеми шагами и результатами.
• Изменение лимита результата

#Выбран неправильный шаблон

• Убедитесь, что overview-template-selector достаточно специфичен (например, включает имя Task и версию).
• Избегайте повторного использования одинаковых меток для разных шаблонов.
• Если несколько ConfigMaps соответствуют селектору, уточните метки, чтобы выбрать только один ConfigMap.

Когда у вас есть ConfigMap с шаблоном, результаты метрик и правильные аннотации Task, вы можете создавать переиспользуемые, версионированные макеты обзора Task без изменения самого UI.