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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Дублированию конфигураций и усложнению поддержки
• Трудностям с обеспечением единых политик безопасности
• Невозможности адаптировать задачи из сообщества (например, из каталога 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: Безопасная конфигурация по умолчанию (рекомендуется)

Сценарий: Задать безопасную конфигурацию с непривилегированным пользователем для всех задач 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-доступа

Сценарий: Ваш глобальный дефолт использует безопасного непривилегированного пользователя (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

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

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

Сценарий: Вы сейчас мигрируете с Alauda DevOps Tekton v3 на Alauda DevOps Pipelines, и ваши кастомные образы ещё не обновлены для поддержки непривилегированного пользователя. Вам нужно временное решение для запуска устаревших 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. Среднесрочно: Обновите кастомные образы для поддержки непривилегированного пользователя (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. Следуйте лучшим практикам безопасности: Всегда используйте непривилегированного пользователя (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