#Написание 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 object с парами ключ-значение

#Специфичные требования Hub к параметрам

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

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

#Требования к Container Image

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

#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

• Не храните секреты прямо в определениях Task
• Используйте доверенные, официальные Container 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
• Документируйте все параметры, workspaces и results
• Приведите примеры использования и типовые сценарии
• Включите сведения по устранению неполадок

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

#✅ Соответствие Hub

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

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

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