#Расширенная конфигурация Repository

В этом руководстве описаны расширенные параметры конфигурации для Repository Custom Resources, включая:

• Глобальный Repository CR для автоматического наследования конфигурации (Tech Preview)
• Ограничения параллелизма
• Конфигурация исходной ветки
• Пользовательское расширение параметров

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

• Компонент PAC развернут и запущен
• Создан Repository CR (см. Руководства)
• Права cluster administrator или права на уровне namespace

#Создание глобального Repository CR

В качестве альтернативы вы можете создать глобальный Repository CR в namespace, где установлен PAC (обычно tekton-pipelines или namespace, указанный через targetNamespace в CR OpenShiftPipelinesAsCode). Если вы создадите Repository CR с именем pipelines-as-code в этом namespace, указанные в нем параметры будут автоматически применяться ко всем создаваемым вами Repository CR.

Ключевые моменты:

• Имя: Должно точно совпадать с pipelines-as-code
• Namespace: Должен находиться в namespace установки PAC (например, tekton-pipelines)
• Автоматическое применение: Параметры автоматически применяются ко всем Repository CR
• Tech Preview: Это функция Technology Preview

#Пример: глобальный Repository CR

Создайте глобальный Repository CR в namespace PAC:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines  # PAC installation namespace
spec:
  git_provider:
    secret:
      name: gitlab-webhook-config
      key: provider.token
    webhook_secret:
      name: gitlab-webhook-config
      key: webhook.secret

Примените CR:

kubectl apply -f global-repository.yaml

Поведение:

• Все создаваемые вами Repository CR будут наследовать эти настройки git_provider
• Отдельные Repository CR при необходимости могут переопределять эти настройки
• Вам по-прежнему нужно указывать url и другие настройки, специфичные для конкретного репозитория, в каждом Repository CR

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

С помощью глобального CR, приведенного выше, вы можете создавать отдельные Repository CR с минимальной конфигурацией:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-app-repo
  namespace: my-project
spec:
  url: "https://gitlab.com/user/my-app"
  # git_provider settings are inherited from the global CR

#Настройка ограничений параллелизма

Ограничения параллелизма помогают предотвратить исчерпание ресурсов, когда множество событий одновременно запускает pipelines. Вы можете задать максимальное количество одновременно выполняющихся PipelineRun для репозитория.

#Настройка ограничения параллелизма

Измените ваш Repository CR, добавив поле concurrency_limit:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  concurrency_limit: 5
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
    webhook_secret:
      name: webhook-secret
      key: secret

Важно:

• Минимальное значение — 1
• Если значение не указано, ограничение на число одновременно выполняющихся PipelineRun отсутствует
• Когда предел достигнут, новые события будут поставлены в очередь до завершения PipelineRun

#Примеры использования

Репозиторий с высоким трафиком: ограничьте число одновременных запусков, чтобы предотвратить перегрузку кластера:

spec:
  concurrency_limit: 3

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

spec:
  concurrency_limit: 2

Без ограничения (по умолчанию): разрешите неограниченное число одновременных запусков:

spec:
  # concurrency_limit не указан

#Проверка ограничения параллелизма

Проверьте Repository CR:

kubectl get repository my-repo -n project-pipelines -o yaml

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

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  concurrency_limit: 2

Отслеживайте выполняющиеся PipelineRun:

kubectl get pipelineruns -n project-pipelines | grep Running

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

NAME                    STARTED        DURATION   STATUS
simple-pipeline-xxxxx   2 minutes ago  30s        Running
test-pipeline-yyyyy     1 minute ago   45s        Running

#Изменение исходной ветки для определения Pipeline

По умолчанию Pipelines-as-Code получает определение PipelineRun из ветки, в которой было сгенерировано событие (например, из ветки push или pull request).

Вы можете изменить это поведение, используя поле spec.settings.pipelinerun_provenance в custom resource Repository. Этот параметр управляет тем, из какой ветки извлекается определение PipelineRun.

#Настройка источника определения PipelineRun

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
  settings:
    pipelinerun_provenance: "default_branch"

Поддерживаемые значения для pipelinerun_provenance:

• source: Поведение по умолчанию. Определение PipelineRun извлекается из ветки, в которой было сгенерировано событие.
• default_branch: Определение PipelineRun извлекается из ветки по умолчанию репозитория, как она настроена у Git provider (например, main, master или trunk).

#Преимущества в области безопасности

Разрешить пользователю задавать происхождение определения PipelineRun из ветки по умолчанию — это еще один уровень безопасности. Это гарантирует, что только пользователь, имеющий право сливать коммиты в ветку по умолчанию, может изменить определение PipelineRun и получить доступ к инфраструктуре.

• Предотвращает вредоносные изменения pipeline: Определения pipeline должны быть слиты в ветку по умолчанию, прежде чем их можно будет выполнить.
• Обеспечивает процесс review: Все изменения pipeline проходят стандартный процесс merge/review.
• Стабильное поведение pipeline: Все запуски используют одни и те же определения pipeline из ветки по умолчанию.

#Сравнение конфигураций

Примечание: Используйте default_branch, когда определения pipeline должны пройти процесс merge review в репозитории, прежде чем они смогут повлиять на будущие запуски.

#Пользовательское расширение параметров

Вы можете определить пользовательские параметры в Repository CR, которые будут подставляться во все PipelineRun, создаваемые для этого репозитория. Это полезно для задания общих значений для всех pipeline.

#Определение пользовательских параметров

Добавьте параметры в поле spec.params Repository CR:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  params:
  - name: environment
    value: "production"
  - name: cluster-name
    value: "prod-cluster"
  - name: namespace
    value: "production"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token

#Использование пользовательских параметров в pipeline

Важно: Параметры Repository CR используют синтаксис переменных PAC {{ param }}, а не синтаксис Tekton $(params.param).

• Переменные PAC ({{ variable }}): PAC подставляет их до создания PipelineRun. Сюда входят:

  • Параметры Repository CR из spec.params (например, {{ environment }}, {{ cluster-name }})
  • Встроенные переменные PAC (например, {{ revision }}, {{ repo_url }}, {{ source_branch }})

• Параметры Tekton ($(params.param)): Tekton разрешает их во время выполнения PipelineRun. Они ссылаются на собственные spec.params PipelineRun.

Ссылайтесь на параметры Repository CR в определениях PipelineRun, используя синтаксис переменных PAC:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: deploy-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  params:
  - name: environment
    value: "{{ environment }}"  # PAC variable - replaced with Repository CR param value
  - name: cluster-name
    value: "{{ cluster-name }}"  # PAC variable - replaced with Repository CR param value
  - name: namespace
    value: "{{ namespace }}"  # PAC variable - replaced with Repository CR param value
  - name: revision
    value: "{{ revision }}"  # PAC built-in variable - replaced with commit SHA
  pipelineSpec:
    tasks:
    - name: deploy
      taskSpec:
        steps:
        - name: deploy
          image: deploy-tool:latest
          script: |
            echo "Deploying to $(params.environment)"  # Tekton parameter syntax in script
            echo "Cluster: $(params.cluster-name)"
            echo "Namespace: $(params.namespace)"
            echo "Commit: $(params.revision)"

Как это работает:

1. До создания PipelineRun: PAC заменяет весь синтаксис {{ variable }} фактическими значениями из параметров Repository CR и встроенных переменных
2. Создание PipelineRun: PAC создает PipelineRun, в котором все переменные уже подставлены
3. Во время выполнения: Tekton разрешает синтаксис $(params.xxx), считывая значения из spec.params PipelineRun

Пример преобразования:

• В вашем Git repo: value: "{{ environment }}"
• PAC заменяет это на: value: "production" (из параметра Repository CR)
• PipelineRun создается с: - name: environment / value: "production"
• Скрипты Task используют: $(params.environment) → Tekton разрешает это в "production"

#Приоритет параметров

Параметры подставляются в следующем порядке (от наивысшего к наименьшему приоритету):

1. Параметры PipelineRun: Параметры, явно определенные в PipelineRun
2. Параметры Repository: Параметры, определенные в Repository CR
3. Динамические переменные: Динамические переменные PAC (например, {{ revision }}, {{ repo_url }})

#Пример: конфигурация для конкретной среды

Настройте разные среды с помощью параметров Repository:

Production Repository:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: prod-repo
  namespace: production
spec:
  url: "https://gitlab.com/user/prod-repo"
  params:
  - name: environment
    value: "production"
  - name: api-url
    value: "https://api.production.example.com"
  - name: registry
    value: "registry.production.example.com"

Staging Repository:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: staging-repo
  namespace: staging
spec:
  url: "https://gitlab.com/user/staging-repo"
  params:
  - name: environment
    value: "staging"
  - name: api-url
    value: "https://api.staging.example.com"
  - name: registry
    value: "registry.staging.example.com"

Оба репозитория могут использовать одно и то же определение pipeline, при этом параметры будут автоматически подставляться из Repository CR.

#Сочетание расширенных функций

Вы можете объединить все расширенные функции в одном Repository CR:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: advanced-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  concurrency_limit: 5
  params:
  - name: environment
    value: "production"
  - name: cluster-name
    value: "prod-cluster"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
    webhook_secret:
      name: webhook-secret
      key: secret

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

#1. Ограничения параллелизма

• Задавайте подходящие ограничения: Учитывайте ресурсы кластера и требования pipeline к ресурсам
• Контролируйте использование: Отслеживайте события, поставленные в очередь, если ограничения слишком низкие
• Динамически корректируйте: Увеличивайте ограничения в периоды высокой нагрузки и уменьшайте для экономии ресурсов

#2. Конфигурация исходной ветки

• Используйте стабильные ветки: Получайте определения pipeline из стабильных веток (например, main)
• Тестируйте изменения pipeline: Проверяйте изменения pipeline в feature-ветках перед слиянием в исходную ветку
• Документируйте изменения: Четко указывайте, в какой ветке находятся определения pipeline

#3. Пользовательские параметры

• Используйте понятные имена: Выбирайте ясные и описательные имена параметров
• Делайте значения простыми: Используйте простые строковые значения для параметров
• Документируйте параметры: Описывайте, что делает каждый параметр и когда он используется
• Избегайте секретов: Не храните secrets в параметрах Repository; вместо этого используйте Kubernetes Secrets

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

#Ограничение параллелизма не работает

1. Проверьте, что ограничение задано:

   kubectl get repository my-repo -n project-pipelines -o jsonpath='{.spec.concurrency_limit}'

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

2 # Это ограничение параллелизма

2. Проверьте наличие очереди событий: Найдите события, которые ожидают завершения PipelineRun

3. Проверьте логи контроллера PAC:

   kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep concurrency  # Replace <pac-namespace> with your actual namespace (default: tekton-pipelines)

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

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Concurrency limit reached","repository":"my-repo","limit":2,"running":2}
{"level":"info","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"PipelineRun queued","repository":"my-repo","reason":"concurrency_limit"}

#Параметры не подставляются

1. Проверьте, что параметры определены:

   kubectl get repository my-repo -n project-pipelines -o jsonpath='{.spec.params}'

2. Проверьте синтаксис параметров: Убедитесь, что для ссылки на параметры Repository CR используется синтаксис {{ param }}, а не $(params.param)

3. Проверьте замену переменных: Посмотрите созданный PipelineRun, чтобы убедиться, что PAC заменил переменные:

   kubectl get pipelinerun <run-name> -n <namespace> -o yaml | grep -A 5 "params:"

4. Проверьте PipelineRun: Убедитесь, не переопределяются ли параметры в определении PipelineRun

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

• Руководства — Пошаговые инструкции по базовой настройке repository
• Определение PipelineRun в Git — Файлы PipelineRun и trigger annotations
• Управление PipelineRun — Управление PipelineRun
• Распространенные проблемы — Руководство по устранению неполадок