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

#Обзор

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

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

#Task vs ClusterTask

⚠️ ВАЖНО: ClusterTask УСТАРЕЛ и УДАЛЕН в Tekton Pipelines v1.0+. НЕ используйте ClusterTask.

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

#Миграция с ClusterTask

# OLD - ClusterTask (NO LONGER WORKS)
apiVersion: tekton.dev/v1beta1
kind: ClusterTask
metadata:
  name: buildah

# NEW - Task (Required for Hub)
apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: buildah
  namespace: tekton-pipelines

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

#Обязательные Labels

metadata:
  name: my-custom-task
  labels:
    app.kubernetes.io/version: "0.1"  # Must match catalog version directory

#Обязательные Annotations для Hub

metadata:
  annotations:
    tekton.dev/pipelines.minVersion: "0.17.0"  # Minimum Tekton version
    tekton.dev/categories: "Build Tools"       # Hub category
    tekton.dev/tags: "build,podman,image"     # Hub search tags
    tekton.dev/displayName: "Build Podman Image"  # Hub display name
    tekton.dev/platforms: "linux/amd64,linux/arm64"  # Supported platforms

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

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

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

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

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

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

#Рекомендации для Hub

#Требования к container image

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

#Results и Workspaces для Hub

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

#Категории и теги 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

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

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

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

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

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

• Присутствуют обязательные метаданные Hub
• Sample TaskRun работает корректно
• Все параметры документированы с описаниями
• Results и workspaces должным образом описаны
• Соблюдены рекомендации по безопасности
• Подтверждена совместимость с платформами

#Шаблон Hub Task

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: my-hub-task
  labels:
    app.kubernetes.io/version: "0.1"  # Match catalog version
  annotations:
    tekton.dev/pipelines.minVersion: "0.17.0"
    tekton.dev/categories: "Build Tools"  # Hub category
    tekton.dev/tags: "build,example"      # Hub search tags
    tekton.dev/displayName: "My Hub Task" # Hub display name
    tekton.dev/platforms: "linux/amd64,linux/arm64"  # Platforms
spec:
  description: >-
    Task description for Hub documentation
  params:
  - name: required-param
    description: Required parameter description
  - name: optional-param
    description: Optional parameter description
    default: "default-value"
  workspaces:
  - name: source
    description: Source workspace description
  results:
  - name: output
    description: Result description
  steps:
  - name: main
    image: alpine:3.18  # Pinned version
    script: |
      #!/bin/sh
      set -e
      echo "Hub task executed successfully"
      echo "result" > $(results.output.path)

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

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

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

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

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

• Присутствуют обязательные метаданные Hub (labels и annotations)
• Task использует тип ресурса Task (не ClusterTask)
• Label версии соответствует структуре каталога
• Все параметры и results имеют описания
• Container image используют закрепленные версии
• Указана совместимость с платформами
• Предоставлен рабочий sample TaskRun
• Полный README с примерами использования
• Выполнены требования валидации Hub

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

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