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

На странице собраны типичные проблемы эксплуатации Stronghold, способы их диагностики и устранения. Перед началом диагностики проверьте общее состояние узла и кластера:

d8 stronghold status
d8 stronghold operator raft list-peers

Permission denied

Симптом — ошибка permission denied (HTTP-код 403) при обращении к пути.

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

1. Проверьте, какие политики привязаны к токену:

   d8 stronghold token lookup

2. Проверьте возможности (capabilities) токена на конкретном пути:

   d8 stronghold token capabilities secret/data/app/config

   Для чужого токена передайте его явно или используйте accessor через эндпоинт /sys/capabilities-accessor:

   d8 stronghold token capabilities <TOKEN> secret/data/app/config

3. Просмотрите содержимое политик:

   d8 stronghold policy read <POLICY_NAME>

Типичные причины:

• для KV v2 политика указана без сегмента data/ или metadata/ (например, secret/app/* вместо secret/data/app/*), как описано в разделе «KV v2»;
• путь закрыт явным правилом deny, которое имеет приоритет;
• запрос выполняется в другом пространстве имён;
• у токена истёк срок действия — d8 stronghold token lookup вернёт ошибку.

Подробнее о синтаксисе политик — в разделе «Политики».

Ошибки x509

Симптомы — ошибки x509: certificate signed by unknown authority, x509: certificate is valid for ..., not ..., x509: certificate has expired.

Проверить сертификат, который отдаёт сервер:

openssl s_client -connect stronghold.example.com:8200 -showcerts </dev/null | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

Для межузлового взаимодействия Raft (retry_join) те же ошибки появляются в журналах standby-узлов. Проверьте параметры leader_ca_cert_file, leader_client_cert_file и leader_client_key_file, описанные в разделе «Установка».

Узел запечатан после перезапуска

При использовании seal на основе Shamir каждый узел после перезапуска запускается запечатанным — это штатное поведение, описанное в разделе «Seal».

1. Проверьте состояние:

   d8 stronghold status

2. Распечатайте узел, введя пороговое количество ключей:

   d8 stronghold operator unseal

Если настроено автоматическое распечатывание (KMS или HSM), а узел остался запечатанным, проверьте в серверных журналах ошибки обращения к KMS/HSM: доступность сервиса, учётные данные, PIN или слот HSM.

В DP модуль в режиме Automatic инициализирует кластер с одной долей ключа и порогом 1. Ключ распечатывания и root-токен хранятся в секрете stronghold-keys (unsealKey, rootToken) в неймспейсе d8-stronghold. Узлы распечатывает Deployment stronghold-automatic (период проверки по умолчанию — 60 секунд). Если узел остаётся запечатанным, проверьте наличие секрета и журналы распечатывателя:

d8 k -n d8-stronghold get secret stronghold-keys
d8 k -n d8-stronghold logs deploy/stronghold-automatic

В режиме Manual нет ни секрета, ни распечатывателя: распечатывайте узлы вручную.

Потеря кворума Raft

Симптом — ошибка local node not active but active cluster node not found, кластер не выбирает лидера.

Кворум требует доступности большинства голосующих узлов: для 3 узлов — 2, для 5 узлов — 3. Если большинство узлов потеряно безвозвратно, выполните восстановление по инструкции:

• Восстановление после потери кворума в Linux;
• Восстановление после потери кворума в DP.

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

Нестабильные выборы лидера

Симптомы — в журналах часто появляются сообщения о переходе в состояние кандидата, клиенты получают кратковременные ошибки, активный узел меняется.

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

• проверьте метрики stronghold_raft_leader_lastContact и stronghold_raft_state_candidate, описанные в разделе «Мониторинг»;

• проверьте сетевую задержку и потери пакетов между узлами на порту кластера (cluster_addr, по умолчанию 8201);

• проверьте задержку диска с данными Raft (iostat -x 1); требования к диску приведены в разделе «Планирование ресурсов»;

• проверьте синхронизацию времени (NTP) на всех узлах;

• проверьте состояние Autopilot:

  d8 stronghold operator raft autopilot state

Типичные причины — перегруженный или сетевой диск с высокой задержкой, нехватка CPU при всплесках нагрузки, размещение узлов в разных площадках с большой задержкой, паузы процесса из-за нехватки памяти.

Медленные ответы и рост числа аренд

Симптомы — растёт время ответа, увеличивается потребление памяти и размер хранилища, медленно проходит запуск и смена лидера.

Частая причина — неконтролируемый рост количества аренд и токенов: клиенты заново аутентифицируются на каждый запрос вместо переиспользования токена, либо TTL аренд слишком большой.

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

1. Проверьте общее количество аренд через эндпоинт /sys/leases/count и метрику stronghold_expire_num_leases.

2. Найдите префиксы с наибольшим количеством аренд (для путей sys/leases/lookup/* нужна возможность sudo):

   d8 stronghold list sys/leases/lookup/auth/approle/login

3. Проверьте TTL в настройках методов аутентификации и механизмов секретов:

   d8 stronghold read sys/auth/approle/tune

Устранение:

• уменьшите default_lease_ttl и max_lease_ttl для проблемных точек монтирования;
• настройте клиентов на переиспользование и продление токенов (например, через Stronghold Agent);
• отзовите лишние аренды по префиксу: d8 stronghold lease revoke -prefix <PATH> (нужна возможность sudo на sys/leases/revoke-prefix/*);
• ограничьте нагрузку квотами.

Аудит-устройство блокирует запросы

Если ни одно аудит-устройство не может записать событие, Stronghold отклоняет запрос с ошибкой no audit backend succeeded in logging the request (или ... the response) либо запросы зависают до устранения проблемы. Подробнее — в разделе «Аудит в Stronghold».

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

1. Проверьте список аудит-устройств:

   d8 stronghold audit list -detailed

2. Для устройства file проверьте свободное место и права на запись в директорию журнала.

3. Для устройств syslog и socket проверьте доступность приёмника.

4. Проверьте метрики stronghold_audit_log_request_failure и stronghold_audit_log_response_failure.

Устранение — освободите место или восстановите приёмник. Держите не менее двух аудит-устройств, чтобы отказ одного не останавливал обслуживание запросов.

Проблемы входа

OIDC

• Ошибка redirect_uri или invalid redirect: URI перенаправления должен совпадать в параметре allowed_redirect_uris роли и в настройках провайдера. Для CLI используется http://localhost:8250/oidc/callback, для веб-интерфейса — адрес вида https://<STRONGHOLD_ADDR>/ui/stronghold/auth/oidc/oidc/callback. Подробнее — в разделе «OIDC».
• Ошибки проверки токена провайдера: проверьте oidc_discovery_url, oidc_client_id, а при собственном CA — oidc_discovery_ca_pem.
• Нет прав после входа: проверьте bound_claims, groups_claim и сопоставление групп с политиками.

LDAP

• Ошибка привязки (bind): проверьте binddn и bindpass, а также доступность сервера из всех узлов Stronghold.
• Ошибки TLS: при использовании ldaps:// или starttls укажите CA сервера в параметре certificate; не используйте insecure_tls в production.
• Пользователь входит, но не получает политики: проверьте groupdn, groupfilter и groupattr.

Подробнее — в разделе «LDAP».

Проблемы подов в DP

Проверьте состояние подов и события:

d8 k -n d8-stronghold get pods -o wide
d8 k -n d8-stronghold describe pod stronghold-0
d8 k -n d8-stronghold get events --sort-by=.lastTimestamp

Чтобы проверить состояние модуля, выполните команду:

d8 k get module stronghold

Сбор диагностических данных

Журналы уровня debug

Временно повысьте уровень логирования без перезапуска через эндпоинт /sys/loggers, как описано в разделе «Серверные журналы», и верните его после сбора данных.

Архив диагностики

Команда d8 stronghold debug собирает в архив состояние узла, метрики, профили pprof и журналы за заданный период:

d8 stronghold debug -duration=5m -interval=30s -output=stronghold-debug.tar.gz

Токен должен иметь права на чтение sys/config/state/sanitized, sys/metrics, sys/pprof/*, sys/host-info, sys/replication/status, sys/in-flight-req и sys/monitor. Передавайте полученный архив в поддержку по защищённому каналу: он содержит сведения о конфигурации и структуре кластера.