#Справочник по командам tkn pac

Данное руководство предоставляет полный справочник по командам плагина CLI tkn pac, включая управление репозиториями, генерацию pipeline и их разрешение.

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

• установлен CLI tkn
• установлен плагин tkn pac
• kubectl настроен для доступа к вашему кластеру
• компонент PAC развернут

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

# Проверка CLI tkn
tkn version

Пример вывода:

Client version: 0.43.0
Pipeline version: v0.65.0

# Проверка плагина tkn-pac
tkn pac version

Пример вывода:

0.39.2

#Команды для работы с репозиториями

#tkn pac create repository

Создаёт новый репозиторий Pipelines as Code и namespace на основе шаблона pipeline run.

Основной синтаксис:

tkn pac create repo

Интерактивный режим:

Команда запросит у вас:

1. URL Git-репозитория (автоопределяется из текущей директории)
2. Namespace для pipeline (по умолчанию: project-pipelines)
3. Специфическую информацию провайдера Git (например, project ID для GitLab)
4. URL контроллера PAC (автоопределяется)
5. Секрет webhook (генерируется автоматически)
6. Токен доступа провайдера Git
7. URL API провайдера Git (зависит от провайдера)

Что делает команда:

• Создаёт объект Repository CR в вашем Kubernetes кластере
• Автоматически настраивает webhook провайдера Git
• Создаёт Kubernetes Secret с учётными данными провайдера Git
• Генерирует шаблон .tekton/pipelinerun.yaml в вашем репозитории

Пример:

cd /path/to/your/repo
tkn pac create repo

Пример вывода (интерактивные запросы):

? Enter the Git repository URL: https://gitlab.com/user/repo
? Enter the namespace where the pipeline should run (default: default): project-pipelines
? Enter the GitLab project ID: 12345678
? Enter the Pipelines as Code controller URL (default: http://pac.example.com): 
? Enter the webhook secret (default: auto-generated): 
? Enter the GitLab access token: glpat-xxxxxxxxxxxxxxxxxxxx
? Enter the GitLab API URL (default: https://gitlab.com): 
✓ Repository CR created successfully
✓ Webhook configured in GitLab
✓ Secret created
✓ Template generated at .tekton/pipelinerun.yaml

Для подробного использования смотрите Configure Repository.

#tkn pac list

Выводит список всех репозиториев Pipelines as Code и отображает последний статус связанных запусков.

Основной синтаксис:

tkn pac list

Список в конкретном namespace:

tkn pac list -n <namespace>

Формат вывода:

REPOSITORY          NAMESPACE          URL                                    LAST RUN STATUS
my-repo            project-pipelines  https://gitlab.com/user/repo       Succeeded
another-repo       production         https://gitlab.com/user/another    Running

Опции:

• -n, --namespace <namespace>: указать namespace для списка репозиториев (по умолчанию: namespace текущего контекста kubectl)
• -A, --all-namespaces: вывести репозитории во всех namespace
• -o, --output <format>: формат вывода (default, json, yaml, wide)

Примеры:

# Вывести все репозитории в текущем namespace
tkn pac list

# Вывести репозитории в конкретном namespace
tkn pac list -n project-pipelines

# Вывести репозитории во всех namespace
tkn pac list -A

#tkn pac repo describe

Отображает подробную информацию о репозитории Pipelines as Code и связанных запусках.

Основной синтаксис:

tkn pac repo describe <repository-name>

Опции:

• -n, --namespace <namespace>: указать namespace, где находится репозиторий (по умолчанию: namespace текущего контекста kubectl)
• -o, --output <format>: формат вывода (default, json, yaml)

Вывод включает:

• детали объекта Repository CR
• конфигурацию провайдера Git
• настройки webhook
• статус последних PipelineRun
• информацию о последнем запуске

Пример:

# Описать репозиторий в текущем namespace
tkn pac repo describe my-repo

# Описать репозиторий в конкретном namespace
tkn pac repo describe my-repo -n project-pipelines

Пример вывода:

Repository: my-repo
Namespace: project-pipelines
URL: https://gitlab.com/user/repo
Git Provider: gitlab
Status: Ready

Recent Runs:
  - pipelinerun-abc123: Succeeded (2 minutes ago)
  - pipelinerun-def456: Running (5 minutes ago)
  - pipelinerun-ghi789: Failed (10 minutes ago)

#Команда Generate

#tkn pac generate

Генерирует простой шаблон PipelineRun.

Основной синтаксис:

tkn pac generate

Возможности:

• Автоматически определяет текущую информацию Git из директории
• Использует базовое определение языка проекта
• Добавляет дополнительные задачи в зависимости от языка
• Создаёт шаблон .tekton/pipelinerun.yaml

Определение языка:

Команда определяет язык проекта и добавляет соответствующие задачи:

• Python: обнаруживает setup.py или requirements.txt, добавляет задачу pylint
• Go: обнаруживает go.mod, добавляет задачу golangci-lint
• Node.js: обнаруживает package.json, добавляет задачи npm
• Java: обнаруживает pom.xml, добавляет задачи maven

Пример:

# Перейти в ваш репозиторий
cd /path/to/your/repo

# Сгенерировать шаблон pipeline
tkn pac generate

Пример вывода:

✓ Pipeline template generated at .tekton/pipelinerun.yaml

Пример сгенерированного шаблона:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: generated-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineSpec:
    tasks:
    - name: hello
      taskSpec:
        steps:
        - name: echo
          image: alpine:latest
          script: |
            echo "Hello from generated pipeline!"

#Команда Resolve

#tkn pac resolve

Выполняет запуск pipeline как если бы он принадлежал сервису Pipelines as Code. Это полезно для локального тестирования определений pipeline без создания нового коммита.

Основной синтаксис:

tkn pac resolve -f <pipeline-file>

Опции:

• -f, --file: путь к файлу pipeline или директории (обязательно)
• -p, --param: переопределение значений параметров (формат: key=value)
• -o, --output: формат вывода (yaml, json или default)

Разрешение из файла:

tkn pac resolve -f .tekton/pull-request.yaml

Разрешение из директории:

tkn pac resolve -f .tekton/

Команда обработает все файлы с расширениями .yaml и .yml в директории.

Переопределение параметров:

Вы можете переопределить значения параметров, получаемых из Git-репозитория:

tkn pac resolve -f .tekton/pipelinerun.yaml \
  -p revision=main \
  -p repo_name=my-repo

Несколько файлов:

Можно использовать флаг -f несколько раз:

tkn pac resolve -f .tekton/pipeline1.yaml -f .tekton/pipeline2.yaml

Автоопределение:

При запуске из репозитория исходного кода команда пытается:

• Определить текущую информацию Git
• Автоматически разрешить параметры, такие как:
  • Текущая ревизия (SHA коммита)
  • Имя ветки
  • URL репозитория
  • Имя репозитория

Пример:

# Разрешить pipeline из текущей директории
cd /path/to/your/repo
tkn pac resolve -f .tekton/pipelinerun.yaml

Пример вывода:

Resolved pipeline:
- revision: abc1234
- repo_url: https://gitlab.com/user/repo
- branch: main
✓ Pipeline resolved successfully

Формат вывода:

Команда выводит разрешённый YAML PipelineRun в stdout. Вы можете:

• Сохранить в файл: tkn pac resolve -f .tekton/pipelinerun.yaml > resolved.yaml

• Просмотреть напрямую: tkn pac resolve -f .tekton/pipelinerun.yaml

• Использовать для валидации: проверить правильность разрешения переменных перед коммитом

  # Разрешить с пользовательскими параметрами
  tkn pac resolve -f .tekton/pipelinerun.yaml \
    -p revision=feature-branch \
    -p repo_name=custom-repo

Пример вывода:

Resolved pipeline:
- revision: feature-branch
- repo_url: https://gitlab.com/user/custom-repo
- branch: feature-branch
✓ Pipeline resolved successfully

Сценарии использования:

• Тестирование определений pipeline локально
• Отладка проблем pipeline без создания коммитов
• Валидация синтаксиса pipeline перед коммитом
• Тестирование разрешения параметров

#Глобальные опции

Все команды tkn pac поддерживают следующие глобальные опции:

• -h, --help: показать справку по команде
• -v, --version: показать информацию о версии
• --kubeconfig: путь к файлу kubeconfig
• --context: использовать указанный Kubernetes context

#Рекомендации по использованию

#1. Управление репозиториями

• Используйте описательные имена: выбирайте понятные имена репозиториев
• Организуйте по namespace: группируйте связанные репозитории в namespace
• Регулярный мониторинг: используйте tkn pac list для контроля состояния репозиториев

#2. Генерация pipeline

• Проверяйте сгенерированные шаблоны: всегда просматривайте и настраивайте сгенерированные pipeline
• Тестируйте локально: используйте tkn pac resolve для тестирования pipeline перед коммитом
• Контроль версий: коммитьте определения pipeline в Git

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

#Команда не найдена

Если команда tkn pac не найдена:

1. Проверьте установку:

   tkn pac version

   Пример вывода:

   0.39.2

2. Проверьте PATH: убедитесь, что tkn-pac находится в вашем PATH

3. Переустановите: при необходимости переустановите плагин

#Проблемы с подключением

Если команды не могут подключиться к кластеру:

1. Проверьте kubectl: протестируйте подключение kubectl
2. Проверьте контекст: убедитесь в правильности Kubernetes context
3. Проверьте права: убедитесь, что у вас есть необходимые разрешения

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

• Configure Repository - Руководство по настройке репозитория
• Incoming Webhooks - Запуск pipeline через webhooks
• Manage PAC Component - Управление компонентом PAC
• Common Issues - Руководство по устранению неполадок