[Документация Yandex Cloud](../../index.md) > [Yandex Cloud Stackland](../index.md) > Диагностика и устранение неполадок

# Диагностика и устранение неполадок

В состав Stackland входит специализированный инструмент для сбора диагностической информации о состоянии кластера. `sladm diag` — утилита командной строки для Ubuntu 22.04 или аналогичного дистрибутива Linux. Как правило, `sladm diag` запускается с того же хоста, с которого выполнялось развертывание кластера Stackland.

В процессе своей работы `sladm diag` формирует архив, содержащий журнальные файлы инсталлятора, основных компонентов Stackland, а также ключевых ресурсов Kubernetes. Чувствительные данные не включаются в архив либо, если их присутствие необходимо для сохранения структурной целостности, заменяются строкой `<redacted>` (`PHJlZGFjdGVkPg==` в кодировке base64). Пользователь всегда может просмотреть содержимое архива и убедиться, что его отправка разработчикам Stackland допустима с точки зрения политик и регламентов, принятых в компании.

## Порядок сбора диагностики

Для запуска диагностики перейдите в папку, откуда осуществлялась установка Stackland. Убедитесь, что утилита `sladm` доступна, и наберите:

```bash
sladm diag
```

Процесс сбора информации занимает несколько минут. По завершении в текущем каталоге будет создан архив `diagnostics-YYYYMMDD-HHMMSS.tar.gz`, который следует отправить разработчикам.

Если `sladm diag` запускается не из папки, откуда выполнялась установка, укажите путь до выходных артефактов инсталлятора (папка `_out`) и журнальных файлов sladm:

```bash
sladm diag \
  --artifacts-dir /path/to/_out \
  --install-log /path/to/install.log
```

В отдельных случаях разработчики Stackland могут попросить собрать диагностику с дополнительных пространств имен Kubernetes. В этом случае добавьте ключ `--addns` (может повторяться несколько раз):

```bash
sladm diag \
  --addns some-namespace \
  --addns some-other-namespace
```

Имя выходного архива с диагностикой можно менять при помощи ключа `--output`:

```bash
sladm diag \
  --artifacts-dir /path/to/_out \
  --install-log /path/to/install.log \
  --output my-stackland-cluster.tar.gz
```

Архив с диагностикой будет собран даже в том случае, если сбор сведений завершился с ошибкой. В этом случае `sladm diag` напечатает соответствующее уведомление. Свяжитесь с разработчиком для уточнения дальнейших действий.

## Секреты не подставляются в под {#secrets-not-injected}

Если Secrets Injector не подставляет секреты в переменные окружения или файлы конфигурации, смотрите раздел [Диагностика Secrets Store](secrets-store/troubleshooting.md). Там описаны типичные причины: неправильное расположение аннотаций, отсутствие поля `command`, ошибки при настройке роли в Secrets Store и другие.

## Доступ к talosctl для продвинутой диагностики {#talosctl-access}

{% note alert %}

`talosctl` — это нештатный механизм доступа к узлам кластера, который не предназначен для обычной эксплуатации. Неправильное использование `talosctl` может привести к нарушению работы кластера или потере данных.

Используйте `talosctl` только для продвинутой диагностики проблем и только если вы понимаете последствия выполняемых команд.

{% endnote %}

### Где находится talosconfig {#talosconfig-location}

После успешной установки Stackland административный конфигурационный файл `talosconfig` создается автоматически и сохраняется в директории инсталлятора на бастионе:

```
_out/talosconfig
```

Этот файл содержит учетные данные для доступа к узлам кластера через `talosctl`.

### Базовое использование talosctl {#talosctl-usage}

Загрузите утилиту `talosctl` с [сайта проекта](https://github.com/siderolabs/talos/releases/tag/v1.11.6).

Для работы с кластером укажите путь к конфигурационному файлу:

```bash
export TALOSCONFIG=_out/talosconfig
_out/bin/talosctl --nodes <IP-адрес узла> <команда>
```

Примеры команд для диагностики:

* Просмотр логов системных сервисов:

  ```bash
  _out/bin/talosctl --nodes 192.168.22.2 logs kubelet
  ```

* Проверка состояния узла:

  ```bash
  _out/bin/talosctl --nodes 192.168.22.2 health
  ```

* Просмотр списка запущенных сервисов:

  ```bash
  _out/bin/talosctl --nodes 192.168.22.2 services
  ```

* Получение информации о дисках:

  ```bash
  _out/bin/talosctl --nodes 192.168.22.2 disks
  ```

Полный список команд и их описание доступен в [официальной документации Talos](https://www.talos.dev/latest/reference/cli/).

### Ограничения и риски {#talosctl-limitations}

При использовании `talosctl` учитывайте следующее:

* Прямое изменение конфигурации узлов через `talosctl` может привести к рассинхронизации с состоянием кластера Stackland.
* Некоторые операции (например, перезагрузка узлов или изменение сетевых настроек) могут временно нарушить доступность сервисов.
* Используйте `talosctl` только для получения информации или точечных правок настроек командой `talosctl mc patch`. Вы выведете из строя кластер и потеряете данные, используя другие пишущие команды.
* Доступ к `talosconfig` должен быть ограничен, так как он предоставляет полный административный доступ к узлам кластера.

Для штатной эксплуатации кластера используйте `kubectl` и другие стандартные инструменты Kubernetes.

## sladm остановился из-за временной недоступности узла {#rerun-sladm}

Если в логе есть сообщение `Node is not running+ready in configured state`, а затем установка завершилась с ошибкой, проверьте текущее состояние узлов:

```bash
kubectl get nodes -o wide
```

Если все узлы находятся в состоянии `Ready`, повторите команду установки:

```bash
./sladm install --config config/ --installation-timeout 2h 2>&1 | tee install-rerun-$(date +%y%m%d-%H%M).log
```

Повторный запуск безопасен: `sladm` повторно сверит состояние узлов и компонентов и продолжит установку.

## В storage остались задания в состоянии `Failed` от предыдущей попытки {#storage-failed-jobs}

Если `sladm` завершился сообщением `Your Stackland cluster is ready`, а `platformconfig` перешел в состояние `Installed`, но в пространстве имен `stackland-storage` остались старые поды или задания в состоянии `Error` или `Failed`, проверьте актуальное состояние заданий и операторов:

```bash
kubectl get platformconfig main -o jsonpath='{.status.initialInstall.state}{"\n"}'
kubectl get jobs -A | grep -E 'storage|s3|mds|nscfg|gosper' || true
kubectl get pod -n stackland-storage -o wide
kubectl get pod -n stackland-storage-goose -o wide
kubectl get pod -n stackland-storage-mds2 -o wide
```

Если повторные задания завершились в состоянии `Complete`, а операторы storage находятся в состоянии `Running`, старые задания в состоянии `Failed` относятся к предыдущим попыткам установки. Они не блокируют доступ к консоли управления, но могут оставаться в выводе диагностических команд до очистки истории заданий.

## Компонент monitoring остается в состоянии Updating {#monitoring-updating}

Если `monitoring-main` долго остается в состоянии `Updating`, проверьте поды в пространстве имен `stackland-monitoring`:

```bash
kubectl get pod -n stackland-monitoring
kubectl describe pod -n stackland-monitoring <имя_пода>
kubectl logs -n stackland-monitoring <имя_пода> --previous --tail=100
```

Если под `kube-state-metrics` завершался с причиной `OOMKilled`, дождитесь следующей сверки компонента или повторите запуск `sladm install`. Если проблема повторяется, увеличьте ресурсы компонента мониторинга.

### Установка прервалась из-за недоступности Kubernetes API {#kubernetes-api-unreachable}

Во время установки узлы несколько раз перезагружаются. В этот момент в логах могут появляться временные ошибки доступа к Kubernetes API, например `Kubernetes cluster unreachable`. Дождитесь, пока Talos API всех узлов и Kubernetes API станут доступны:

```bash
nc -vz 192.168.22.2 50000
nc -vz 192.168.22.3 50000
nc -vz 192.168.22.4 50000
nc -vz 192.168.22.127 6443
```

Замените адреса на значения из вашей конфигурации. После восстановления доступности перезапустите `sladm install` той же командой. Инсталлятор продолжит установку с уже выполненных этапов.

### Установка прервалась во время настройки компонентов {#components-not-ready}

Если `sladm` завершился с ошибкой на этапе настройки платформенных компонентов, сначала проверьте текущее состояние кластера. Ошибка в старом логе может уже не соответствовать текущему состоянию ресурсов:

```bash
kubectl get componentinstallations.stackland.yandex.cloud
kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded
kubectl get events -A --field-selector type=Warning --sort-by=.lastTimestamp
```

Если в выводе `ComponentInstallation` есть фазы `Installing`, `Updating` или `Error`, проверьте описание соответствующего ресурса:

```bash
kubectl describe componentinstallation <componentinstallation_name>
```

После устранения причины ошибки повторно запустите `sladm install` с тем же `--config`. Если узлы уже установлены и доступны по Talos API, отключите PXE/DHCP для повторного запуска:

```bash
sladm install \
  --config config/ \
  --installation-timeout 3h
```

Дождитесь, пока `sladm` завершится успешно. После этого повторите проверки из раздела [Проверьте установку](#verification).

### Истек таймаут установки {#installation-timeout}

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

```bash
sladm install \
  --config config/ \
  --dhcp-interface eth1 \
  --pxe-folder ./pxe \
  --installation-timeout 3h
```

### sladm игнорирует DHCP-запросы узла {#unknown-mac}

Если сетевой загрузчик узла не получает адрес, проверьте MAC-адрес в конфигурации. Он должен совпадать с MAC-адресом сетевого интерфейса, через который сервер загружается по PXE. Если загрузчик получает адрес, но не пытается загружаться дальше, проверьте, что в сети не работает другой DHCP-сервер.