Диагностика среды разработки

Начинайте диагностику с чтения состояния. Не исправляйте ошибку ручным изменением ресурсов, которыми управляет Garden или Helm.

Базовый набор проверок

cd ap-deploy

garden get linked-repos --env dev-local
garden validate --env dev-local
garden deploy agent-platform --env dev-local --plan
garden logs agent-platform --env dev-local --tail 100

Для Low-code IDE замените имя технической точки входа на langflow.

Проверьте кластер с явным kubeconfig и context:

kubectl \
  --kubeconfig "$HOME/.kube/ap-dev-local" \
  --context kind-ap-dev-local \
  get nodes

Текущее пространство имён разработчика:

DEV_NAMESPACE="ap-dev-$(id -un | tr '[:upper:]' '[:lower:]')"

kubectl \
  --kubeconfig "$HOME/.kube/ap-dev-local" \
  --context kind-ap-dev-local \
  -n "$DEV_NAMESPACE" \
  get pods,svc,pvc,httproute

Кластер отсутствует

Признаки:

• kubeconfig не найден;
• context kind-ap-dev-local отсутствует;
• Kubernetes API недоступен.

Проверьте:

kind get clusters
test -f "$HOME/.kube/ap-dev-local"

Если кластер не создан, выполните первичную настройку. Не направляйте Garden на другой кластер ради обхода ошибки.

Garden использует удалённый исходный код

Проверьте локальные соответствия:

garden get linked-repos --env dev-local

Если нужных действий нет:

python3 scripts/link_local_actions.py --check
python3 scripts/link_local_actions.py

Скрипт завершится ошибкой при неожиданном адресе удалённого репозитория Git или отсутствии соседнего рабочего каталога. Исправьте расположение репозитория либо укажите согласованный промежуточный удалённый репозиторий. Не редактируйте .garden/local-config.json вручную без необходимости.

LFX carrier не совпадает с Runtime lock

Ошибка carrier sourceRevision does not match the Runtime lock означает, что immutable LFX carrier был подменён текущим рабочим каталогом Langflow. Это не ошибка сборки Team Docs.

Обновите локальные соответствия и повторите только упавшую сборку:

python3 scripts/link_local_actions.py
garden build low-code-runtime-image --env dev-local

Актуальный helper заменяет устаревшую ссылку на live checkout отдельным detached worktree точно закреплённого коммита из Git-базы Langflow. Если коммит отсутствует, локальный Langflow develop отстаёт от composition baseline: обновите checkout через настроенный Git remote и повторите helper. Ручной перенос Git-объектов не требуется. Не исправляйте проблему ручным изменением lock или отключением проверки provenance.

Изменение кода не попало в среду

Убедитесь, что:

1. Изменён файл из рабочего каталога, показанного командой garden get linked-repos.
2. Файл входит в исходный набор соответствующего действия сборки.
3. Выполнено развёртывание правильной технической точки входа.
4. Новый Pod действительно заменил предыдущий.

Повторите развёртывание с подробными логами. Не меняйте файлы в .garden/build: это производный каталог.

Текущая конфигурация не выполняет постоянную синхронизацию файлов. Сохранение исходного файла само по себе не изменяет работающий контейнер.

Заняты локальные порты

Действие dev-local-edge-port-preflight проверяет порты 18085 и 18086 до запуска перенаправления.

Найдите процесс:

lsof -nP -iTCP:18085 -sTCP:LISTEN
lsof -nP -iTCP:18086 -sTCP:LISTEN

Частая причина — оставшийся процесс Garden или kubectl. Завершите именно этот процесс и повторите:

garden run dev-local-edge-forward --env dev-local

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

Docker не может собрать образ

Проверьте:

• запущен ли Docker;
• доступны ли требуемые процессор, память и место на диске;
• доступен ли источник базового образа;
• не мешает ли корпоративная сеть проверке TLS;
• относится ли ошибка к изменённому действию.

Garden передаёт сборке проверенный корпоративный набор центров сертификации. Не отключайте проверку TLS и не добавляйте небезопасный реестр как обходной путь.

Pod не готов

Получите список и описание проблемного Pod:

kubectl \
  --kubeconfig "$HOME/.kube/ap-dev-local" \
  --context kind-ap-dev-local \
  -n "$DEV_NAMESPACE" \
  get pods

kubectl \
  --kubeconfig "$HOME/.kube/ap-dev-local" \
  --context kind-ap-dev-local \
  -n "$DEV_NAMESPACE" \
  describe pod POD_NAME

Сначала установите причину: загрузка образа, нехватка ресурсов, ошибка готовности, миграция или постоянный том. После исправления повторите штатное развёртывание Garden. Не создавайте параллельный Deployment вручную.

Маршрут не работает

Проверьте HTTPRoute и локальную шлюзовую инфраструктуру:

kubectl \
  --kubeconfig "$HOME/.kube/ap-dev-local" \
  --context kind-ap-dev-local \
  -n "$DEV_NAMESPACE" \
  get httproute -o wide

kubectl \
  --kubeconfig "$HOME/.kube/ap-dev-local" \
  --context kind-ap-dev-local \
  -n agentgateway-system \
  get gateway,listenerset

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

Ошибка входа через Keycloak

Проверьте:

• точный публичный издатель OIDC;
• доступность документа обнаружения;
• адрес возврата приложения;
• отсутствие прямого обращения к внутреннему Service из браузера;
• состояние согласования идентификации.

curl -fsS \
  http://api-gw.localhost:18085/keycloak/realms/ap-dev/.well-known/openid-configuration \
  | jq '.issuer'

Ожидаемое значение:

http://api-gw.localhost:18085/keycloak/realms/ap-dev

Не исправляйте ошибку добавлением произвольного wildcard callback или Web Origin.

Тестовые данные отсутствуют

Убедитесь, что запускался явный сценарий тестовых данных:

garden deploy all-fixtures --env dev-local --yes

Обычный сценарий all не создаёт тестовых пользователей и агентов. Это ожидаемое поведение, а не ошибка развёртывания.

Как временно остановить Kind без удаления данных

У Kind нет штатных команд stop/start. На рабочей станции с Docker и GNU xargs можно остановить и позднее запустить узлы точного локального кластера как необязательную оптимизацию ресурсов:

alias kind-stop='docker ps -q --filter "label=io.x-k8s.kind.cluster=ap-dev-local" | xargs -r docker stop'
alias kind-start='docker ps -aq --filter "label=io.x-k8s.kind.cluster=ap-dev-local" | xargs -r docker start'

Перед kind-stop завершите процесс dev-local-edge-forward. После kind-start дождитесь готовности узла и заново запустите перенаправление:

kubectl \
  --kubeconfig "$HOME/.kube/ap-dev-local" \
  --context kind-ap-dev-local \
  wait node --all --for=condition=Ready --timeout=5m

garden run dev-local-edge-forward --env dev-local

Это удобство Docker-only, а не переносимый контракт Kind. Если кластер после запуска не восстанавливается, не чините его ручными изменениями Kubernetes: создайте точный disposable-кластер заново по инструкции первичной настройки.

Когда нужен полный сброс

Полный сброс допустим для одноразового dev-local, если данные не нужны и обычное повторное развёртывание не может исправить несовместимое изменение хранилища:

kind delete cluster \
  --name ap-dev-local \
  --kubeconfig "$HOME/.kube/ap-dev-local"

Команда необратимо удаляет все данные кластера. Она не применяется к ST и не является заменой разбору обычной ошибки приложения.