#Добавление пользовательских каталогов в 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: Настройте API ConfigMap

Добавьте ваш пользовательский каталог в 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 catalogs (для внутреннего использования)
• provider: Указывает платформу Git для корректной интеграции API и аутентификации:
  • github: GitHub и GitHub Enterprise
  • gitlab: GitLab и GitLab self-hosted

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

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

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

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

• Для private repository: Необходимо указать и url, и sshurl — url требуется для хранения в database, а 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 всегда обязателен из-за ограничений database, даже если для private repositories используется sshurl.

#Шаг 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 должны содержать обязательные metadata
• Документация: Для каждого ресурса должны быть корректные README и examples

Подробные инструкции по созданию совместимых репозиториев каталога см. в 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

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

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

#Аутентификация для private repository

#Аутентификация по SSH Key

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

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

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

#Создание 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 сервера:

   # 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 URLs в конфигурации каталога

При настройке каталогов, требующих 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 repositories требуются и url (HTTPS), и sshurl (SSH). Для фактических операций git будет использоваться sshurl.

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

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

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

Советы: Значение по умолчанию для API endpoint Tekton Hub — 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>

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

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

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

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

Решения:

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

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

Проблема: Доступ к private repository запрещен

Решения:

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 на наличие ошибок, связанных с аутентификацией, таких как "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 обновляйте environment Kubernetes:

   • Обратитесь к разделу Generating known_hosts Entries, чтобы корректно сгенерировать файл 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>