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

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

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

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

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

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

Содержание

Предварительные требования Как это работает Шаги 1. Выберите между Markdown и шаблонами 2. Создайте ConfigMap шаблона 3. Добавьте результат в ваш Task 4. Добавьте annotations в Task, чтобы связать его с шаблоном 5. Запустите Task и проверьте вкладку Overview Советы и соглашения Устранение неполадок Во вкладке Overview ничего не отображается Шаблон отрисовывается, но данные пустые или неверные Лимиты размера результата или termination message Выбран неверный шаблон

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

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

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

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

Шаги

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

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

Контент короткий и его легко удержать в пределах лимитов размера результата.
Вам нужно только очень простое форматирование.

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

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

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

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

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

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

Пример:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-task-0.1-overview-template
  # configmap should be in kube-public namespace
  namespace: kube-public
  labels:
    # Which Task this template is for
    style.tekton.dev/overview-template-task: my-task
    # Version of the Task/template pairing
    style.tekton.dev/overview-template-task-version: "0.1"
    # Which engine the UI should use
    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 result, который будет содержать метрики, используемые шаблоном.

Пример Task:

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: my-task
spec:
  results:
    - name: TASK_METRICS
      type: object
      description: Summary metrics for the overview template.
      properties:
        total: {}
        passed: {}
        failed: {}
        status: {}
        report_url: {}
  steps:
    - name: run-and-collect-metrics
      image: <your-image>
      script: |
        #!/usr/bin/env sh
        set -eu

        # TODO: replace these with real values
        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)"

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

Держите результат небольшим и плоским. Используйте простые поля, такие как счетчики, проценты, статус и URLs.
Не встраивайте большие текстовые блоки.
Если вы используете object result, убедитесь, что шаг записывает валидный JSON (без завершающих запятых, с корректными кавычками).

4. Добавьте annotations в Task, чтобы связать его с шаблоном

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

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

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: my-task
  annotations:
    # 1) Where to find the template 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) Which Task result(s) to read from the TaskRun
    #    Here: expose TASK_METRICS as "metrics" in template.ejs
    #    If you do not specify an alias key, the result name is used (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

    # Multiple results, separated by commas
    # Aliases:
    # - CODE_SCAN_METRICS -> metrics
    # - SCAN_RESULT_URL   -> SCAN_RESULT_URL (no alias)
    # - SCAN_PROJECT      -> SCAN_PROJECT (no alias)
    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

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

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

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

Дождитесь завершения запуска.
Откройте запуск в UI и выберите вкладку Overview.

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

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

Советы и соглашения

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

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

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

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

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

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

Лимиты размера результата или termination message

Удалите из результатов все необязательные поля.
Перенесите подробные отчеты по каждому файлу в logs или внешнюю систему, а в результатах оставьте только сводные числа и URLs.
Помните, что каждый Task по-прежнему использует общий бюджет termination message для всех шагов и результатов.
Изменить лимит результата

Выбран неверный шаблон

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

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

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

#Содержание

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

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

#Шаги

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

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

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

#4. Добавьте annotations в Task, чтобы связать его с шаблоном

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

#Советы и соглашения

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

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

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

#Лимиты размера результата или termination message

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