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

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

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

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

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

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

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

Основные моменты:

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

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

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

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines  # namespace установки PAC
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 могут переопределять эти настройки при необходимости
• В каждом Repository CR по-прежнему нужно указывать url и другие специфичные для репозитория настройки

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

С глобальным 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 наследуются из глобального CR

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

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

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

Отредактируйте ваш 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
• Если не указано, ограничение отсутствует (неограниченное количество одновременных PipelineRuns)
• При достижении лимита новые события будут ставиться в очередь до завершения 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

Отслеживайте запущенные PipelineRuns:

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-провайдера (например, main, master или trunk).

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

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

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

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

Примечание: Согласно документации Red Hat OpenShift Pipelines, настройка default_branch рекомендуется как мера безопасности для максимальной проверки изменений pipeline в процессе ревью слияния.

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

Вы можете определить пользовательские параметры в Repository CR, которые будут расширяться во всех PipelineRuns, созданных для этого репозитория. Это удобно для задания общих значений для всех 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. Они ссылаются на параметры самого PipelineRun spec.params.

Ссылайтесь на параметры 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 - заменяется значением параметра Repository CR
  - name: cluster-name
    value: "{{ cluster-name }}"  # переменная PAC - заменяется значением параметра Repository CR
  - name: namespace
    value: "{{ namespace }}"  # переменная PAC - заменяется значением параметра Repository CR
  - name: revision
    value: "{{ revision }}"  # встроенная переменная PAC - заменяется SHA коммита
  pipelineSpec:
    tasks:
    - name: deploy
      taskSpec:
        steps:
        - name: deploy
          image: deploy-tool:latest
          script: |
            echo "Deploying to $(params.environment)"  # синтаксис параметров Tekton в скрипте
            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-репозитории: value: "{{ environment }}"
• PAC заменяет на: value: "production" (из параметра Repository CR)
• PipelineRun создаётся с: - name: environment / value: "production"
• Скрипты задач используют: $(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: проверяйте изменения в feature-ветках перед слиянием в исходную ветку
• Документируйте изменения: чётко фиксируйте, в какой ветке находятся определения pipeline

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

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

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

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

1. Проверьте, что лимит установлен:

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

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

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

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

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

   kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep concurrency  # Замените <pac-namespace> на ваш namespace (по умолчанию: 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. Проверьте синтаксис параметров: убедитесь, что используете синтаксис {{ param }} для параметров Repository CR, а не $(params.param)

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

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

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

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

• Configure Repository - Базовая настройка репозитория
• Maintain Pipeline Code - Руководство по определению pipeline
• Manage PipelineRuns - Управление PipelineRun
• Common Issues - Руководство по устранению неполадок