#Проверка ConfigMap

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

#Обзор

Webhook pruner проверяет ConfigMap для:

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

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

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

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

#1. Обязательные метки

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

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

Проверка включает:

• Обе метки должны присутствовать
• 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. Ограничения на селекторы

КРИТИЧНО: Селекторы (matchLabels/matchAnnotations) поддерживаются ТОЛЬКО в ConfigMap уровня namespace (tekton-pruner-namespace-spec), НЕЛЬЗЯ использовать в глобальных ConfigMap.

Допустимо — селекторы в ConfigMap namespace:

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 - Это ConfigMap уровня namespace
          - matchLabels:
              app: myapp
        ttlSecondsAfterFinished: 1800

Недопустимо — селекторы в глобальном 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:              # ПРОВЕРКА ЗАВАЛИТСЯ
              - 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

Почему такое ограничение?

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

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

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

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

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

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

• Имя: должно быть tekton-pruner-namespace-spec (фиксированное)
• Namespace: должен быть пользовательским namespace (НЕ системным или tekton namespace)
• Метка: 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:

• Системные 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 должны быть неотрицательными и не превышать глобальные максимумы, если они применяются
• Селекторы (только для ConfigMap namespace): селекторы меток и аннотаций должны содержать корректные пары ключ-значение; селекторы по имени должны быть валидными именами ресурсов

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

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

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

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

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

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

#Ошибка отсутствия меток

ConfigMap must have labels

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

labels:
  app.kubernetes.io/part-of: tekton-pruner
  pruner.tekton.dev/config-type: global  # или 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

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

• Глобальная: 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
# Затем удалите глобальную конфигурацию
kubectl delete cm tekton-pruner-default-spec -n tekton-pipelines

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

#Проверка статуса webhook

# Проверить конфигурацию webhook
kubectl get validatingwebhookconfigurations tekton-pruner-validating-webhook

# Проверить pod и сервис webhook
kubectl get pods,svc -n tekton-pipelines -l app.kubernetes.io/component=webhook

# Просмотреть логи webhook
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. Удалите идентифицирующую метку:

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

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

3. Восстановите метку:

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

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

#Рекомендуемые практики

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