#Написание Tasks для Tekton Hub

#Overview

В этом руководстве рассматриваются конкретные требования и лучшие практики создания Tasks, которые работают с каталогами Tekton Hub. Основное внимание уделяется метаданным, валидации и стандартам, специфичным для Hub.

#Требования Tekton Hub

#Task против ClusterTask

⚠️ CRITICAL: ClusterTask УСТАРЕЛ и УДАЛЕН в Tekton Pipelines версии 1.0 и выше. НЕ используйте ClusterTask.

• Task: ЕДИНСТВЕННЫЙ поддерживаемый тип ресурса для каталогов Hub
• ClusterTask: ❌ УДАЛЕН в Tekton версии 1.0 и выше — не работает

#Миграция с ClusterTask

# СТАРЫЙ - ClusterTask (БОЛЬШЕ НЕ РАБОТАЕТ)
apiVersion: tekton.dev/v1beta1
kind: ClusterTask
metadata:
  name: buildah

# НОВЫЙ - Task (Требуется для Hub)
apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: buildah
  namespace: tekton-pipelines

#Метаданные, специфичные для Hub

#Обязательные метки

metadata:
  name: my-custom-task
  labels:
    app.kubernetes.io/version: "0.1"  # Должна совпадать с версией каталога

#Обязательные аннотации для Hub

metadata:
  annotations:
    tekton.dev/pipelines.minVersion: "0.17.0"  # Минимальная версия Tekton
    tekton.dev/categories: "Build Tools"       # Категория Hub
    tekton.dev/tags: "build,podman,image"     # Теги для поиска в Hub
    tekton.dev/displayName: "Build Podman Image"  # Отображаемое имя в Hub
    tekton.dev/platforms: "linux/amd64,linux/arm64"  # Поддерживаемые платформы

#Стандарты параметров Hub

#Типы параметров

Tekton Hub поддерживает три типа параметров:

• string: одиночное текстовое значение (по умолчанию)
• array: список строковых значений
• object: JSON-объект с парами ключ-значение

#Требования к параметрам, специфичные для Hub

• Четкие описания: все параметры должны иметь осмысленные описания для UI Hub
• Разумные значения по умолчанию: предоставляйте значения по умолчанию для улучшения пользовательского опыта
• Безопасность типов: используйте подходящие типы для предотвращения ошибок во время выполнения

#Лучшие практики для Hub

#Требования к контейнерным образам

• Используйте официальные, проверенные контейнерные образы
• Фиксируйте конкретные версии вместо тегов latest
• Убедитесь, что образы работают на поддерживаемых платформах (linux/amd64, linux/arm64)
• Регулярно обновляйте базовые образы для безопасности

#Результаты и рабочие пространства для Hub

• Results: должны иметь четкие описания для документации Hub
• Workspaces: отмечайте необязательные рабочие пространства как optional: true
• Описания: обязательны для всех рабочих пространств и результатов

#Категории и теги Hub

#Стандартные категории

• Build Tools
• Testing
• Deployment
• Security
• Integration & Delivery
• Developer Tools
• Code Quality

#Эффективное использование тегов

• Используйте конкретные, удобные для поиска теги
• Включайте названия технологий (podman, kubernetes, npm и т.д.)
• Добавляйте теги по сценариям использования (ci, cd, build, test, deploy)

#Требования к валидации Hub

#Стандарты обработки ошибок

• Используйте правильные коды выхода (0 — успех, ненулевые — ошибка)
• Предоставляйте понятные сообщения об ошибках для пользователей Hub
• Включайте структурированное логирование для облегчения отладки

#Безопасность для Hub Tasks

#Требования безопасности Hub

• Не храните секреты в явном виде в определениях Task
• Используйте проверенные, официальные контейнерные образы
• Фиксируйте конкретные версии образов (без тегов latest)
• Следуйте принципам минимальных привилегий
• Документируйте любые особые требования безопасности

#Требования к тестированию Hub

#Обязательные тестовые файлы

• Предоставьте рабочую директорию samples/ с примерами TaskRun
• Включите run.yaml, демонстрирующий типичное использование
• Тестируйте все комбинации параметров
• Проверяйте сценарии обработки ошибок

#Контрольный список валидации Hub

• Присутствуют обязательные метаданные Hub
• Пример TaskRun работает корректно
• Все параметры задокументированы с описаниями
• Результаты и рабочие пространства правильно описаны
• Соблюдены лучшие практики безопасности
• Проверена совместимость с платформами

#Шаблон задачи Hub

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: my-hub-task
  labels:
    app.kubernetes.io/version: "0.1"  # Совпадает с версией каталога
  annotations:
    tekton.dev/pipelines.minVersion: "0.17.0"
    tekton.dev/categories: "Build Tools"  # Категория Hub
    tekton.dev/tags: "build,example"      # Теги для поиска в Hub
    tekton.dev/displayName: "My Hub Task" # Отображаемое имя в Hub
    tekton.dev/platforms: "linux/amd64,linux/arm64"  # Платформы
spec:
  description: >-
    Описание задачи для документации Hub
  params:
  - name: required-param
    description: Описание обязательного параметра
  - name: optional-param
    description: Описание необязательного параметра
    default: "default-value"
  workspaces:
  - name: source
    description: Описание рабочего пространства source
  results:
  - name: output
    description: Описание результата
  steps:
  - name: main
    image: alpine:3.18  # Зафиксированная версия
    script: |
      #!/bin/sh
      set -e
      echo "Hub task executed successfully"
      echo "result" > $(results.output.path)

#Требования к документации

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

• Включайте полный README.md в директорию задачи
• Документируйте все параметры, рабочие пространства и результаты
• Приводите примеры использования и типичные сценарии
• Включайте информацию по устранению неполадок

#Контрольный список публикации Hub

#✅ Соответствие требованиям Hub

• Присутствуют обязательные метаданные Hub (метки и аннотации)
• Задача использует ресурс типа Task (не ClusterTask)
• Метка версии совпадает со структурой каталога
• Все параметры и результаты имеют описания
• Контейнерные образы используют зафиксированные версии
• Указана совместимость с платформами
• Предоставлен рабочий пример TaskRun
• Полный README с примерами использования
• Проходит требования валидации Hub

#✅ Стандарты качества

• Задача идемпотентна и переиспользуема
• Обработка ошибок с правильными кодами выхода
• Отсутствие жестко заданных секретов или учетных данных
• Соблюдение лучших практик безопасности
• Проверена кроссплатформенная совместимость
• Документация полная и точная