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

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

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

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

Распространённые сценарии:

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

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

• Создание Pod завершается с ошибкой — Проверьте распространённые ошибки и решения

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Требования безопасности: настройка securityContext (например, runAsUser, fsGroup) для соответствия политикам безопасности
• Доступ к приватным реестрам: настройка image pull secrets для доступа к приватным контейнерным реестрам
• Планирование узлов: настройка nodeSelector, tolerations или affinity для управления размещением Pod
• Управление ресурсами: настройка ресурсов вычислений, томов и требований к хранилищу
• Переменные окружения: установка переменных окружения для выполнения Pipeline
• Сетевые настройки: настройка DNS-политик и сетевых параметров
• Согласованность: обеспечение единых сред выполнения для множества запусков 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  # Можно изменить по необходимости (например, 0 для root, 1000 для кастомного пользователя)
      fsGroup: 65532
    nodeSelector:
      disktype: ssd

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

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

Сценарий использования: Применить единые настройки ко всем задачам в запуске 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  # Можно изменить по необходимости (например, 0 для root)
        fsGroup: 65532
      nodeSelector:
        environment: production
      imagePullSecrets:
        - name: private-registry-secret

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

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

Сценарий использования: Применить разные настройки к разным задачам в одном запуске 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  # Переопределение для этой конкретной задачи при необходимости
        nodeSelector:
          disktype: ssd
          performance: high
        tolerations:
          - key: "dedicated"
            operator: "Equal"
            value: "build"
            effect: "NoSchedule"
    - pipelineTaskName: deploy
      podTemplate:
        securityContext:
          runAsUser: 65532  # Использовать безопасный дефолт для этой задачи
          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 (средний) > Глобальный (низший).

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

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

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

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

Поведение слияния:

• Переменные окружения: сливаются по имени; значения с более высоким приоритетом переопределяют нижестоящие
• Тома (volumes): сливаются по имени; значения с более высоким приоритетом переопределяют нижестоящие
• Другие поля: конфигурация с более высоким приоритетом полностью заменяет нижестоящую

Пример:

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

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

То результат будет:

• Конкретная задача (официальная): runAsUser: 65532
• Другие задачи в Pipeline (кастомные образы): runAsUser: 0

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

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

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

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

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 и задачи из каталога рассчитаны на работу с UID 65532. Эта конфигурация гарантирует безопасное выполнение всех Pipeline по умолчанию.

#Пример 2: Секреты для загрузки образов

Сценарий: Настроить image pull secrets для доступа к приватным реестрам.

Конфигурация 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: Переопределение для кастомных образов с root-доступом

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

# Глобальная базовая конфигурация (безопасный дефолт)
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 с выборочными переопределениями
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: mixed-workload-pipeline-run
spec:
  pipelineRef:
    name: build-deploy-pipeline
  taskRunSpecs:
    # Переопределение ТОЛЬКО для задач с кастомными образами, требующими root
    - pipelineTaskName: custom-build
      podTemplate:
        securityContext:
          runAsUser: 0
        nodeSelector:
          disktype: ssd
    # Задачи с официальными задачами из каталога Tekton наследуют безопасный дефолт (65532)
    # Переопределение для 'git-clone', 'kaniko-build' и т.п. не требуется

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

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

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

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

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

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    default-pod-template: |
      securityContext:
        runAsUser: 0  # Устаревшая глобальная настройка для кастомных образов

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

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: catalog-tasks-pipeline-run
spec:
  pipelineRef:
    name: pipeline-using-catalog-tasks  # Pipeline с git-clone, buildah и др.
  taskRunTemplate:
    podTemplate:
      # Переопределение глобального runAsUser: 0 на безопасные настройки для официальных задач
      securityContext:
        runAsUser: 65532
        fsGroup: 65532

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

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: mixed-pipeline-run
spec:
  pipelineRef:
    name: mixed-pipeline
  # Большинство задач используют глобальный runAsUser: 0 (для кастомных образов)
  taskRunSpecs:
    # Переопределение только для задач с официальными задачами из каталога
    - pipelineTaskName: git-clone
      podTemplate:
        securityContext:
          runAsUser: 65532
          fsGroup: 65532
    - pipelineTaskName: buildah
      podTemplate:
        securityContext:
          runAsUser: 65532
          fsGroup: 65532
    # Другие задачи (с кастомными образами) наследуют глобальный runAsUser: 0

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

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

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

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

• Безопасный глобальный дефолт (runAsUser: 65532)
• Активная миграция устаревших Pipeline
• Необходимы временные переопределения при обновлении образов

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

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: legacy-pipeline-run
spec:
  pipelineRef:
    name: legacy-pipeline-requiring-root
  taskRunTemplate:
    podTemplate:
      # Временное переопределение для миграции — планируется убрать
      securityContext:
        runAsUser: 0

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

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

Важно: Это временное решение на время активной миграции.

#Важные замечания

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

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

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

2. ❌ Конфликты securityContext: Убедитесь, что настройки securityContext на уровне задачи (например, runAsNonRoot: true) совместимы с securityContext шаблона Pod. Частая ошибка: container's runAsUser breaks non-root policy. Решения смотрите в Troubleshooting: Custom Image Pod Creation Failed.

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

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

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 рассчитаны на UID 65532. Переопределяйте на runAsUser: 0 только для задач, которым действительно нужен root.

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

   securityContext:
     runAsUser: 65532
     runAsNonRoot: true
     fsGroup: 65532

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

4. Используйте TaskRunSpecs для тонкого контроля: Если разные задачи в Pipeline требуют разных securityContext (например, кастомные образы и официальные задачи), применяйте разные конфигурации через taskRunSpecs.

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

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

#Проверка

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

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

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

# Проверка 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

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

# Для PipelineRun (показывает все Pods, созданные PipelineRun)
$ kubectl get pods -n <namespace> -l tekton.dev/pipelineRun=<pipelinerun-name>

# Пример вывода:
# NAME                                      READY   STATUS      RESTARTS   AGE
# build-task-run-pod                        0/1     Completed   0          2m

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

# Проверка securityContext Pod
$ kubectl get pod -n <namespace> <pod-name> -o yaml | grep -A 10 "securityContext:"

  securityContext:
    runAsUser: 65532
    fsGroup: 65532

# Проверка конкретных полей
$ kubectl get pod -n <namespace> <pod-name> -o jsonpath='{.spec.securityContext.runAsUser}'
# Должно вывести: 65532 (или ваше настроенное значение)

# Проверка fsGroup
$ kubectl get pod -n <namespace> <pod-name> -o jsonpath='{.spec.securityContext.fsGroup}'
# Должно вывести: 65532 (или ваше настроенное значение)

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

• Pod Templates Concepts — Подробное объяснение шаблонов Pod, поддерживаемых полей и поведения слияния
• Troubleshooting: Custom Image Pod Creation Failed — Решения распространённых проблем с конфигурацией шаблонов Pod
• Adjusting Optional Configuration Items — Общее руководство по настройке опций TektonConfig
• Документация Kubernetes PodSpec — Официальная справка по PodSpec Kubernetes