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

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

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

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

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

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

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

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

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

spec:
  concurrency_limit: 3

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

spec:
  concurrency_limit: 2

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

spec:
  # concurrency_limit not specified

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

Проверьте 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 в пользовательском ресурсе 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 и получить доступ к инфраструктуре сможет только тот пользователь, который имеет право вносить commits в ветку по умолчанию.

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

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

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

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

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

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

Добавьте параметры в поле 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

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

Важно: Параметры 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 params:

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. Ограничения параллелизма

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

#2. Настройка исходной ветки

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

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

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

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

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

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

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

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

2 # This is the concurrency limit

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

3. Проверьте логи PAC controller:

   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. Проверьте синтаксис параметров: убедитесь, что вы используете синтаксис {{ 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 - Руководство по устранению неполадок