Диагностика проблем

Проблемы с запуском подов

Под находится в статусе `ImagePullBackOff` или `ErrImagePull`

Причина: Нет доступа к Docker registry или неверные credentials (если registry требует аутентификацию).

Примечание: По умолчанию registry.hexway.io не требует аутентификации.

Под в статусе `CrashLoopBackOff`

Причина: Приложение не может запуститься (проблемы с конфигурацией, БД, и т.д.).

Решение:

# Проверьте логи пода
kubectl logs -n $RELEASE_NAMESPACE <pod-name>

# Проверьте логи предыдущего контейнера (если под перезапускался)
kubectl logs -n $RELEASE_NAMESPACE <pod-name> --previous

# Проверьте события
kubectl describe pod -n $RELEASE_NAMESPACE <pod-name>

Типичные проблемы:

Нет доступа к БД: Проверьте настройки database.host, database.port и credentials
Неверные Secret references: Убедитесь, что Secret существует и содержит нужные ключи
Проблемы с правами: Проверьте securityContext и права на volumes
Ошибки при выполнении upgrade job: см. раздел «Проблемы с джобами»

Под в статусе `Pending`

Причина: Недостаточно ресурсов в кластере или проблемы с PVC.

Решение:

# Проверьте события пода
kubectl describe pod -n $RELEASE_NAMESPACE <pod-name>

# Проверьте доступные ресурсы на нодах
kubectl top nodes

# Проверьте PVC
kubectl get pvc -n $RELEASE_NAMESPACE

Возможные причины:

Недостаточно CPU/Memory на нодах
PVC не может быть создан (проблемы со StorageClass)
nodeSelector указывает на несуществующие ноды

Проблемы с джобами

Upgrade job завершилась с ошибкой

Проверки:

# Посмотрите статус pre-upgrade джобы
kubectl get jobs -n $RELEASE_NAMESPACE | grep "<RELEASE_NAME>-v-upgrade-migrations"

# Логи джобы, которая выполняет миграции
kubectl logs -n $RELEASE_NAMESPACE job/<release-name>-v-upgrade-migrations

Что делать:

Убедитесь, что у джобы есть доступ к необходимым Secret и ConfigMap
Проверьте, не упирается ли джоба в лимиты по CPU/Memory
Если ...-v-upgrade-migrations зависла, проверьте состояния БД и связанных сервисов, а также успешность применения миграций

Проблемы с подключением к БД

Ошибка: "Connection refused" или "Connection timeout"

Проверки:

# 1. Проверьте, доступен ли PostgreSQL из пода
kubectl exec -n $RELEASE_NAMESPACE -it <engine-pod-name> -- bash
# Внутри пода:
nc -zv your-postgres-host 5432
# или
ping your-postgres-host

# 2. Проверьте настройки БД в ConfigMap
kubectl get configmap -n $RELEASE_NAMESPACE ${RELEASE_NAME}-vampy-config -o yaml

# 3. Проверьте Secret с паролями
kubectl get secret -n $RELEASE_NAMESPACE ${RELEASE_NAME}-vampy-config -o yaml

Ошибка: "Authentication failed"

Решение:

# Проверьте корректность credentials в Secret
kubectl get secret ${RELEASE_NAME}-vampy-config -n $RELEASE_NAMESPACE -o jsonpath='{.data.EXT_PG_USERNAME}' | base64 -d
kubectl get secret ${RELEASE_NAME}-vampy-config -n $RELEASE_NAMESPACE -o jsonpath='{.data.EXT_PG_PASSWORD}' | base64 -d

# Пересоздайте Secret с правильными данными
kubectl delete secret ${RELEASE_NAME}-vampy-config -n $RELEASE_NAMESPACE
kubectl create secret generic ${RELEASE_NAME}-vampy-config \
  --namespace=$RELEASE_NAMESPACE \
  --from-literal=EXT_PG_USERNAME='correct_user' \
  --from-literal=EXT_PG_PASSWORD='correct_password'

# Перезапустите поды
kubectl rollout restart deployment -n $RELEASE_NAMESPACE ${RELEASE_NAME}-v-engine

Проблемы с Ingress

Ingress создан, но приложение недоступно

Проверки:

# 1. Проверьте статус Ingress
kubectl get ingress -n $RELEASE_NAMESPACE
kubectl describe ingress -n $RELEASE_NAMESPACE ${RELEASE_NAME}-v-deck

# 2. Убедитесь, что Ingress Controller установлен
kubectl get pods -n ingress-nginx
# или
kubectl get pods -A | grep ingress

# 3. Проверьте, что Service доступен
kubectl get svc -n $RELEASE_NAMESPACE ${RELEASE_NAME}-v-deck
kubectl port-forward -n $RELEASE_NAMESPACE service/${RELEASE_NAME}-v-deck 8080:8080
# Попробуйте открыть http://localhost:8080

Решение:

Установите Ingress Controller, если его нет
Проверьте, что ingressClassName соответствует вашему Ingress Controller
Убедитесь, что DNS настроен правильно

Проблемы с производительностью

Медленная работа системы

Диагностика:

# Проверьте использование ресурсов
kubectl top pods -n $RELEASE_NAMESPACE
kubectl top nodes

# Проверьте логи на предмет ошибок
kubectl logs -n $RELEASE_NAMESPACE -l app.kubernetes.io/component=${RELEASE_NAME}-v-engine --tail=100

# Проверьте статус БД
# Подключитесь к PostgreSQL и выполните:
# SELECT * FROM pg_stat_activity;
# SELECT * FROM pg_stat_database;

Решения:

1. Увеличьте ресурсы для компонентов:

vEngine:
  resources:
    limits:
      cpu: 4
      memory: 4Gi

2. Увеличьте количество реплик:

vEngine:
  replicas: 5

Сканирования выполняются очень долго

Причины и решения:

1. Недостаточно ресурсов на scan-нодах:

# Проверьте использование ресурсов
kubectl top nodes -l kubernetes.io/affinity-node-label=app-worker-scan

# Увеличьте ресурсы для сканеров

2. Мало воркеров для vOrchestration:

vOrchestration:
  workers:
    max: 8  # увеличьте максимальное количество

⚠️ Важно: При увеличении количества воркеров (max) необходимо следить за использованием ресурсов компонента vOrchestration. Если воркеры испытывают нехватку ресурсов (CPU или памяти), увеличьте соответствующие requests и limits:

vOrchestration:
  workers:
    max: 12  # увеличили количество воркеров
  resources:
    limits:
      cpu: 4      # увеличьте пропорционально количеству воркеров
      memory: 4Gi # увеличьте пропорционально количеству воркеров
    requests:
      cpu: 2      # увеличьте пропорционально количеству воркеров
      memory: 2Gi # увеличьте пропорционально количеству воркеров

Проверьте использование ресурсов после изменения:

kubectl top pods -n $RELEASE_NAMESPACE -l app.kubernetes.io/component=${RELEASE_NAME}-v-orchestration

3. Проблемы с доступом сканера Semgrep к внешним ресурсам:

Сканер Semgrep требует доступа к внешнему адресу https://semgrep.dev для загрузки правил и обновлений. Если в вашем кластере настроены сетевые политики или firewall, которые ограничивают исходящий трафик, сканер может не работать корректно.

Проверка:

# Проверьте логи orchestration на наличие ошибок подключения к semgrep.dev
kubectl logs -n $RELEASE_NAMESPACE -l app.kubernetes.io/component=${RELEASE_NAME}-v-orchestration | grep -i semgrep

# Проверьте доступность semgrep.dev из пода сканера (если возможно)
kubectl exec -n $RELEASE_NAMESPACE <scanner-pod-name> -- curl -I https://semgrep.dev

Решение:

Убедитесь, что сетевые политики Kubernetes разрешают исходящий HTTPS-трафик на semgrep.dev
Проверьте настройки firewall на уровне кластера или нод
Использование сетевых политик Kubernetes для точечного доступа: Чарт автоматически добавляет набор лейблов к подам сканеров при их создании. Вы можете использовать эти лейблы в сетевых политиках Kubernetes, чтобы разрешить доступ во внешнюю сеть только определенным сканерам (например, только Semgrep), в то время как другие сканеры не будут иметь такого доступа. Это позволяет настроить более строгую политику безопасности, предоставляя доступ к внешним ресурсам только тем сканерам, которым он действительно необходим.

4. Проблемы с доступом к образам сканеров:

# Проверьте логи orchestration
kubectl logs -n $RELEASE_NAMESPACE -l app.kubernetes.io/component=${RELEASE_NAME}-v-orchestration

Проблемы с PVC

PVC в статусе `Pending`

Причина: Проблемы со StorageClass или недостаточно места.

Решение:

# Проверьте статус PVC
kubectl describe pvc -n $RELEASE_NAMESPACE ${RELEASE_NAME}-v-postgres-pvc

# Проверьте доступные StorageClass
kubectl get storageclass

# Если нужно указать конкретный StorageClass
helm upgrade $RELEASE_NAME oci://registry.hexway.io/charts/vampy \
  --version $RELEASE_VERSION \
  -n $RELEASE_NAMESPACE \
  --reuse-values \
  --set vPostgres.pvc.storageClass="your-storage-class"

Проблемы с CA сертификатами

Ошибки SSL при подключении к внутренним сервисам

Симптомы: Ошибки вида "SSL certificate problem: unable to get local issuer certificate"

Решение:

Добавьте ваши корневые сертификаты через caBundle (см. раздел Добавление собственного корневого сертификата)
Убедитесь, что Secret с сертификатом создан до установки/обновления
Проверьте, что сертификаты в формате PEM или DER

Логи и отладка

Включение DEBUG логов

Для более подробных логов установите уровень DEBUG:

vEngine:
  logLevel: DEBUG

vBackground:
  logLevel: DEBUG

vOrchestration:
  logLevel: DEBUG

Сбор логов для поддержки

Параметр времени: Используйте флаг --since для указания периода времени, за который собираются логи. Примеры:

--since=1h - логи за последний час
--since=30m - логи за последние 30 минут
--since=24h - логи за последние 24 часа
--since=2026-01-01T00:00:00Z - логи с указанной даты и времени

Сбор логов всех компонентов:

# Экспортируем логи каждого pod в отдельный файл за последний час
for pod in $(kubectl get pods -n $RELEASE_NAMESPACE \
  -l app.kubernetes.io/instance=$RELEASE_NAME \
  -o name); do
  pod_name=${pod#pod/}
  kubectl logs -n $RELEASE_NAMESPACE "$pod" \
    --timestamps --since=1h 2>&1 > "vampy-${pod_name}-1h.log"
done

Сбор логов конкретных компонентов:

# Экспортируем логи каждого pod v-background-cpu-load в отдельный файл за последний час
for pod in $(kubectl get pods -n $RELEASE_NAMESPACE \
  -l app.kubernetes.io/component=${RELEASE_NAME}-v-background-cpu-load \
  -o name); do
  pod_name=${pod#pod/}
  kubectl logs -n $RELEASE_NAMESPACE "$pod" \
    --timestamps --since=1h 2>&1 > "vampy-${pod_name}-1h.log"
done

Список компонентов:

v-engine (Backend)
v-background (Background Workers в базовом режиме, без vBackgroundSeparated)
v-background-cpu-load (BackgroundSeparated: cpu-load scan/calc)
v-background-business-flow (BackgroundSeparated: business-flow)
v-background-high-priority-calc (BackgroundSeparated: high-priority-calc)
v-orchestration (Orchestration)
v-scheduling (Scheduling)
v-reports (Reports)
v-bro (Bro)
v-bro-background (Bro background workers)
v-deck (Frontend)
v-files (Files)
v-postgres (PostgreSQL, если используется встроенная БД)
v-pgbouncer (PgBouncer, если используется встроенная БД)
v-redis (Redis, если используется встроенный Redis)

Сбор диагностической информации:

# Экспорт состояния всех ресурсов
kubectl get all -n $RELEASE_NAMESPACE -o yaml 2>&1 > vampy-resources.yaml

# Экспорт событий (может быть пустым, если события очищены или их нет - это нормально)
# События полезны для диагностики проблем с ресурсами, образами, PVC, но автоматически очищаются через ~1 час
kubectl get events -n $RELEASE_NAMESPACE --sort-by='.lastTimestamp' 2>&1 > vampy-events.txt

# Экспорт конфигурации Helm
helm get values $RELEASE_NAME -n $RELEASE_NAMESPACE -o yaml 2>&1 > vampy-helm-values.yaml
helm get manifest $RELEASE_NAME -n $RELEASE_NAMESPACE 2>&1 > vampy-helm-manifest.yaml

# Список всех подов с их статусами
kubectl get pods -n $RELEASE_NAMESPACE -o wide 2>&1 > vampy-pods.txt

# Описание проблемных подов (если есть)
kubectl describe pods -n $RELEASE_NAMESPACE 2>&1 > vampy-pods-describe.txt

Примечания:

При выборе временного интервала учитывайте, что логи за большой период (24 часа и более) могут создать очень большие файлы
Если проблема возникла в конкретное время, используйте --since с указанием конкретной даты и времени
Логи отдельных компонентов удобнее для анализа, чем общий файл со всеми логами

Техническая поддержка

При возникновении проблем:

1. Проверьте документацию:

Раздел Диагностика проблем (эта страница)
Раздел Настройка production окружения
README.md в корне helm чарта

2. Соберите диагностическую информацию

Подробные команды для сбора диагностической информации см. в разделе Сбор логов для поддержки.

3. Обратитесь в техническую поддержку:

Email: support@hexway.io
При обращении приложите собранные логи и описание проблемы

Диагностика проблем

Проблемы с запуском подов

Под находится в статусе ImagePullBackOff или ErrImagePull

Под в статусе CrashLoopBackOff

Под в статусе Pending

Проблемы с джобами

Upgrade job завершилась с ошибкой

Проблемы с подключением к БД

Ошибка: "Connection refused" или "Connection timeout"

Ошибка: "Authentication failed"

Проблемы с Ingress

Ingress создан, но приложение недоступно

Проблемы с производительностью

Медленная работа системы

Сканирования выполняются очень долго

Проблемы с PVC

PVC в статусе Pending

Проблемы с CA сертификатами

Ошибки SSL при подключении к внутренним сервисам

Логи и отладка

Включение DEBUG логов

Сбор логов для поддержки

Техническая поддержка

Под находится в статусе `ImagePullBackOff` или `ErrImagePull`

Под в статусе `CrashLoopBackOff`

Под в статусе `Pending`

PVC в статусе `Pending`