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

#Обзор

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

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

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

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

#Предварительные требования

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

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

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

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

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

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

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-hub-api
  namespace: <tekton-pipelines>
data:
  CATALOGS: |
    # Default local catalog
    - name: catalog
      org: tektoncd
      type: community
      provider: github
      url: file:////mnt/git/catalog.git
      revision: master

    # Official Tekton catalog (public repository)
    - name: catalog-official
      org: tektoncd
      type: community
      provider: github
      url: https://github.com/tektoncd/catalog
      revision: main

    # Custom public repository
    - name: my-public-catalog
      org: myorganization
      type: community
      provider: github
      url: https://github.com/myorganization/my-public-catalog
      revision: main

    # Custom private repository (requires SSH authentication)
    - 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: Private каталоги (для внутреннего использования)
• provider: Указывает платформу Git для корректной интеграции с API и аутентификации:
  • github: GitHub и GitHub Enterprise
  • gitlab: GitLab и self-hosted GitLab

Приоритет настройки URL:

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

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

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

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

  url: https://github.com/org/private-repo        # Required field (database constraint)
  sshurl: git@github.com:org/private-repo.git     # Used for git operations (takes precedence)

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

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

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

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

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

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

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

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

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

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

#Предварительные требования для пользовательских каталогов

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

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

Подробные инструкции по созданию каталогов, соответствующих требованиям, см. в Creating a Custom Catalog.

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

Вы можете настроить несколько каталогов в одном экземпляре 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

Рекомендации:

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

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

#Аутентификация с помощью SSH key

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

#Предварительные требования

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

#Создание SSH Secret

Создайте Kubernetes secret с именем tekton-hub-api-ssh-crds с вашими SSH credentials:

$ 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>

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

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

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

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

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

1. Проверьте SSH connection локально, чтобы получить fingerprint server:

   # This will add the server's fingerprint to your local known_hosts
   $ ssh -T git@github.com
   $ ssh -T git@your-git-server.com

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

   # For GitHub
   $ ssh-keyscan github.com >> ~/.ssh/known_hosts
   
   # For custom Git servers
   $ ssh-keyscan your-git-server.com >> ~/.ssh/known_hosts

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

   # Test the SSH URL that will be used by Tekton Hub
   $ git clone ssh://git@github.com:org/private-repo.git
   
   # Also test the HTTPS URL for verification
   $ git clone https://github.com/org/private-repo.git

Пример записи known_hosts (сгенерирован после успешного SSH connection):

github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndN...

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

При настройке каталогов, которые требуют SSH authentication, укажите оба поля url и sshurl:

data:
  CATALOGS: |
    - name: private-catalog
      org: myorg
      type: community
      provider: github
      url: https://github.com/myorg/private-catalog        # Required for database
      sshurl: git@github.com:myorg/private-catalog.git     # Used for git operations
      revision: main

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

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

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

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

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

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

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

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

# Execute inside the tekton-hub-api pod for testing
$ kubectl exec -it deployment/tekton-hub-api -n <tekton-pipelines> -- /bin/sh

# Check if the catalog appears in the 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>"}]}

# Check catalog resources
$ 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":""}]}

# Verify specific resource
$ wget -qO- http://<your-tekton-hub-api>/v1/resource/<my-custom-catalog>/task/<my-task>

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

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

Проверьте, что ресурсы могут быть разрешены через Hub resolver:

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 app=tekton-hub-api -n <tekton-pipelines>
3. Проверьте логи API: kubectl logs deployment/tekton-hub-api -n <tekton-pipelines>

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

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

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

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

Решения:

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

#Сбой аутентификации SSH

Проблема: Отказано в доступе к private репозиторию

Решения:

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

#Сбой разрешения ресурсов

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

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

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

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

# Check available catalogs
$ wget -qO- http://<your-tekton-hub-api>/v1/catalogs

# Verify resource exists
$ wget -qO- http://<your-tekton-hub-api>/v1/resource/<my-custom-catalog>/task/<my-task>/<version>

# Check catalog sync status
$ kubectl logs deployment/tekton-hub-api -n <tekton-pipelines>

#FAQ

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

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

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

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

• SSH key не имеет достаточных прав для репозитория
• В файле known_hosts отсутствует fingerprint Git server
• SSH key не был корректно добавлен в deploy keys репозитория

Решение:

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

   # Test with the exact same SSH key and known_hosts
   $ git clone ssh://git@github.com:org/private-repo.git

2. Только после успешного локального clone обновите вашу Kubernetes environment:

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

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