#Добавление пользовательских каталогов в Tekton Hub

#Overview

В этом руководстве объясняется, как настроить экземпляр Tekton Hub для включения пользовательских каталогов из существующих Git-репозиториев. Если вам нужно сначала создать новый репозиторий каталога, смотрите Создание пользовательского каталога.

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

Важно: Если вы развернули Tekton Hub через TektonConfig, изменяйте конфигурацию каталогов в ресурсе TektonConfig, а не напрямую редактируйте ConfigMap. Прямые изменения ConfigMap будут перезаписаны контроллером Tekton Operator.

Примечание по namespace: В этом руководстве <tekton-pipelines> используется как заполнитель для namespace вашего Tekton Hub. Замените его на фактическое имя вашего namespace. По умолчанию используется namespace tekton-pipelines.

#Требования

Перед началом убедитесь, что у вас есть:

• Kubernetes кластер с установленными Tekton Pipelines
• Запущенный экземпляр Tekton Hub
• Администраторский доступ к кластеру
• Git-репозиторий с вашими пользовательскими ресурсами Tekton, соответствующий структуре Tekton Catalog

#Добавление пользовательских каталогов

#Шаг 1: Подготовьте репозиторий каталога

Убедитесь, что ваш репозиторий каталога соответствует структуре Tekton Catalog Organization TEP (подробности смотрите в разделе tutorials).

#Шаг 2: Настройте ConfigMap API

Добавьте ваш пользовательский каталог в ConfigMap tekton-hub-api в разделе CATALOGS:

apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-hub-api
  namespace: <tekton-pipelines>
data:
  CATALOGS: |
    # Каталог по умолчанию (локальный)
    - name: catalog
      org: tektoncd
      type: community
      provider: github
      url: file:////mnt/git/catalog.git
      revision: master

    # Официальный каталог Tekton (публичный репозиторий)
    - name: catalog-official
      org: tektoncd
      type: community
      provider: github
      url: https://github.com/tektoncd/catalog
      revision: main

    # Пользовательский публичный репозиторий
    - name: my-public-catalog
      org: myorganization
      type: community
      provider: github
      url: https://github.com/myorganization/my-public-catalog
      revision: main

    # Пользовательский приватный репозиторий (требуется SSH-аутентификация)
    - name: my-private-catalog
      org: myorganization
      type: community
      provider: github
      url: https://github.com/myorganization/my-private-catalog
      sshurl: git@github.com:myorganization/my-private-catalog.git
      revision: main

Поля конфигурации каталога:

Подробности использования полей:

• org: Используется для организации и группировки каталогов в UI Hub. Может быть любой осмысленной строкой, представляющей владельца каталога.
• type: Определяет классификацию и отображение каталога в интерфейсе Hub:
  • official: Официальные каталоги Tekton (обычно поддерживаются командой Tekton)
  • community: Каталоги, поддерживаемые сообществом (наиболее распространённый вариант)
  • enterprise: Каталоги предприятий/компаний
  • private: Приватные каталоги (внутреннее использование)
• provider: Указывает Git-платформу для правильной интеграции API и аутентификации:
  • github: GitHub и GitHub Enterprise
  • gitlab: GitLab и самохостинг GitLab

Приоритет конфигурации URL:

• sshurl имеет приоритет над url — если указаны оба, для git-операций будет использоваться sshurl

• Для публичных репозиториев: используйте только url с HTTPS

  url: https://github.com/org/public-repo

• Для приватных репозиториев: необходимо указать и url, и sshurl — url нужен для хранения в базе данных, sshurl используется для git-операций

  url: https://github.com/org/private-repo        # Обязательное поле (ограничение базы данных)
  sshurl: git@github.com:org/private-repo.git     # Используется для git-операций (приоритет)

Важно: url всегда обязателен из-за ограничений базы данных, даже если для приватных репозиториев используется sshurl.

#Шаг 3: Примените конфигурацию

Примените обновлённый ConfigMap в ваш кластер:

$ kubectl apply -f tekton-hub-api-configmap.yaml

#Шаг 4: Примените изменения

После обновления ConfigMap примените изменения:

Вариант 1: Перезапустите API Pod

$ kubectl delete pod -l app=tekton-hub-api -n <tekton-pipelines>

Вариант 2: Дождитесь автоматического обновления

Каталог будет автоматически обновлён согласно настроенному CATALOG_REFRESH_INTERVAL.

#Требования к пользовательским каталогам

Перед добавлением пользовательского каталога в Tekton Hub ваш репозиторий должен соответствовать следующим требованиям:

• Структура репозитория: соответствовать стандарту Tekton Catalog Organization
• Валидация ресурсов: все Tasks/Pipelines должны содержать обязательные метаданные
• Документация: каждый ресурс должен иметь корректный README и примеры

Подробные инструкции по созданию совместимых репозиториев каталогов смотрите в Создание пользовательского каталога.

#Управление несколькими каталогами

Вы можете настроить несколько каталогов в одном экземпляре Tekton Hub:

data:
  CATALOGS: |
    - name: tekton
      org: tektoncd
      type: community
      provider: github
      url: https://github.com/tektoncd/catalog
      revision: main
    - name: company-catalog
      org: mycompany
      type: community
      provider: github
      url: https://github.com/mycompany/tekton-catalog
      revision: main
    - name: team-catalog
      org: mycompany
      type: community
      provider: github
      url: https://github.com/mycompany/team-tekton-catalog
      revision: develop

Рекомендации по лучшим практикам:

• Используйте описательные, уникальные имена каталогов
• Поддерживайте согласованность имён каталогов в разных средах
• Используйте подходящие Git-ревизии (main/master для стабильных, develop для тестирования)

#Аутентификация для приватных репозиториев

#Аутентификация по SSH-ключу

Для доступа к приватным Git-репозиториям или репозиториям на приватных Git-инстансах необходимо создать SSH-учётные данные в виде Kubernetes секрета.

#Требования

• SSH-ключи должны существовать в вашем каталоге ~/.ssh
• Публичный SSH-ключ должен быть добавлен в deploy keys вашего Git-репозитория или в ваш пользовательский аккаунт

#Создание SSH-секрета

Создайте Kubernetes секрет с именем tekton-hub-api-ssh-crds с вашими SSH-учётными данными:

$ kubectl create secret generic tekton-hub-api-ssh-crds \
  --from-file=id_rsa="/path/to/id_rsa" \
  --from-file=id_rsa.pub="/path/to/id_rsa.pub" \
  --from-file=known_hosts="/path/to/known_hosts" \
  --namespace=<tekton-pipelines>

Важные замечания:

• Секрет должен называться именно tekton-hub-api-ssh-crds
• Секрет должен быть создан в том же namespace, что и установка Tekton Hub
• Включите все три файла: приватный ключ, публичный ключ и known_hosts

#Генерация записей known_hosts

Важно: файл known_hosts необходимо сгенерировать, фактически подключившись к Git-серверу для получения его SSH-отпечатка. Простое копирование примерных записей может не сработать из-за изменений ключей сервера или разных провайдеров Git.

Рекомендуемый подход:

1. Проверьте SSH-соединение локально, чтобы добавить отпечаток сервера в локальный known_hosts:

   # Это добавит отпечаток сервера в ваш локальный known_hosts
   $ ssh -T git@github.com
   $ ssh -T git@your-git-server.com

2. Альтернативно: используйте ssh-keyscan для генерации записей known_hosts:

   # Для GitHub
   $ ssh-keyscan github.com >> ~/.ssh/known_hosts
   
   # Для кастомных Git-серверов
   $ ssh-keyscan your-git-server.com >> ~/.ssh/known_hosts

3. Проверьте, клонируя репозитории локально с обоими URL:

   # Проверьте SSH URL, который будет использовать Tekton Hub
   $ git clone ssh://git@github.com:org/private-repo.git
   
   # Также проверьте HTTPS URL для верификации
   $ git clone https://github.com/org/private-repo.git

Пример записи known_hosts (сгенерирована после успешного SSH-подключения):

github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndN...

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

При настройке каталогов, требующих SSH-аутентификацию, указывайте оба поля url и sshurl:

data:
  CATALOGS: |
    - name: private-catalog
      org: myorg
      type: community
      provider: github
      url: https://github.com/myorg/private-catalog        # Обязательно для базы данных
      sshurl: git@github.com:myorg/private-catalog.git     # Используется для git-операций
      revision: main

Примечание: Для приватных репозиториев обязательны оба поля — url (HTTPS) и sshurl (SSH). Для git-операций будет использоваться sshurl.

#Проверка и тестирование

#Проверка конфигурации каталога

После добавления пользовательского каталога проверьте, что он корректно настроен:

Советы: По умолчанию API Tekton Hub доступен по адресу tekton-hub-api.tekton-pipelines:8000, который доступен только внутри кластера.

Для заполнителя <your-tekton-hub-api> в командах ниже:

• Внутри pod tekton-hub-api: используйте localhost:8000
• Из других pod в кластере: используйте tekton-hub-api.tekton-pipelines:8000
• Снаружи кластера: создайте сервис NodePort или Ingress (не рассматривается в этом руководстве)

Для тестирования можно выполнить команды внутри pod tekton-hub-api с помощью wget.

# Выполните внутри pod tekton-hub-api для тестирования
$ kubectl exec -it deployment/tekton-hub-api -n <tekton-pipelines> -- /bin/sh

# Проверьте, отображается ли каталог в API
$ wget -qO- http://<your-tekton-hub-api>/v1/catalogs

{"data":[{"id":1,"name":"catalog","type":"community","url":"file:////mnt/git/catalog.git","provider":"github"},{"id":2,"name":"<new-catalog>","type":"private","url":"<url>","provider":"<provider>"}]}

# Проверьте ресурсы каталога
$ wget -qO- "http://<your-tekton-hub-api>/v1/query?catalogs=<my-custom-catalog>"

{"data":[{"id":1,"name":"<name>","catalog":{"id":1,"name":"<my-custom-catalog>","type":"community"},"categories":[{"id":9,"name":"<name>"}],"kind":"Task","hubURLPath":"","hubRawURLPath":""}]}

# Проверьте конкретный ресурс
$ wget -qO- http://<your-tekton-hub-api>/v1/resource/<my-custom-catalog>/task/<my-task>

{"data":{"id":4,"name":"<my-task>","catalog":{}}}

#Тестирование разрешения ресурсов

Проверьте, что ресурсы можно разрешить через резолвер Hub:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: test-catalog-resolution
spec:
  taskRef:
    resolver: hub
    params:
    - name: catalog
      value: my-custom-catalog
    - name: type
      value: tekton
    - name: kind
      value: task
    - name: name
      value: test-task
    - name: version
      value: "0.1"

#Устранение неполадок

#Каталог не отображается

Проблема: Каталог настроен, но не отображается в API

Решения:

1. Проверьте, что ConfigMap применён: kubectl get cm tekton-hub-api -o yaml
2. Перезапустите API pod: kubectl delete pod -l app=tekton-hub-api -n <tekton-pipelines>
3. Проверьте логи API: kubectl logs deployment/tekton-hub-api -n <tekton-pipelines>

#Ресурсы не загружаются

Проблема: Каталог отображается, но ресурсы отсутствуют

Возможные причины:

• Структура репозитория не соответствует стандарту
• Отсутствуют обязательные метаданные (см. Создание пользовательского каталога)
• Проблемы с аутентификацией Git-репозитория

Решения:

1. Проверьте логи API на ошибки парсинга
2. Проверьте синтаксис YAML ресурсов с помощью kubectl apply --dry-run

#Ошибки SSH-аутентификации

Проблема: Доступ к приватному репозиторию запрещён

Решения:

1. Убедитесь, что секрет существует: kubectl get secret tekton-hub-api-ssh-crds
2. Проверьте, что known_hosts содержит ваш Git-сервер
3. Проверьте SSH-соединение вручную из pod

#Ошибки разрешения ресурсов

Проблема: Резолвер Hub не может найти ресурсы

Распространённые причины:

• Несовпадение имени каталога между ConfigMap и параметрами резолвера
• Имя/версия ресурса не совпадают со структурой каталогов
• Ресурс не прошёл валидацию при парсинге каталога

Шаги для отладки:

# Проверьте доступные каталоги
$ wget -qO- http://<your-tekton-hub-api>/v1/catalogs

# Проверьте, что ресурс существует
$ wget -qO- http://<your-tekton-hub-api>/v1/resource/<my-custom-catalog>/task/<my-task>/<version>

# Проверьте статус синхронизации каталога
$ kubectl logs deployment/tekton-hub-api -n <tekton-pipelines>

#FAQ

#В: Я настроил согласно документации, но не вижу новый каталог

О: Сначала проверьте логи tekton-hub-api на ошибки, связанные с аутентификацией, например "Host key verification failed":

$ kubectl logs deployment/tekton-hub-api -n <tekton-pipelines>

Распространённые причины:

• SSH-ключ не имеет достаточных прав на репозиторий
• Файл known_hosts не содержит отпечаток Git-сервера
• SSH-ключ не добавлен в deploy keys репозитория

Решение:

1. Сначала протестируйте локально: убедитесь, что вы можете успешно клонировать репозиторий локально с теми же SSH-учётными данными:

   # Тест с тем же SSH-ключом и known_hosts
   $ git clone ssh://git@github.com:org/private-repo.git

2. Только после успешного локального клонирования обновляйте Kubernetes окружение:

   • Следуйте разделу Генерация записей known_hosts для правильного создания файла known_hosts
   • Пересоздайте секрет tekton-hub-api-ssh-crds с рабочими учётными данными
   • Перезапустите pod tekton-hub-api и проверьте логи:

     $ kubectl delete pod -l app=tekton-hub-api -n <tekton-pipelines>
     $ kubectl logs deployment/tekton-hub-api -n <tekton-pipelines>