#Проверка ConfigMap

Tekton Pruner использует ValidatingWebhook, чтобы гарантировать, что ConfigMap соответствуют требуемым спецификациям до их создания или обновления в кластере. В этом документе объясняется, как работает проверка и какие требования должны быть выполнены.

#Обзор

Webhook pruner проверяет ConfigMap на соответствие следующим требованиям:

• Обеспечивать обязательные labels и соглашения об именовании
• Не допускать применения некорректных конфигураций
• Защищать от случайного удаления критически важных конфигураций
• Гарантировать, что конфигурации на уровне namespace соблюдают глобальные границы

#Как работает проверка

Webhook проверки автоматически устанавливается вместе с pruner и перехватывает операции CREATE, UPDATE и DELETE для ConfigMap. Он проверяет только те ConfigMap, у которых есть label app.kubernetes.io/part-of: tekton-pruner, поэтому обычные ConfigMap в вашем кластере не затрагиваются.

#Правила проверки

#1. Обязательные labels

Все ConfigMap pruner ДОЛЖНЫ иметь следующие labels:

metadata:
  labels:
    app.kubernetes.io/part-of: tekton-pruner
    pruner.tekton.dev/config-type: <global|namespace>

Проверки валидации:

• Должны присутствовать оба labels
• app.kubernetes.io/part-of должен быть равен tekton-pruner
• pruner.tekton.dev/config-type должен иметь значение global или namespace

Пример ошибки:

Invalid pruner ConfigMap labels: ConfigMap must have label app.kubernetes.io/part-of=tekton-pruner

#2. Ограничения на selectors

ВАЖНО: selectors (matchLabels/matchAnnotations) поддерживаются ТОЛЬКО в ConfigMap на уровне namespace (tekton-pruner-namespace-spec), НО НЕ в глобальных ConfigMap.

Допустимо — selectors в namespace ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-pruner-namespace-spec
  namespace: dev
  labels:
    app.kubernetes.io/part-of: tekton-pruner
    pruner.tekton.dev/config-type: namespace
data:
  ns-config: |
    pipelineRuns:
      - selector:                  # OK - This is a namespace ConfigMap
          - matchLabels:
              app: myapp
        ttlSecondsAfterFinished: 1800

Недопустимо — selectors в глобальном ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-pruner-default-spec
  namespace: tekton-pipelines
  labels:
    app.kubernetes.io/part-of: tekton-pruner
    pruner.tekton.dev/config-type: global
data:
  global-config: |
    namespaces:
      dev:
        pipelineRuns:
          - selector:              # WILL FAIL VALIDATION
              - matchLabels:
                  app: myapp
        ttlSecondsAfterFinished: 1800

Пример ошибки:

Invalid pruner configuration: global-config.namespaces.dev.pipelineRuns[0]: 
selectors are NOT supported in global ConfigMap. 
Use namespace-level ConfigMap (tekton-pruner-namespace-spec) instead

Почему действует это ограничение?

• Сопоставление ресурсов на основе selectors требует доступа к labels/annotations ресурса во время выполнения
• Глобальные ConfigMap предназначены для кластерных значений по умолчанию, а не для сопоставления с конкретными ресурсами
• ConfigMap уровня namespace обеспечивают корректную область действия для динамического выбора ресурсов

См. также: Resource Groups — примеры использования selectors

#3. Требования к именованию

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

• Имя: Должно быть tekton-pruner-default-spec (фиксированное)
• Namespace: Должен быть tekton-pipelines (или системный namespace)
• Label: pruner.tekton.dev/config-type: global

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

• Имя: Должно быть tekton-pruner-namespace-spec (фиксированное)
• Namespace: Должен находиться в пользовательском namespace (НЕ в системном namespace и НЕ в Tekton namespace)
• Label: pruner.tekton.dev/config-type: namespace

Примеры ошибок:

Global config must be named 'tekton-pruner-default-spec', got: my-custom-name

Namespace config must be named 'tekton-pruner-namespace-spec', got: pruner-config

#3. Ограничения на namespace

Запрещенные namespace для конфигураций уровня namespace:

• System namespace: kube-*
• Tekton namespace: tekton-pipelines, tekton-*

Попытка создать конфигурацию уровня namespace в этих местах будет отклонена.

Пример ошибки:

Invalid pruner ConfigMap configuration: wrong config-type label or namespace combination

#4. Проверка содержимого конфигурации

Webhook проверяет данные конфигурации, включая:

• Значения времени: ttlSecondsAfterFinished должен быть неотрицательным
• Ограничения истории: historyLimit, successfulHistoryLimit и failedHistoryLimit должны быть неотрицательными и не могут превышать глобальные максимумы, если они заданы
• Selectors (только для namespace ConfigMap): selectors по labels и annotations должны содержать допустимые пары ключ-значение; selectors по имени должны быть допустимыми именами ресурсов

Примечание: selectors (массивы pipelineRuns, taskRuns с matchLabels/matchAnnotations) обрабатываются только в ConfigMap уровня namespace. В глобальных ConfigMap они игнорируются.

#5. Защита от удаления

Webhook предотвращает удаление глобальной конфигурации, если namespace-level конфигурации все еще существуют. Перед удалением глобальной конфигурации необходимо удалить все namespace-конфигурации. Namespace-конфигурации можно удалять без ограничений.

#6. Принудительное применение глобальной конфигурации

При создании или обновлении конфигураций уровня namespace webhook получает глобальную конфигурацию и проверяет, что значения namespace не превышают глобальные максимумы, если они определены (например, maxTTLSecondsAfterFinished, maxHistoryLimit).

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

#Ошибка: отсутствуют labels

ConfigMap must have labels

Решение: Добавьте в ConfigMap обязательные labels:

labels:
  app.kubernetes.io/part-of: tekton-pruner
  pruner.tekton.dev/config-type: global  # or namespace

#Ошибка: неверный тип конфигурации

label pruner.tekton.dev/config-type must be 'global' or 'namespace', got: local

Решение: Используйте только значения global или namespace для config-type.

#Ошибка: неверное имя

Global config must be named 'tekton-pruner-default-spec', got: tekton-pruner-config

Решение: Используйте точное требуемое имя:

• Global: tekton-pruner-default-spec
• Namespace: tekton-pruner-namespace-spec

#Ошибка: превышен глобальный лимит

Invalid pruner configuration: namespace config ttlSecondsAfterFinished (172800) exceeds global maximum (86400)

Решение: Уменьшите значение в namespace до уровня, не превышающего глобальные ограничения, либо попросите администратора увеличить глобальный максимум.

#Ошибка: удаление заблокировано

Cannot delete global config: 2 namespace config(s) still exist

Решение: Сначала удалите все namespace-конфигурации:

kubectl delete cm tekton-pruner-namespace-spec -n dev
kubectl delete cm tekton-pruner-namespace-spec -n staging
# Then delete global config
kubectl delete cm tekton-pruner-default-spec -n tekton-pipelines

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

#Проверка состояния webhook

# Check webhook configuration
kubectl get validatingwebhookconfigurations tekton-pruner-validating-webhook

# Check webhook pod and service
kubectl get pods,svc -n tekton-pipelines -l app.kubernetes.io/component=webhook

# View webhook logs
kubectl logs -n tekton-pipelines -l app.kubernetes.io/component=webhook

#Проверка валидации

Создайте некорректный ConfigMap, чтобы убедиться, что webhook работает:

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-pruner-default-spec
  namespace: tekton-pipelines
data:
  global-config: |
    ttlSecondsAfterFinished: 300
EOF

Ожидаемая ошибка: admission webhook denied the request: Invalid pruner ConfigMap labels

#Обход проверки (не рекомендуется)

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

Чтобы временно обойти проверку:

1. Удалите идентифицирующий label:

   kubectl label cm tekton-pruner-default-spec -n tekton-pipelines \
     app.kubernetes.io/part-of-

2. Внесите необходимые изменения

3. Снова добавьте label:

   kubectl label cm tekton-pruner-default-spec -n tekton-pipelines \
     app.kubernetes.io/part-of=tekton-pruner

Примечание: Контроллер pruner не будет обрабатывать ConfigMap без корректных labels.

#Рекомендации

1. Сразу добавляйте обязательные labels с самого начала
2. Используйте точные соглашения об именовании для глобальных конфигураций и конфигураций namespace
3. Сначала проверяйте конфигурации в непроизводственном namespace
4. Внимательно изучайте ошибки валидации — они указывают, что нужно исправить
5. Следите за логами webhook при внедрении новых конфигураций
6. Удаляйте namespace-конфигурации перед попыткой удаления глобальной конфигурации