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

Содержание

Обзор Структура каталога Требуемая структура репозитория Основные правила структуры Требования к валидации в Tekton HubКритические требования (ресурс игнорируется при отсутствии)1. Обязательная метка 2. Обязательные аннотации 3. Обязательное поле spec 4. Правило именования файла Рекомендуемые аннотации (улучшают обнаруживаемость)Стандартные категории Полный пример TaskПолный пример PipelineНастройка вашего репозитория Инициализация структуры репозитория Корневой файл OWNERSУправление версиями Правила семантического версионирования Управление версиями Использование ресурсов из каталогов Использование Hub Resolver для TasksИспользование Hub Resolver для PipelinesПараметры Hub Resolver Пример: разные каталоги Использование Hub Resolver в Pipeline Следующие шаги: добавление в Tekton HubКонтрольный список валидации Критическая валидация (обязательно пройти)Рекомендуемая валидация Тестирование вашего каталога Публикация вашего каталога Следующие шаги

Обзор

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

Для настройки существующего каталога в Tekton Hub смотрите Добавление пользовательских каталогов.

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

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

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

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/

Основные правила структуры

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

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

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

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

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

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

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

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

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

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

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

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

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

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

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: hello-pipeline
  # КРИТИЧНО: обязательная метка - ДОЛЖНА совпадать с версией каталога
  labels:
    app.kubernetes.io/version: "0.1"
  annotations:
    # КРИТИЧНО: обязательная минимальная версия pipelines
    tekton.dev/pipelines.minVersion: "0.17.0"
    # РЕКОМЕНДУЕТСЯ: для лучшей обнаруживаемости
    tekton.dev/categories: "Integration & Delivery"
    tekton.dev/tags: "demo,pipeline,workflow"
    tekton.dev/displayName: "Hello Pipeline"
    tekton.dev/platforms: "linux/amd64,linux/arm64"
spec:
  # КРИТИЧНО: обязательное поле описания
  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

# Создание базовой структуры
mkdir -p task pipeline
touch README.md OWNERS

# Пример: создание задачи
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. Разные каталоги имеют разные настройки резолвера.

Использование `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"  # Имя вашего каталога в конфигурации 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!"

Использование `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"  # Имя вашего каталога в конфигурации 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

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

Параметр	Обязательный	Описание	Значение по умолчанию	Примеры значений
`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.

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

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

Использование Hub Resolver в Pipeline

Вы можете комбинировать задачи из разных каталогов в одном 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!"

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

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

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

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

Смотрите Добавление пользовательских каталогов.

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

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

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

Именование файлов: строго по шаблону 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

Тестирование вашего каталога

# Проверка требуемой структуры каталогов
$ 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/

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

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

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

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

Создание пользовательских задач — подробное руководство по созданию Task
Создание пользовательских pipeline — шаблоны оркестрации Pipeline

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

#Содержание

#Обзор

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

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

#Основные правила структуры

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

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

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

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

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

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

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

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

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

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

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

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

#Корневой файл OWNERS

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

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

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

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

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

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

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

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

#Использование Hub Resolver в Pipeline

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

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

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

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

#Тестирование вашего каталога

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

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

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

Содержание

Обзор

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

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

Основные правила структуры

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

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

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

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

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

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

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

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

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

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

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

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

Корневой файл `OWNERS`

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

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

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

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

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

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

Параметры Hub Resolver

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

Использование Hub Resolver в Pipeline

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

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

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

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

Тестирование вашего каталога

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

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