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

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

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

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

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

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

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

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

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

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

Типовые сложности:

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

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

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

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

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

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

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

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

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

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

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

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

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

• Требования безопасности: настройка security contexts (например, runAsUser, fsGroup) в соответствии с политиками безопасности
• Доступ к private registry: настройка image pull secrets для доступа к private container registries
• Планирование на узлы: настройка node selectors, tolerations или правил affinity для управления размещением Pod
• Управление ресурсами: настройка вычислительных ресурсов, volumes и требований к хранилищу
• Переменные окружения: задание переменных окружения для выполнения Pipeline
• Сетевая конфигурация: настройка DNS policies и сетевых параметров
• Единообразие: обеспечение согласованной среды выполнения для нескольких запусков 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. Это влияет на все Tasks внутри PipelineRun, если они не переопределены через taskRunSpecs.

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

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

Сценарий использования: применение единообразной базовой конфигурации ко всем выполнениям 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 - Наивысший приоритет, применяется к конкретным Tasks
2. PipelineRun podTemplate или TaskRun podTemplate - Средний приоритет, применяется на уровне Pipeline или Task
3. Global default-pod-template - Самый низкий приоритет, применяется ко всем выполнениям

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

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

Пример:

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

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

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

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

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

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

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

#Пример 2: image pull secrets

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

Конфигурация 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: Планирование на узлы

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

Конфигурация 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 для переопределения на уровне конкретных Tasks, сохраняя безопасные значения по умолчанию для официальных 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 только для конкретных Tasks, которым действительно нужен root-доступ. Позвольте официальным Tekton Tasks использовать безопасное значение по умолчанию (65532).

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

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

Решение: переопределите глобальную конфигурацию на уровне PipelineRun для Pipelines, использующих официальные 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

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

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

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

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

• Имеют безопасное глобальное значение по умолчанию (runAsUser: 65532)
• Находятся в процессе миграции устаревших Pipelines
• Нуждаются во временных переопределениях во время обновления 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. Краткосрочно: используйте это переопределение для устаревших Pipelines, которым нужен root
2. Среднесрочно: обновите ваши пользовательские container images, чтобы они поддерживали пользователей без root-прав (UID 65532)
3. Долгосрочно: удалите эти переопределения и используйте безопасное глобальное значение по умолчанию

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

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

#Типовые ошибки

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

1. ❌ Установка глобального 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 для пользовательского образа завершилось сбоем для получения решений.

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

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

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

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

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

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

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

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

   securityContext:
     runAsUser: 65532
     runAsNonRoot: true
     fsGroup: 65532

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

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

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

6. Проверяйте изменения конфигурации: тестируйте изменения конфигурации шаблонов Pod в непроизводственной среде перед применением в production, особенно изменения 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 - Подробное описание шаблонов Pod, поддерживаемых полей и поведения при объединении
• Устранение неполадок: Создание Pod для пользовательского образа завершилось сбоем - Решения для типовых проблем настройки шаблонов Pod
• Настройка дополнительных параметров конфигурации - Общее руководство по настройке параметров TektonConfig
• Документация Kubernetes PodSpec - Официальная справка по Kubernetes PodSpec