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

Содержание

Overview Catalog Directory Structure Required Repository Structure Key Structure Rules Tekton Hub Validation Requirements Critical Requirements (Resource Ignored if Missing)1. Обязательная метка (label)2. Обязательные аннотации 3. Обязательное поле spec 4. Правило именования файлов Recommended Annotations (Improves Discoverability)Standard Categories Complete Task Example Complete Pipeline Example Setting Up Your Repository Initialize Repository Structure Root OWNERS File Version Management Semantic Versioning Rules Managing Versions Using Resources from Catalogs Using Hub Resolver for TasksUsing Hub Resolver for PipelinesHub Resolver Parameters Example: Different Catalogs Using Hub Resolver in Pipelines Next Steps: Adding to Tekton HubValidation Checklist Critical Validation (Must Pass)Recommended Validation Test Your Catalog Publishing Your Catalog Next Steps

Overview

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

Для настройки существующего каталога в Tekton Hub смотрите раздел Adding Custom Catalogs.

Catalog Directory Structure

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

Required Repository Structure

catalog-repo/
├── README.md              # Документация корневого каталога
├── OWNERS                 # Ответственные за каталог
├── task/                  # Все ресурсы Task
│   ├── task-name/         # Каталог с именем задачи
│   │   ├── 0.1/           # Каталог версии
│   │   │   ├── README.md  # Документация задачи
│   │   │   ├── task-name.yaml  # Определение задачи
│   │   │   ├── OWNERS     # Ответственные за задачу
│   │   │   └── samples/   # Примеры использования
│   │   │       └── run.yaml
│   │   └── 0.2/           # Следующая версия
│   └── another-task/
└── pipeline/              # Все ресурсы Pipeline
    └── pipeline-name/
        └── 0.1/
            ├── README.md
            ├── pipeline-name.yaml
            ├── OWNERS
            └── samples/

Key Structure Rules

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

`Tekton Hub` Validation Requirements

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

Critical Requirements (Resource Ignored if Missing)

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

1. Обязательная метка (label)

metadata:
  labels:
    app.kubernetes.io/version: "0.1"  # ДОЛЖНО точно совпадать с версией каталога

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

metadata:
  annotations:
    # ОБЯЗАТЕЛЬНО: Минимальная версия Tekton Pipelines
    tekton.dev/pipelines.minVersion: "0.17.0"

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

spec:
  description: "Описание вашего ресурса"  # ОБЯЗАТЕЛЬНО: не может быть пустым

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

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

Recommended Annotations (Improves Discoverability)

metadata:
  annotations:
    # Категория для Tekton Hub (выберите из стандартного списка)
    tekton.dev/categories: "Build Tools"

    # Теги для поиска (через запятую, без пробелов после запятых)
    tekton.dev/tags: "build,podman,container"

    # Читаемое имя для отображения
    tekton.dev/displayName: "Podman Build Task"

    # Поддерживаемые платформы (опционально)
    tekton.dev/platforms: "linux/amd64,linux/arm64"

Standard Categories

Выбирайте из этих стандартных категорий 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.

Complete `Task` Example

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

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: echo-hello
  # CRITICAL: Обязательная метка - ДОЛЖНА совпадать с версией каталога
  labels:
    app.kubernetes.io/version: "0.1"
  annotations:
    # CRITICAL: Обязательная минимальная версия pipelines
    tekton.dev/pipelines.minVersion: "0.17.0"
    # RECOMMENDED: Для лучшей обнаруживаемости
    tekton.dev/categories: "CLI"
    tekton.dev/tags: "echo,cli,demo"
    tekton.dev/displayName: "Echo Hello"
    tekton.dev/platforms: "linux/amd64,linux/arm64"
spec:
  # CRITICAL: Обязательное поле описания
  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).

Complete `Pipeline` Example

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

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: hello-pipeline
  # CRITICAL: Обязательная метка - ДОЛЖНА совпадать с версией каталога
  labels:
    app.kubernetes.io/version: "0.1"
  annotations:
    # CRITICAL: Обязательная минимальная версия pipelines
    tekton.dev/pipelines.minVersion: "0.17.0"
    # RECOMMENDED: Для лучшей обнаруживаемости
    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: Обязательное поле описания
  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).

Setting Up Your Repository

Initialize Repository Structure

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

# Создать базовую структуру
mkdir -p task pipeline
touch README.md OWNERS

# Пример: создать задачу
mkdir -p task/echo-hello/0.1/samples

Root `OWNERS` File

Определите ответственных за каталог:

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

Version Management

Semantic Versioning Rules

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

Managing Versions

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

Using Resources from Catalogs

После настройки вашего каталога в Tekton Hub пользователи смогут ссылаться на ваши ресурсы с помощью Hub resolver. Разные каталоги имеют разные настройки резолвера.

Using `Hub Resolver` for `Tasks`

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: test-echo-hello
spec:
  taskRef:
    resolver: hub
    params:
    - name: catalog
      value: "my-custom-catalog"  # Имя вашего каталога в конфигурации Hub
    - name: type
      value: tekton
    - name: kind
      value: task
    - name: name
      value: echo-hello  # Имя задачи
    - name: version
      value: "0.1"       # Версия задачи
  params:
  - name: message
    value: "Hello from my catalog!"

Using `Hub Resolver` for `Pipelines`

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: test-hello-pipeline
spec:
  pipelineRef:
    resolver: hub
    params:
    - name: catalog
      value: "my-custom-catalog"  # Имя вашего каталога в конфигурации Hub
    - name: type
      value: tekton
    - name: kind
      value: pipeline
    - name: name
      value: hello-pipeline  # Имя pipeline
    - name: version
      value: "0.1"           # Версия pipeline
  params:
  - name: greeting
    value: "Welcome to Tekton!"
  workspaces:
  - name: shared-data
    emptyDir: {}

Hub Resolver Parameters

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

Parameter	Required	Description	Default	Example Values
`name`	Да	Имя задачи или pipeline для загрузки из хаба	-	`echo-hello`, `build-image`
`catalog`	Нет	Каталог, из которого загружается ресурс	`tekton-catalog-tasks` (для задач) `tekton-catalog-pipelines` (для pipeline)	`tekton`, `my-catalog`
`type`	Нет	Тип хаба, из которого загружается ресурс	`artifact`	`artifact`, `tekton`
`kind`	Нет	Тип ресурса	`task`	`task`, `pipeline`
`version`	Нет	Версия или ограничение версии ресурса	Последняя	`"0.1"`, `">=0.5.0"`

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

Для настройки и конфигурации резолвера Hub смотрите Hub Resolver Configuration.

Example: Different Catalogs

# Использование официального каталога Tekton
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"

# Использование пользовательского каталога организации
taskRef:
  resolver: hub
  params:
  - name: catalog
    value: my-catalog     # Имя пользовательского каталога
  - name: type
    value: tekton
  - name: kind
    value: task
  - name: name
    value: custom-build
  - name: version
    value: "0.2"

Using Hub Resolver in Pipelines

Вы можете использовать задачи из разных каталогов в одном 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:
  # Задача из официального каталога Tekton
  - 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

  # Задача из вашего пользовательского каталога
  - 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!"

Next Steps: Adding to `Tekton Hub`

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

Для полного руководства по:

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

Смотрите Adding Custom Catalogs.

Validation Checklist

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

Critical Validation (Must Pass)

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

Recommended Validation

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

Test Your Catalog

# Проверка обязательной структуры каталогов
$ find . -name "*.yaml" -path "*/task/*" -o -path "*/pipeline/*"

# Проверка синтаксиса YAML
$ 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>

# Проверка наличия критичных полей
$ grep -r "app.kubernetes.io/version" task/ pipeline/
$ grep -r "tekton.dev/pipelines.minVersion" task/ pipeline/
$ grep -r "description:" task/ pipeline/

Publishing Your Catalog

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

Next Steps

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

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

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

#Содержание

#Overview

#Catalog Directory Structure

#Required Repository Structure

#Key Structure Rules

#Tekton Hub Validation Requirements

#Critical Requirements (Resource Ignored if Missing)

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

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

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

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

#Recommended Annotations (Improves Discoverability)

#Standard Categories

#Complete Task Example

#Complete Pipeline Example

#Setting Up Your Repository

#Initialize Repository Structure

#Root OWNERS File

#Version Management

#Semantic Versioning Rules

#Managing Versions

#Using Resources from Catalogs

#Using Hub Resolver for Tasks

#Using Hub Resolver for Pipelines

#Hub Resolver Parameters

#Example: Different Catalogs

#Using Hub Resolver in Pipelines

#Next Steps: Adding to Tekton Hub

#Validation Checklist

#Critical Validation (Must Pass)

#Recommended Validation

#Test Your Catalog

#Publishing Your Catalog

#Next Steps