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

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

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

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

#Установка плагина tkn pac

См. tkn pac Releases для получения последней версии.

Установите tkn pac, используя один из способов, описанных в официальном руководстве по релизам проекта tkn pac, и убедитесь, что исполняемый файл доступен в вашем PATH.

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

# Verify tkn CLI
tkn version

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

Client version: 0.43.0
Pipeline version: v0.65.0

# Verify tkn-pac plugin
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 (например, ID проекта для GitLab)
4. URL контроллера PAC (автоматически определяется)
5. Секрет webhook (генерируется автоматически)
6. Токен доступа Git-провайдера
7. URL API Git-провайдера (зависит от провайдера)

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

• Создает CR Repository в вашем Kubernetes-кластере
• Автоматически настраивает webhook Git-провайдера
• Создает Secret Kubernetes с учетными данными 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: Выводит список репозиториев во всех пространствах имен
• -o, --output <format>: Формат вывода (default, json, yaml, wide)

Пример:

# List all repositories in current namespace
tkn pac list

# List repositories in specific namespace
tkn pac list -n project-pipelines

# List repositories in all namespaces
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)

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

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

Пример:

# Describe repository in current namespace
tkn pac repo describe my-repo

# Describe repository in specific 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-данные из каталога
• Использует базовую возможность определения языка
• Добавляет дополнительные tasks в зависимости от определенного языка
• Создает шаблон .tekton/pipelinerun.yaml

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

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

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

Пример:

# Navigate to your repository
cd /path/to/your/repo

# Generate pipeline template
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

Выполняет PipelineRun так, как если бы им управлял сервис 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
• автоматически разрешить такие параметры, как:
  • текущий revision (commit SHA)
  • имя branch
  • URL репозитория
  • имя репозитория

Пример:

# Resolve pipeline from current directory
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

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

  # Resolve with custom parameters
  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

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

#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. Проверьте context: убедитесь, что контекст Kubernetes задан верно
3. Проверьте права доступа: убедитесь, что у вас есть необходимые разрешения

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

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