Skip to content

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

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

Под находится в статусе 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

Решение:

  1. Убедитесь, что сетевые политики Kubernetes разрешают исходящий HTTPS-трафик на semgrep.dev
  2. Проверьте настройки firewall на уровне кластера или нод
  3. Использование сетевых политик 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"

Решение:

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

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

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

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

vEngine:
  logLevel: DEBUG

vBackground:
  logLevel: DEBUG

vOrchestration:
  logLevel: DEBUG

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

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

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

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

# Экспорт логов всех подов за последний час
kubectl logs -n $RELEASE_NAMESPACE -l app.kubernetes.io/instance=$RELEASE_NAME \
  --all-containers=true --prefix --since=1h 2>&1 | cat > vampy-logs-all-1h.txt

# Экспорт логов всех подов за последние 24 часа (может быть большой файл)
kubectl logs -n $RELEASE_NAMESPACE -l app.kubernetes.io/instance=$RELEASE_NAME \
  --all-containers=true --prefix --since=24h 2>&1 | cat > vampy-logs-all-24h.txt

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

Backend (vEngine):

# Логи backend за последний час
kubectl logs -n $RELEASE_NAMESPACE -l app.kubernetes.io/component=${RELEASE_NAME}-v-engine \
  --all-containers=true --prefix --since=1h 2>&1 | cat > vampy-logs-backend-1h.txt

Background Workers (vBackground):

# Логи всех background workers за последний час (если используется базовый режим vBackground)
kubectl logs -n $RELEASE_NAMESPACE -l app.kubernetes.io/component=${RELEASE_NAME}-v-background \
  --all-containers=true --prefix --since=1h 2>&1 | cat > vampy-logs-background-1h.txt

# Логи всех cpu-load workers (scan и calc вместе, если используется vBackgroundSeparated)
kubectl logs -n $RELEASE_NAMESPACE -l app.kubernetes.io/component=${RELEASE_NAME}-v-background-cpu-load \
  --all-containers=true --prefix --since=1h 2>&1 | cat > vampy-logs-background-cpu-load-1h.txt


# Логи high-priority-calc workers
kubectl logs -n $RELEASE_NAMESPACE -l app.kubernetes.io/component=${RELEASE_NAME}-v-background-high-priority-calc \
  --all-containers=true --prefix --since=1h 2>&1 | cat > vampy-logs-background-high-priority-calc-1h.txt

# Логи business-flow workers
kubectl logs -n $RELEASE_NAMESPACE -l app.kubernetes.io/component=${RELEASE_NAME}-v-background-business-flow \
  --all-containers=true --prefix --since=1h 2>&1 | cat > vampy-logs-background-business-flow-1h.txt

Orchestration (vOrchestration):

# Логи orchestration за последние 30 минут
kubectl logs -n $RELEASE_NAMESPACE -l app.kubernetes.io/component=${RELEASE_NAME}-v-orchestration \
  --all-containers=true --prefix --since=30m 2>&1 | cat > vampy-logs-orchestration-30m.txt

Frontend (vDeck):

# Логи frontend за последний час
kubectl logs -n $RELEASE_NAMESPACE -l app.kubernetes.io/component=${RELEASE_NAME}-v-deck \
  --all-containers=true --prefix --since=1h 2>&1 | cat > vampy-logs-frontend-1h.txt

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

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

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

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

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

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

Примечания:

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

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

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

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

  • Раздел Диагностика проблем в этой инструкции
  • README.md в корне helm чарта
  • Документацию по production setup: production-setup-ru.md или production-setup-en.md

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

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

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

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