#Руководство по настройке шаблонов Pod

#Быстрая навигация

Начало работы:

• Как настроить шаблоны Pod? - См. 4 способа настройки
• Какой метод следует использовать? - Руководство по выбору
• Как проверить мою конфигурацию? - Команды для проверки

Типовые сценарии:

• Моим пользовательским образам нужен доступ root - Как безопасно переопределить
• Я мигрировал с Tekton v3 с глобальным runAsUser: 0 - Как использовать официальные Tekton Tasks

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

• Создание моего Pod завершается сбоем - Проверьте распространенные ошибки и способы их устранения

#Зачем использовать шаблоны Pod?

При запуске Tekton Pipelines в продуктивных средах вы, скорее всего, столкнетесь со сценариями, когда конфигурация Pod по умолчанию не соответствует вашим требованиям:

Распространенные проблемы:

• Требования политики безопасности: Политики безопасности вашей организации требуют, чтобы все контейнеры запускались от пользователей без прав root, но некоторые выполнения Pipeline завершаются ошибками доступа.
• Доступ к частному registry: Ваш Pipeline использует пользовательские образы из частного registry, но Pod не могут загрузить образы из-за отсутствия учетных данных.
• Планирование ресурсов: Вам нужно, чтобы задачи сборки выполнялись на высокопроизводительных узлах с SSD-хранилищем, но Pod назначаются на обычные узлы, что приводит к медленной сборке.
• Мультиарендные среды: Разным командам требуются разные параметры безопасности, квоты ресурсов или размещение на узлах для своих Pipeline.
• Требования соответствия: Вы должны соответствовать определенным стандартам соответствия (PCI DSS, HIPAA и т. д.), которые предписывают конкретные настройки безопасности Pod.

Без шаблонов Pod:

Вам пришлось бы изменять отдельные определения Task или создавать несколько версий одной и той же Task с разными настройками, что приводит к:

• Дублированию конфигурации и дополнительным затратам на сопровождение
• Сложностям с обеспечением единых политик безопасности
• Невозможности адаптировать community Tasks (например, Tasks из Tekton catalog) под свою среду

Как шаблоны Pod решают эти проблемы:

Шаблоны Pod предоставляют гибкую многоуровневую систему конфигурации, которая позволяет:

• Задавать безопасные базовые настройки для всех Pipeline в вашем кластере
• При необходимости переопределять настройки для конкретных Pipeline или Task
• Использовать официальные Tasks из Tekton catalog и адаптировать их под свою среду
• Разделять логику Task и конфигурацию среды выполнения

#Что такое шаблоны Pod?

Шаблоны Pod — это поля конфигурации, которые позволяют настраивать спецификации Pod для ваших Tekton TaskRun и PipelineRun. Они определяют часть PodSpec, которую Tekton использует для настройки Pod, выполняющих ваши Task и Pipeline.

Шаблоны Pod можно настраивать на разных уровнях (глобальном, на уровне pipeline, на уровне task), что обеспечивает гибкость применения конфигурации с разными областями действия и приоритетами.

Подробную информацию о концепциях шаблонов Pod и поддерживаемых полях см. в разделе Концепции Pod Templates.

#Когда использовать шаблоны Pod

Шаблоны Pod полезны в следующих сценариях:

• Требования безопасности: Настройка security context (например, runAsUser, fsGroup) для соответствия политикам безопасности
• Доступ к частному registry: Настройка image pull secrets для доступа к частным container registry
• Планирование на узлах: Настройка node selector, toleration или правил affinity для управления размещением Pod
• Управление ресурсами: Настройка вычислительных ресурсов, томов и требований к хранилищу
• Переменные среды: Установка переменных среды для выполнения Pipeline
• Сетевая конфигурация: Настройка DNS policy и сетевых параметров
• Единообразие: Обеспечение согласованных сред выполнения для нескольких запусков Pipeline

#Какой метод настройки выбрать

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

#Как настроить шаблоны Pod

Шаблоны Pod можно настраивать на четырех разных уровнях, каждый из которых служит своим целям и имеет разный масштаб влияния.

#Метод 1: Конфигурация на уровне TaskRun

Настройте шаблон Pod непосредственно в TaskRun. Это влияет только на конкретное выполнение TaskRun.

Сценарий использования: Применение специальных настроек к отдельным выполнениям TaskRun.

Расположение конфигурации: spec.podTemplate в TaskRun

Пример:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: build-task-run
spec:
  taskRef:
    name: build-task
  podTemplate:
    securityContext:
      runAsUser: 65532  # Can be modified as needed (e.g., 0 for root, 1000 for custom user)
      fsGroup: 65532
    nodeSelector:
      disktype: ssd

#Метод 2: Конфигурация на уровне PipelineRun

Настройте шаблон Pod на уровне PipelineRun. Это влияет на все Task внутри PipelineRun, если они не переопределены через taskRunSpecs.

Сценарий использования: Применение единых настроек ко всем Task в выполнении Pipeline.

Расположение конфигурации: spec.taskRunTemplate.podTemplate в PipelineRun

Пример:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-pipeline-run
spec:
  pipelineRef:
    name: build-deploy-pipeline
  taskRunTemplate:
    podTemplate:
      securityContext:
        runAsUser: 65532  # Can be modified as needed (e.g., 0 for root)
        fsGroup: 65532
      nodeSelector:
        environment: production
      imagePullSecrets:
        - name: private-registry-secret

#Метод 3: Конфигурация PipelineRun TaskRunSpecs

Настройте шаблон Pod для конкретных Task внутри PipelineRun. Это позволяет выполнять тонкую настройку отдельных Task в Pipeline.

Сценарий использования: Применение разных настроек к разным Task в рамках одного выполнения Pipeline.

Расположение конфигурации: spec.taskRunSpecs[].podTemplate в PipelineRun

Пример:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-pipeline-run
spec:
  pipelineRef:
    name: build-deploy-pipeline
  taskRunSpecs:
    - pipelineTaskName: build
      podTemplate:
        securityContext:
          runAsUser: 0  # Override for this specific task if needed
        nodeSelector:
          disktype: ssd
          performance: high
        tolerations:
          - key: "dedicated"
            operator: "Equal"
            value: "build"
            effect: "NoSchedule"
    - pipelineTaskName: deploy
      podTemplate:
        securityContext:
          runAsUser: 65532  # Use secure default for this task
          runAsNonRoot: true
        nodeSelector:
          environment: production

#Метод 4: Глобальная конфигурация по умолчанию (TektonConfig)

Настройте глобальный шаблон Pod по умолчанию, который применяется ко всем TaskRun и PipelineRun в кластере.

Сценарий использования: Применение единых базовых настроек ко всем выполнениям Pipeline в кластере.

Расположение конфигурации: spec.pipeline.default-pod-template в TektonConfig

Шаги:

$ kubectl edit tektonconfigs.operator.tekton.dev config

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    default-pod-template: |
      securityContext:
        runAsUser: 65532
        fsGroup: 65532
      imagePullSecrets:
        - name: private-registry-secret

$ kubectl get configmap -n tekton-pipelines config-defaults -o yaml | grep 'default-pod-template: |' -A5

#Сравнение методов настройки

Правило приоритета: Если одно и то же поле настроено на нескольких уровнях, действует конфигурация с более высоким приоритетом. TaskRunSpecs (высший) > PipelineRun/TaskRun (средний) > Global (низший).

#Приоритет конфигурации

Конфигурации шаблонов Pod следуют четкой иерархии приоритетов. Когда для одного и того же поля существует несколько конфигураций, конфигурация с более высоким приоритетом переопределяет конфигурацию с более низким приоритетом.

Порядок приоритетов (от высшего к низшему):

1. PipelineRun taskRunSpecs podTemplate - Наивысший приоритет, применяется к конкретным task
2. PipelineRun podTemplate или TaskRun podTemplate - Средний приоритет, применяется на уровне pipeline или task
3. Глобальный default-pod-template - Низший приоритет, применяется ко всем выполнениям

Поведение при объединении:

• Переменные среды: Объединяются по имени; значения с более высоким приоритетом переопределяют значения с более низким приоритетом
• Тома: Объединяются по имени; значения с более высоким приоритетом переопределяют значения с более низким приоритетом
• Другие поля: Конфигурация с более высоким приоритетом полностью заменяет конфигурацию с более низким приоритетом

Пример:

Если у вас есть:

• Глобальная конфигурация: runAsUser: 65532 (безопасное значение по умолчанию)
• Конфигурация PipelineRun: runAsUser: 0 (переопределение для custom images)
• Конфигурация TaskRunSpec: runAsUser: 65532 (восстановление безопасного значения по умолчанию для официальных Tasks)

Результат будет следующим:

• Конкретная task (использующая официальную Task): runAsUser: 65532
• Другие task в pipeline (использующие custom images): runAsUser: 0

#Примеры конфигурации

#Пример 1: Безопасная конфигурация по умолчанию (рекомендуется)

Сценарий: Задать безопасную конфигурацию по умолчанию с пользователем без прав root для всех Task в Pipeline. Это рекомендуемая базовая конфигурация, соответствующая best practice в области безопасности.

Глобальная конфигурация:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    default-pod-template: |
      securityContext:
        runAsUser: 65532
        runAsNonRoot: true
        fsGroup: 65532
        fsGroupChangePolicy: "OnRootMismatch"

Примечание: Официальные Tekton Tasks и Tasks из catalog рассчитаны на работу с UID 65532. Эта конфигурация гарантирует, что все выполнения Pipeline будут по умолчанию запускаться безопасно.

#Пример 2: Image Pull Secrets

Сценарий: Настройка image pull secrets для доступа к private registry.

Конфигурация PipelineRun:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-pipeline-run
spec:
  pipelineRef:
    name: build-pipeline
  taskRunTemplate:
    podTemplate:
      imagePullSecrets:
        - name: private-registry-secret
        - name: enterprise-registry-secret

#Пример 3: Планирование на узлах

Сценарий: Запуск задач сборки на высокопроизводительных узлах.

Конфигурация TaskRunSpecs:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-pipeline-run
spec:
  pipelineRef:
    name: build-deploy-pipeline
  taskRunSpecs:
    - pipelineTaskName: build
      podTemplate:
        nodeSelector:
          disktype: ssd
          performance: high
        tolerations:
          - key: "dedicated"
            operator: "Equal"
            value: "build"
            effect: "NoSchedule"

#Пример 4: Переопределение для custom images, которым нужен доступ root

Сценарий: Глобальная конфигурация по умолчанию использует безопасного пользователя без прав root (65532), но у вас есть pipeline с custom images, которым нужен доступ root. Используйте TaskRunSpecs, чтобы переопределить настройки только для конкретных Task, сохраняя безопасные значения по умолчанию для официальных Tasks.

# Global baseline configuration (secure default)
apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    default-pod-template: |
      securityContext:
        runAsUser: 65532
        fsGroup: 65532
        fsGroupChangePolicy: "OnRootMismatch"
      imagePullSecrets:
        - name: default-registry-secret

---
# Pipeline execution with selective overrides
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: mixed-workload-pipeline-run
spec:
  pipelineRef:
    name: build-deploy-pipeline
  taskRunSpecs:
    # Override ONLY for tasks using custom images that require root
    - pipelineTaskName: custom-build
      podTemplate:
        securityContext:
          runAsUser: 0
        nodeSelector:
          disktype: ssd
    # Tasks using official Tekton catalog Tasks inherit the secure default (65532)
    # No override needed for 'git-clone', 'kaniko-build', etc.

Лучшая практика: Переопределяйте runAsUser на 0 только для конкретных task, которым действительно нужен доступ root. Официальные Tekton Tasks должны использовать безопасное значение по умолчанию (65532).

#Пример 5: Использование официальных Tasks с устаревшей глобальной конфигурацией

Сценарий: Вы мигрировали с Alauda DevOps Tekton v3 на Alauda DevOps Pipelines и задали глобальный default-pod-template со значением runAsUser: 0 для обратной совместимости с существующими custom images. Теперь вы хотите использовать официальные Tasks из Tekton catalog, которым требуются runAsUser: 65532 и fsGroup: 65532.

Решение: Переопределите глобальную конфигурацию на уровне PipelineRun для Pipeline, которые используют официальные Tasks.

Текущая глобальная конфигурация (задана во время миграции):

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    default-pod-template: |
      securityContext:
        runAsUser: 0  # Legacy global setting for custom images

Конфигурация PipelineRun для официальных Tasks:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: catalog-tasks-pipeline-run
spec:
  pipelineRef:
    name: pipeline-using-catalog-tasks  # Pipeline using git-clone, buildah, etc.
  taskRunTemplate:
    podTemplate:
      # Override global runAsUser: 0 to use secure settings required by official Tasks
      securityContext:
        runAsUser: 65532
        fsGroup: 65532

Альтернатива: Используйте TaskRunSpecs для смешанных сценариев:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: mixed-pipeline-run
spec:
  pipelineRef:
    name: mixed-pipeline
  # Most tasks will use global runAsUser: 0 (for custom images)
  taskRunSpecs:
    # Override only for tasks using official catalog Tasks
    - pipelineTaskName: git-clone
      podTemplate:
        securityContext:
          runAsUser: 65532
          fsGroup: 65532
    - pipelineTaskName: buildah
      podTemplate:
        securityContext:
          runAsUser: 65532
          fsGroup: 65532
    # Other tasks (using custom images) inherit global runAsUser: 0

Долгосрочная рекомендация: Постепенно обновите свои custom images, чтобы они поддерживали пользователей без прав root, а затем измените глобальное значение по умолчанию на runAsUser: 65532 для повышения безопасности.

#Пример 6: Временное переопределение во время активной миграции

Сценарий: Вы в данный момент мигрируете с Alauda DevOps Tekton v3 на Alauda DevOps Pipelines, и ваши custom images еще не обновлены для поддержки пользователей без прав root. Вам нужно временное решение, чтобы запускать устаревшие pipeline, пока вы обновляете образы.

Контекст: В отличие от Примера 5 (где миграция завершена и глобально используется runAsUser: 0), этот сценарий предназначен для пользователей, которые:

• Имеют безопасное глобальное значение по умолчанию (runAsUser: 65532)
• Активно мигрируют устаревшие pipeline
• Нуждаются во временных переопределениях при обновлении container images

Временная конфигурация PipelineRun:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: legacy-pipeline-run
spec:
  pipelineRef:
    name: legacy-pipeline-requiring-root
  taskRunTemplate:
    podTemplate:
      # Temporary override for migration - plan to remove this
      securityContext:
        runAsUser: 0

Путь миграции:

1. Краткосрочно: Используйте это переопределение для устаревших pipeline, которым нужен root
2. Среднесрочно: Обновите свои custom container images, чтобы они поддерживали пользователей без прав root (UID 65532)
3. Долгосрочно: Удалите эти переопределения и полагайтесь на безопасное глобальное значение по умолчанию

Важно: Это временное обходное решение на период активной миграции.

#Важные соображения

#Распространенные ошибки

Это наиболее частые проблемы, с которыми сталкиваются пользователи. Ознакомьтесь с ними перед настройкой шаблонов Pod:

1. ❌ Установка global runAsUser в 0: Не задавайте runAsUser: 0 в глобальном default-pod-template. Это нарушает лучшие практики безопасности и подвергает все выполнения Pipeline ненужному риску. Всегда используйте runAsUser: 65532 как глобальное значение по умолчанию. Если вам нужен доступ root, переопределяйте значение только на уровне TaskRun/PipelineRun.

2. ❌ Конфликты security context: Убедитесь, что параметры security context на уровне Task (например, runAsNonRoot: true) совместимы с security context шаблона Pod. Типичная ошибка: container's runAsUser breaks non-root policy. См. Устранение неполадок: Сбой создания Pod с custom image для решения.

3. ❌ Неверное понимание приоритета конфигурации: Помните, что конфигурации с более высоким приоритетом переопределяют конфигурации с более низким приоритетом:

   • TaskRunSpecs (высший) > PipelineRun/TaskRun (средний) > Global (низший)
   • Если конфигурация не применяется, проверьте наличие переопределений на более высоких уровнях приоритета.

4. ❌ Влияние глобальной конфигурации: Будьте осторожны при изменении глобального default-pod-template, так как это влияет на ВСЕ выполнения Pipeline в кластере. Сначала протестируйте изменения на TaskRun/PipelineRun.

5. ❌ Форматирование YAML: При настройке default-pod-template в TektonConfig используйте символ pipe (|) для корректного форматирования многострочной YAML-строки:

   default-pod-template: |
     securityContext:
       runAsUser: 65532

#Область применения и момент применения конфигурации

• Глобальная конфигурация: Влияет на все вновь создаваемые TaskRun и PipelineRun после применения конфигурации. Не влияет на уже выполняющиеся запуски.
• Конфигурация TaskRun/PipelineRun: Влияет только на конкретное выполнение.
• Изменения конфигурации: Вступают в силу немедленно для новых запусков. Перезапуск компонентов Tekton не требуется.

#Необходимые права

• Глобальная конфигурация: Требуются права уровня кластера для изменения ресурса TektonConfig (обычно cluster-admin или эквивалент).
• Конфигурация TaskRun/PipelineRun: Требуются права уровня namespace для создания/изменения ресурсов TaskRun или PipelineRun.

#Лучшие практики

1. Следуйте лучшим практикам безопасности: Всегда используйте пользователя без прав root (runAsUser: 65532) как глобальное значение по умолчанию. Официальные Tekton Tasks рассчитаны на работу с UID 65532. Переопределяйте значение на runAsUser: 0 только для конкретных task, которым требуются привилегии root.

2. Начинайте с безопасных глобальных значений по умолчанию: Настройте безопасные базовые параметры в глобальном default-pod-template:

   securityContext:
     runAsUser: 65532
     runAsNonRoot: true
     fsGroup: 65532

3. Переопределяйте выборочно: Если у вас есть custom images, которым нужен доступ root, переопределяйте настройки ТОЛЬКО на уровне TaskRun или taskRunSpecs для этих конкретных task. Не изменяйте глобальное значение по умолчанию на runAsUser: 0.

4. Используйте TaskRunSpecs для тонкой настройки: Когда разные task в pipeline требуют разных security context (например, custom images и официальные Tasks), используйте taskRunSpecs для применения разных конфигураций.

5. Документируйте исключения безопасности: Четко фиксируйте, почему конкретным task нужен доступ root (runAsUser: 0). Регулярно пересматривайте эти исключения, чтобы понять, можно ли их устранить.

6. Проверяйте изменения конфигурации: Перед применением в production тестируйте изменения конфигурации шаблонов Pod в непроизводственных средах, особенно изменения security context.

#Проверка

После применения конфигураций шаблонов Pod убедитесь, что они действительно применены:

#Для глобальной конфигурации

Проверьте, что конфигурация применена к ConfigMap:

# Check ConfigMap
$ kubectl get configmap -n tekton-pipelines config-defaults -o yaml | grep 'default-pod-template' -A 10

  default-pod-template: |
    securityContext:
      runAsUser: 65532

Ожидаемый вывод должен показывать настроенный вами шаблон Pod.

#Для конфигурации TaskRun/PipelineRun

Шаг 1: Найдите Pod, созданный вашим TaskRun или PipelineRun

# For TaskRun
$ kubectl get pods -n <namespace> -l tekton.dev/taskRun=<taskrun-name>

# For PipelineRun (shows all Pods created by the PipelineRun)
$ kubectl get pods -n <namespace> -l tekton.dev/pipelineRun=<pipelinerun-name>

# Example output:
# NAME                                      READY   STATUS      RESTARTS   AGE
# build-task-run-pod                        0/1     Completed   0          2m

Шаг 2: Проверьте спецификацию Pod

# Check the Pod's security context
$ kubectl get pod -n <namespace> <pod-name> -o yaml | grep -A 10 "securityContext:"

  securityContext:
    runAsUser: 65532
    fsGroup: 65532

# Check specific fields
$ kubectl get pod -n <namespace> <pod-name> -o jsonpath='{.spec.securityContext.runAsUser}'
# Should output: 65532 (or your configured value)

# Check fsGroup
$ kubectl get pod -n <namespace> <pod-name> -o jsonpath='{.spec.securityContext.fsGroup}'
# Should output: 65532 (or your configured value)

#Связанная документация

• Концепции Pod Templates - Подробное описание шаблонов Pod, поддерживаемых полей и поведения при объединении
• Устранение неполадок: Сбой создания Pod с custom image - Решения для распространенных проблем с настройкой шаблонов Pod
• Настройка дополнительных параметров конфигурации - Общее руководство по настройке параметров TektonConfig
• Документация Kubernetes PodSpec - Официальная справка по Kubernetes PodSpec