#Создание пользовательского каталога

#Обзор

В этом руководстве вы узнаете, как создать репозиторий каталога с ресурсами Tekton (Tasks, Pipelines). Вы познакомитесь со структурой, стандартами метаданных и требованиями к валидации, которые обеспечивают корректную работу ваших ресурсов с Tekton Hub.

Чтобы настроить существующий каталог в Tekton Hub, см. Adding Custom Catalogs.

#Структура каталога

Все каталоги Tekton должны соответствовать Tekton Catalog Organization Standard. Этот стандарт обеспечивает единообразие и совместимость с Tekton Hub.

#Требуемая структура репозитория

catalog-repo/
├── README.md              # Root catalog documentation
├── OWNERS                 # Catalog maintainers
├── task/                  # All Task resources
│   ├── task-name/         # Task name directory
│   │   ├── 0.1/           # Version directory
│   │   │   ├── README.md  # Task documentation
│   │   │   ├── task-name.yaml  # Task definition
│   │   │   ├── OWNERS     # Task maintainers
│   │   │   └── samples/   # Usage examples
│   │   │       └── run.yaml
│   │   └── 0.2/           # Next version
│   └── another-task/
└── pipeline/              # All Pipeline resources
    └── pipeline-name/
        └── 0.1/
            ├── README.md
            ├── pipeline-name.yaml
            ├── OWNERS
            └── samples/

#Ключевые правила структуры

1. Типы ресурсов: поддерживаются только каталоги task/ и pipeline/
2. Версионирование: для каждого ресурса используется семантическое версионирование (0.1, 0.2, 1.0)
3. Несколько версий: разные версии сосуществуют в виде отдельных каталогов
4. Обязательные файлы: каждая версия должна иметь определение YAML. README и OWNERS необязательны, но рекомендуются.
5. Примеры использования: каталог samples/ для примеров применения

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

Tekton Hub использует строгие правила валидации, которые определяют, будут ли ваши ресурсы отображаться. Ресурсы, не прошедшие валидацию, полностью игнорируются.

#Критические требования (ресурс игнорируется при отсутствии)

Эти поля абсолютно обязательны — отсутствие любого из них приведет к тому, что ваш ресурс будет полностью проигнорирован:

#1. Обязательная метка

metadata:
  labels:
    app.kubernetes.io/version: "0.1"  # MUST match directory version exactly

#2. Обязательные аннотации

metadata:
  annotations:
    # MANDATORY: Minimum Tekton Pipelines version
    tekton.dev/pipelines.minVersion: "0.17.0"

#3. Обязательное поле spec

spec:
  description: "Your resource description here"  # MANDATORY: Cannot be empty

#4. Правило именования файла

• Имя файла YAML ДОЛЖНО совпадать с именем ресурса
• Пример: Task с именем build-image → файл должен называться build-image.yaml
• Применяемый шаблон: task/<name>/<version>/<name>.yaml или pipeline/<name>/<version>/<name>.yaml

#Рекомендуемые аннотации (улучшают обнаруживаемость)

metadata:
  annotations:
    # Tekton Hub category (choose from standard list)
    tekton.dev/categories: "Build Tools"

    # Searchable tags (comma-separated, no spaces after commas)
    tekton.dev/tags: "build,podman,container"

    # Human-readable display name
    tekton.dev/displayName: "Podman Build Task"

    # Supported platforms (optional)
    tekton.dev/platforms: "linux/amd64,linux/arm64"

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

Выберите одну из следующих стандартных категорий Tekton Hub:

• Automation, Build Tools, CLI, Cloud
• Code Quality, Continuous Integration
• Deployment, Developer Tools
• Image Build, Integration & Delivery
• Git, Kubernetes, Messaging
• Monitoring, Networking, Publishing
• Security, Storage, Testing

Важно: ресурсы с категориями, не настроенными в вашем экземпляре Tekton Hub, не будут отображаться, даже если используются допустимые имена категорий. Инструкции по добавлению пользовательских категорий в ваш экземпляр Hub см. в Categories Configuration.

#Полный пример Task

Ниже приведен полный пример Task, демонстрирующий все обязательные и рекомендуемые поля:

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: echo-hello
  # CRITICAL: Required label - MUST match directory version
  labels:
    app.kubernetes.io/version: "0.1"
  annotations:
    # CRITICAL: Required minimum pipelines version
    tekton.dev/pipelines.minVersion: "0.17.0"
    # RECOMMENDED: For better discoverability
    tekton.dev/categories: "CLI"
    tekton.dev/tags: "echo,cli,demo"
    tekton.dev/displayName: "Echo Hello"
    tekton.dev/platforms: "linux/amd64,linux/arm64"
spec:
  # CRITICAL: Required description field
  description: Simple demonstration Task that echoes a greeting message
  params:
  - name: message
    description: Message to echo
    default: "Hello World"
  results:
  - name: greeting
    description: The echoed greeting
  steps:
  - name: echo-message
    image: alpine:3.18
    script: |
      #!/bin/sh
      echo "$(params.message)"
      echo -n "$(params.message)" | tee $(results.greeting.path)

Важно: этот файл должен быть сохранен как task/echo-hello/0.1/echo-hello.yaml (имя файла совпадает с именем task).

#Полный пример Pipeline

Ниже приведен полный пример Pipeline, демонстрирующий все обязательные и рекомендуемые поля:

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: hello-pipeline
  # CRITICAL: Required label - MUST match directory version
  labels:
    app.kubernetes.io/version: "0.1"
  annotations:
    # CRITICAL: Required minimum pipelines version
    tekton.dev/pipelines.minVersion: "0.17.0"
    # RECOMMENDED: For better discoverability
    tekton.dev/categories: "Integration & Delivery"
    tekton.dev/tags: "demo,pipeline,workflow"
    tekton.dev/displayName: "Hello Pipeline"
    tekton.dev/platforms: "linux/amd64,linux/arm64"
spec:
  # CRITICAL: Required description field
  description: Simple demonstration Pipeline showing task orchestration
  params:
  - name: greeting
    description: Greeting message
    default: "Hello from Pipeline"
  workspaces:
  - name: shared-data
    description: Workspace for sharing data between tasks
  tasks:
  - name: say-hello
    taskRef:
      name: echo-hello
    params:
    - name: message
      value: "$(params.greeting)"
  - name: say-goodbye
    taskRef:
      name: echo-hello
    params:
    - name: message
      value: "Goodbye from $(tasks.say-hello.results.greeting)"
    runAfter:
    - say-hello

Важно: этот файл должен быть сохранен как pipeline/hello-pipeline/0.1/hello-pipeline.yaml (имя файла совпадает с именем pipeline).

#Настройка вашего репозитория

#Инициализация структуры репозитория

mkdir my-tekton-catalog
cd my-tekton-catalog
git init

# Create basic structure
mkdir -p task pipeline
touch README.md OWNERS

# Example: Create a task
mkdir -p task/echo-hello/0.1/samples

#Файл OWNERS в корне

Определите сопровождающих каталога:

approvers:
  - your-github-username
reviewers:
  - team-member-username

#Управление версиями

#Правила семантического версионирования

• 0.1 → 0.2: исправления ошибок, улучшения
• 0.x → 1.0: новые возможности, стабильный выпуск
• 1.x → 2.0: несовместимые изменения

#Управление версиями

• для каждой версии создается собственный каталог
• несколько версий сосуществуют одновременно
• несовместимые изменения документируйте в README

#Использование ресурсов из каталогов

После того как ваш каталог будет настроен в Tekton Hub, пользователи смогут ссылаться на ваши ресурсы с помощью Hub resolver. Для разных каталогов используются разные конфигурации resolver.

#Использование Hub resolver для Tasks

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: test-echo-hello
spec:
  taskRef:
    resolver: hub
    params:
    - name: catalog
      value: "my-custom-catalog"  # Your catalog name in Hub config
    - name: type
      value: tekton
    - name: kind
      value: task
    - name: name
      value: echo-hello  # Task name
    - name: version
      value: "0.1"       # Task version
  params:
  - name: message
    value: "Hello from my catalog!"

#Использование Hub resolver для Pipelines

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: test-hello-pipeline
spec:
  pipelineRef:
    resolver: hub
    params:
    - name: catalog
      value: "my-custom-catalog"  # Your catalog name in Hub config
    - name: type
      value: tekton
    - name: kind
      value: pipeline
    - name: name
      value: hello-pipeline  # Pipeline name
    - name: version
      value: "0.1"           # Pipeline version
  params:
  - name: greeting
    value: "Welcome to Tekton!"
  workspaces:
  - name: shared-data
    emptyDir: {}

#Параметры Hub resolver

Hub resolver поддерживает следующие параметры:

Примечание: для пользовательских каталогов обычно необходимо явно указывать параметры catalog и type: tekton.

Инструкции по настройке и конфигурации Hub resolver см. в Hub Resolver Configuration.

#Пример: разные каталоги

# Using the official Tekton catalog
taskRef:
  resolver: hub
  params:
  - name: catalog
    value: catalog        # Official catalog name
  - name: type
    value: tekton
  - name: kind
    value: task
  - name: name
    value: git-clone
  - name: version
    value: "0.9"

# Using a custom organization catalog
taskRef:
  resolver: hub
  params:
  - name: catalog
    value: my-catalog     # Custom catalog name
  - name: type
    value: tekton
  - name: kind
    value: task
  - name: name
    value: custom-build
  - name: version
    value: "0.2"

#Использование Hub resolver в Pipelines

Вы можете использовать Tasks из разных каталогов в одном и том же Pipeline:

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: multi-catalog-pipeline
spec:
  description: Pipeline using tasks from multiple catalogs
  workspaces:
  - name: source
    description: Source code workspace
  tasks:
  # Task from official Tekton catalog
  - name: git-clone
    taskRef:
      resolver: hub
      params:
      - name: catalog
        value: catalog
      - name: type
        value: tekton
      - name: kind
        value: task
      - name: name
        value: git-clone
      - name: version
        value: "0.9"
    workspaces:
    - name: output
      workspace: source

  # Task from your custom catalog
  - name: custom-build
    taskRef:
      resolver: hub
      params:
      - name: catalog
        value: my-custom-catalog
      - name: type
        value: tekton
      - name: kind
        value: task
      - name: name
        value: echo-hello
      - name: version
        value: "0.1"
    runAfter:
    - git-clone
    params:
    - name: message
      value: "Build completed!"

#Следующие шаги: добавление в Tekton Hub

После того как репозиторий вашего каталога будет готов, его необходимо настроить в Tekton Hub, прежде чем пользователи смогут получить к нему доступ через resolver.

Полные инструкции по следующим темам:

• добавление вашего каталога в конфигурацию Tekton Hub
• аутентификация SSH для закрытых репозиториев
• тестирование и устранение неполадок при интеграции каталога

См. Adding Custom Catalogs.

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

Перед публикацией каталога убедитесь, что каждый ресурс соответствует всем требованиям Tekton Hub:

#Критическая валидация (должна пройти)

• Именование файла: шаблон task/<name>/<version>/<name>.yaml соблюден точно
• Метка версии: app.kubernetes.io/version: "0.1" соответствует версии каталога
• Аннотация MinVersion: присутствует tekton.dev/pipelines.minVersion: "0.17.0"
• Поле description: spec.description: "..." не пустое
• Синтаксис YAML: ресурс проходит валидацию с kubectl apply --dry-run

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

• Отображаемое имя: указано tekton.dev/displayName для лучшего UX
• Категории: указана допустимая категория из стандартного списка
• Теги: описательные теги, разделенные запятыми, без пробелов после запятых
• Документация: полный README.md для каждого ресурса
• Примеры: рабочие примеры в samples/run.yaml

#Проверьте ваш каталог

# Check required directory structure
$ find . -name "*.yaml" -path "*/task/*" -o -path "*/pipeline/*"

# Validate YAML syntax
$ kubectl apply --dry-run=client -f <task/echo-hello/0.1/echo-hello.yaml>
$ kubectl apply --dry-run=client -f <pipeline/hello-pipeline/0.1/hello-pipeline.yaml>

# Test critical fields exist
$ grep -r "app.kubernetes.io/version" task/ pipeline/
$ grep -r "tekton.dev/pipelines.minVersion" task/ pipeline/
$ grep -r "description:" task/ pipeline/

#Публикация вашего каталога

1. Отправьте в репозиторий Git (GitHub, GitLab и т. д.)
2. Протестируйте локально — проверьте структуру и синтаксис YAML
3. Добавьте в Tekton Hub — см. Adding Custom Catalogs
4. Поделитесь с командой — теперь ваши ресурсы можно обнаружить через Hub resolver

#Следующие шаги

Теперь, когда вы понимаете структуру каталога и стандарты, перейдите к более глубокому изучению разработки ресурсов:

• Writing Custom Tasks — подробное руководство по созданию Task
• Writing Custom Pipelines — шаблоны оркестрации Pipeline