Путь разработки

О документе

Руководство предназначено для разработчиков компонентов Платформы ИИ. Оно описывает поддерживаемый способ получить интегрированную локальную среду (dev-local), проверить изменение и подготовить результат к слиянию.

Актуальная информация о структуре компонентов и операторском развёртывании — в Состав компонентов платформы и Развёртывание платформы. Здесь приведены только те сведения, которые относятся к локальной среде разработчика.

Что такое Garden

Garden — инструмент оркестрации процесса разработки в Kubernetes. Он описывает среду как граф сборки, настройки и развёртывания. Разработчик выбирает требуемый target, например langflow или agent-platform, а Garden выполняет его транзитивные зависимости в правильном порядке.

Garden не заменяет Docker, Helm или Kubernetes. Он объединяет их в один воспроизводимый процесс и хранит этот процесс в репозитории.

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

Операции согласования внешнего состояния не полагаются только на вычисленную версию. Они выполняются идемпотентно и должны исправлять обнаруженное расхождение.

Граф локального развёртывания

Упрощённый граф показывает, что Garden делает при локальном развёртывании: параллельно подготавливает зависимости, затем разворачивает выбранные продукты и, только по явному запросу, добавляет тестовые данные.

Пунктирная стрелка обозначает необязательный путь с тестовыми данными: он задействуется только при выборе соответствующего target. Точный граф для текущей рабочей копии можно получить командой:

garden get graph --env dev-local

Полная картина состава компонентов и их взаимных зависимостей для всех окружений приведена в Состав компонентов платформы.

Быстрый запуск

Сценарий предназначен для подготовленной рабочей станции. Docker, Kind, Garden, kubectl, Helm, Python 3 и uv уже установлены, кластер ap-dev-local создан, репозитории расположены рядом. Для новой машины — см. Первичная настройка.

Проверьте кластер:

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

Подключите рабочие каталоги и проверьте конфигурацию:

cd deploy
python3 scripts/link_local_actions.py
garden validate --env dev-local
garden get linked-repos --env dev-local

Разверните нужную часть среды:

# Target langflow: Low-code Конструктор
garden deploy langflow --env dev-local --yes

# Target agent-platform: остальные компоненты платформы
garden deploy agent-platform --env dev-local --yes

# Полная среда без тестовых данных
garden deploy all --env dev-local --yes

В отдельном терминале запустите доступ через локальный шлюз:

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

После запуска доступны:

• Low-code Конструктор — http://ide.localhost:18086;
• программные интерфейсы платформы — http://api-gw.localhost:18085;
• документация платформы — http://docs.localhost:18086.

Первое развёртывание может занимать продолжительное время: Docker скачивает базовые образы, а Garden собирает неизменяемые образы компонентов. Слово «быстрый» здесь означает короткий поддерживаемый путь, а не гарантированное время холодного запуска.

Пользовательские точки входа

Сценарий all намеренно не включает тестовые данные. Fixture actions активируются только при прямом выборе соответствующей точки входа или агрегате all-fixtures. Вызов без имени garden deploy не создаёт тестовые данные.

Первичная настройка dev-local

Эта инструкция подготавливает новую рабочую станцию для локальной разработки Платформы ИИ. Среда dev-local работает в отдельном Kind-кластере и не использует текущий Kubernetes context рабочей станции.

Требования к рабочей станции

Нужны:

• работающий Docker с доступными 4 процессорными ядрами, 12 ГиБ оперативной памяти и примерно 30 ГиБ свободного места;
• Kind версии 0.32.x;
• Garden версии 0.14.20;
• Helm версии 3.x или новее;
• kubectl, Python 3 и uv версии 0.11.x;
• curl и jq для проверок состояния.

Устанавливайте инструменты по официальным инструкциям:

• Docker;
• Kind 0.32.0;
• средство управления Kubernetes;
• Helm;
• uv;
• Garden.

Общая инструкция Garden может установить более новую версию. После установки переключитесь на версию, закреплённую для композиции:

garden self-update 0.14.20

Проверьте версии:

docker version
kind version
garden version
kubectl version --client
helm version
python3 --version
uv --version
curl --version
jq --version

Расположение репозиториев

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

aip/
├── deploy/
├── ai-platform/
└── langflow/

Репозитории ai-platform и langflow содержат разные части реализации Платформы ИИ. Репозиторий deploy описывает их совместную среду. Карта владения — в Репозитории и владение.

Создание Kind-кластера

Сначала убедитесь, что кластер с требуемым именем ещё не существует:

kind get clusters

Создайте каталог kubeconfig и кластер:

mkdir -p "$HOME/.kube"

kind create cluster \
  --name ap-dev-local \
  --kubeconfig "$HOME/.kube/ap-dev-local" \
  --wait 5m

Проверьте соединение:

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

Имя кластера, контекст и путь kubeconfig являются частью контракта среды:

Garden использует эти значения явно. Это защищает от случайного развёртывания в кластер, выбранный в обычном ~/.kube/config.

Подключение рабочих каталогов

В общей конфигурации исходные репозитории закреплены полными Git SHA. Для локальной разработки замените их локальными рабочими каталогами:

cd deploy
python3 scripts/link_local_actions.py --check
python3 scripts/link_local_actions.py
garden get linked-repos --env dev-local

Скрипт проверяет адрес удалённого репозитория Git, показывает ветку, SHA и наличие незакоммиченных изменений. Затем он записывает локальные соответствия действий Garden в игнорируемый файл .garden/local-config.json. Изменяемые действия приложений связываются с рабочими каталогами, но immutable carrier platform-lfx-wheel-image получает отдельный локальный detached worktree точно закреплённого коммита из Git-базы соседнего Langflow. Доступ к удалённому репозиторию для этого не нужен, а provenance остаётся согласованным с Runtime lock.

Если рабочая станция использует согласованный промежуточный удалённый репозиторий вместо прямого доступа к Sfera, укажите его явно:

python3 scripts/link_local_actions.py --bridge-remote mac

Этот режим не переносит изменения и не обновляет адрес удалённого репозитория Git. Он только разрешает использование выбранного рабочего каталога. Закреплённый commit LFX входит в историю Langflow develop. Если helper его не находит, обновите локальный develop до актуального composition baseline. Отдельный перенос Git-объектов не является частью рабочего цикла.

Проверка конфигурации

До первого развёртывания выполните статические проверки:

garden validate --env dev-local
garden get linked-repos --env dev-local

Первое развёртывание

Выберите минимальную требуемую точку входа:

# Target langflow: Low-code Конструктор и его зависимости
garden deploy langflow --env dev-local --yes

# Target agent-platform: остальные компоненты и их зависимости
garden deploy agent-platform --env dev-local --yes

# Оба набора компонентов, но без тестовых данных
garden deploy all --env dev-local --yes

Тестовые данные для первого запуска не обязательны. Если для проверки нужны готовые пользователи и агенты Платформы ИИ, выберите явный fixture target; базовый runtime поднимется как его зависимость:

garden deploy agent-platform-fixtures --env dev-local --yes

Холодный запуск может занять продолжительное время из-за загрузки образов и первой сборки.

Доступ с рабочей станции

После успешного развёртывания оставьте в отдельном терминале:

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

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

Проверьте адреса:

curl -fsS http://ide.localhost:18086/config.js >/dev/null
curl -fsS http://docs.localhost:18086/health/ready
curl -fsS http://api-gw.localhost:18085/agent-registry/health/ready | jq

Остановка терминала сочетанием Ctrl-C завершает только перенаправление портов. Рабочие нагрузки продолжают работать в Kind.

Возврат к закреплённым исходным версиям

Чтобы отключить все локальные соответствия и снова использовать Git SHA из общей конфигурации:

garden unlink action --all
garden get linked-repos --env dev-local

После отключения список локально связанных репозиториев должен быть пустым. Для следующей команды Garden потребуется доступ к закреплённым Git-версиям либо их локальный кеш.

Полный сброс среды

Удаление точного Kind-кластера удаляет все рабочие нагрузки, постоянные тома и локальные данные:

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

Не используйте эту команду как обычный способ восстановления. Сначала убедитесь, что выбран именно одноразовый кластер ap-dev-local и что его данные больше не нужны.

Как устроен процесс разработки

Разработка состоит из двух вложенных циклов:

изменение и целевые тесты в репозитории компонента
→ развёртывание изменённой части через Garden
→ проверка через канонический адрес шлюза
→ следующий шаг разработки

Нативные команды тестирования, проверки типов и форматирования остаются частью быстрого цикла. Они не создают вторую среду. Создание и изменение интегрированной среды выполняется только через Garden.

Текущая конфигурация ещё не синхронизирует изменённые файлы непосредственно в работающие контейнеры. После изменения кода нужно повторить развёртывание требуемой части графа. Настройка синхронизации кода для компонентов Agent Platform является следующим этапом перехода.

Garden описывает целевой быстрый цикл с синхронизацией файлов в работающие контейнеры в официальном материале «Локальная разработка с удалёнными кластерами». Материал показывает целевую возможность Garden, а не текущую инструкцию этого репозитория: наша среда использует локальный Kind, локальную сборку Docker и пока не включает синхронизацию кода.

Границы поддерживаемого пути

• Интегрированная среда создаётся из репозитория deploy.
• Код меняется в репозитории компонента, а не в каталоге deploy/.garden/build.
• Ручные helm upgrade, kubectl apply и изменение управляемых ресурсов не являются поддерживаемым способом разработки.
• Тестовые данные включаются только явными сценариями Garden.
• Локальные ссылки на рабочие каталоги допустимы только для разработки и не используются для общей среды (qa).
• Удаление Kind-кластера удаляет все локальные данные и выполняется только как осознанный полный сброс.

Почему не Docker Compose

Отдельный сценарий Docker Compose повторно описывает образы, переменные окружения, порты, тома, проверки состояния, сетевые зависимости и настройку идентификации. Значительная часть тех же сведений уже находится в Helm-чартах, действиях Garden и значениях окружений. Поддержка двух моделей приводит к расхождениям и требует синхронно изменять обе конфигурации.

Garden использует реальные Kubernetes-ресурсы и Helm-чарты платформы. Поэтому локальная проверка проходит через те же службы, HTTPRoute, OIDC-контракт и модель постоянного хранения, которые используются в общей среде.

Целевая модель не предусматривает два параллельных способа создания среды. Существующие сценарии Docker Compose считаются переходными. После реализации быстрого обновления кода через Garden платформенные сценарии Docker Compose должны быть удалены. Примеры исходного проекта Langflow могут сохраняться как неподдерживаемые примеры самостоятельного запуска, но не как среда Платформы ИИ.

Карта конфигурации Garden

Код компонентов, Dockerfile, Helm-чарты и принадлежащие приложению манифесты хранятся в репозитории владельца. Репозиторий композиции не должен содержать их копии.

Просмотр графа и плана

Посмотреть список действий и их зависимости:

garden get graph --env dev-local

Создать Mermaid-представление:

garden get graph --env dev-local --output json \
  | python3 scripts/garden_graph_to_mermaid.py --direction TB \
  > /tmp/ap-dev-local-garden.mmd

Посмотреть предполагаемые изменения без развёртывания:

garden deploy langflow --env dev-local --plan
garden deploy agent-platform --env dev-local --plan

План является вспомогательной проверкой. Он не заменяет развёртывание и проверку работающей среды.

Закреплённые версии и локальные ссылки

Общие среды используют полные Git SHA. Коммит deploy тем самым фиксирует совместимый состав исходных версий.

Локальная разработка использует соответствия действий рабочим каталогам:

python3 scripts/link_local_actions.py
garden get linked-repos --env dev-local

Garden читает текущие файлы рабочего каталога, включая незакоммиченные изменения. Исключение — immutable platform-lfx-wheel-image: он не линкуется на live checkout Langflow. Helper извлекает точно закреплённый коммит из локальной Git-базы в .garden/local-worktrees и линкует action на этот detached worktree. Скрипт не обновляет закреплённые SHA и не переносит Git-коммиты. Исходный Langflow commit в composition BOM всегда содержит закреплённый LFX commit в своей Git-истории, поэтому актуального develop достаточно для offline bootstrap.

Отключить локальные соответствия:

garden unlink action --all

Локальная ссылка не является синхронизацией кода с работающим контейнером. После изменения исходных файлов в текущей конфигурации нужно повторить развёртывание требуемой точки входа.

Правила изменения среды

• Выбирайте минимальную требуемую пользовательскую точку входа.
• Не используйте голый garden deploy, если достаточно одного target.
• Не изменяйте управляемые ресурсы через ручной Helm или kubectl.
• Не публикуйте разрешённую конфигурацию Garden, если она может содержать секретные значения.
• Не используйте локальные соответствия исходного кода для общей среды (qa).
• Повторный запуск после частичной ошибки является нормальным способом восстановления идемпотентного графа.

Локальный Registry артефактов

Run action dev-local-artifact-registry поддерживает один pinned OCI Distribution container в Docker network Kind и настраивает containerd каждой ноды. Publisher использует push endpoint http://ap-dev-local-registry:5000/agent-platform/low-code, а Kubernetes Image Volume — canonical digest-only reference с prefix localhost:5001/agent-platform/low-code. Оба адреса указывают на одни repository и blobs.

Garden application image Low-code Runtime сначала существует только в local Docker store. Поэтому перед Agent Platform deploy отдельный action dev-local-runtime-image публикует exact build в repository agent-platform/runtime/low-code, читает подтверждённый Registry digest и передаёт Control Plane только ссылку localhost:5001/...@sha256:.... Mutable Garden tag не сохраняется в publication contract и не попадает в Kubernetes workload.

После остановки и повторного запуска Kind выполните:

garden run dev-local-artifact-registry --env dev-local --yes
curl -fsS http://127.0.0.1:5001/v2/

Чтобы отдельно проверить сборку, публикацию и digest output Runtime:

garden run dev-local-runtime-image --env dev-local --yes

Container и named volume принадлежат композиции dev-local, а не Helm chart приложения. Volume намеренно переживает удаление Kind. Удалять его можно только при подтверждённом полном reset после проверки, что Control Plane не содержит live или retained AgentVersion references. Обычный cleanup Garden и digest GC не удаляют всё хранилище.

Окружения

Garden использует один граф компонентов, но подставляет в него параметры выбранного окружения. Это позволяет проверять одинаковые контракты приложения, не выдавая локальную инфраструктуру за точную копию общей среды.

Сравнение локальной и общей среды:

Схема пространств имён aip-<env> с суффиксами и роли общих провайдеров описаны в Развёртывание платформы.

dev-local

Локальная среда использует точный кластер ap-dev-local. Garden устанавливает закреплённые версии Gateway API и agentgateway, создаёт локальную шлюзовую топологию и разворачивает компоненты в пространстве имён разработчика.

Доступ с рабочей станции обеспечивает отдельное действие:

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

Публичные адреса локальной среды:

• API — http://api-gw.localhost:18085;
• Low-code Конструктор — http://ide.localhost:18086;
• документация — http://docs.localhost:18086.

Локальный HTTP допустим только для адресов .localhost. Он не является образцом внешнего или производственного доступа.

Target agent-platform транзитивно согласует локальный OCI Registry для data-only артефактов агентов. Он не заменяет механизм доставки application images. После повторного запуска остановленного Kind восстановите containerd mapping командой garden run dev-local-artifact-registry --env dev-local --yes. Данные Registry хранятся в отдельном Docker volume и переживают пересоздание кластера до подтверждённого полного reset.

Локальная среда одноразовая, но остановка перенаправления портов не удаляет рабочие нагрузки. Полный сброс выполняется удалением точного Kind-кластера и уничтожает все его постоянные данные.

qa

Общая среда qa использует кластер ai-dev и пространство имён aip-qa с суффиксами. Композиция создаёт только разрешённые ресурсы этого пространства имён, включая HTTPRoute приложений.

Gateway, ListenerSet, DNS, TLS-секреты и сертификаты принадлежат DevOps. Перед каждым развёртыванием оператор должен заново проверить существование внешних родителей маршрутов, разрешённые пространства имён, имена узлов и состояние шлюза.

Основные публичные адреса приведены в Развёртывание платформы.

Локальные соответствия действий исходным каталогам не являются способом поставки qa. Перед операторским развёртыванием проверьте:

garden get linked-repos --env qa

Список должен быть пустым, а общая конфигурация — содержать проверенные полные Git SHA.

Что должно совпадать

Между dev-local и qa проверяются одни и те же классы контрактов:

• образы и Helm-шаблоны компонентов;
• публичные пути API;
• издатель OIDC, аудитория и адрес возврата;
• HTTPRoute и выбранный Kubernetes Service;
• готовность компонентов;
• постоянное хранение там, где оно требуется;
• явное отделение обычной среды от тестовых данных.

Имена узлов, протокол доступа, класс хранилища и владелец шлюза намеренно различаются и задаются окружением.

Границы доступа

• Разработчик изменяет только собственное пространство имён в разрешённой среде.
• Наличие административного kubeconfig не разрешает менять общие операторы, Gateway или чужие пространства имён.
• Создание и ротация секретов требуют отдельного разрешения.
• Ручное удаление пространства имён, постоянных томов или данных qa запрещено.
• Успешная локальная проверка не заменяет проверку внешнего маршрута и OIDC в qa.

Полная операторская последовательность qa находится в руководстве по развёртыванию. Разработчику не следует повторять команды общей среды как часть обычного локального цикла.

Репозитории и владение

Платформа ИИ состоит из нескольких компонентов и технических репозиториев. Место хранения файла определяет владельца желаемого состояния, но не превращает репозиторий в отдельный пользовательский продукт.

Карта репозиториев

В пользовательской документации все эти части называются Платформа ИИ. Имена репозиториев и технических точек входа используются только в командах и инструкциях для разработчиков.

Где выполнять изменение

У каждого Helm-релиза и Kubernetes-ресурса должен быть один владелец. Не создавайте вторую копию ресурса в репозитории композиции.

Подготовка межрепозиторного изменения

Безопасная последовательность:

1. Определите владельца каждого изменяемого артефакта.
2. Измените продуктовый артефакт во владеющем репозитории.
3. Проверьте его через локальную связь Garden.
4. Создайте проверенный Git-коммит продуктового репозитория.
5. Обновите закреплённый SHA в deploy.
6. Убедитесь, что предыдущая и новая композиция имеют рабочий путь обновления.
7. Выполните проверки графа и развёртывание по новому составу.

Не создавайте неатомарное несовместимое изменение, при котором ни предыдущая, ни новая версия композиции не способны развернуть работающую систему.

Дублирующие способы запуска

Платформенные файлы Docker Compose, отдельные скрипты ручного развёртывания и любой новый Garden Project в продуктовом репозитории создают вторую модель интегрированной среды. Они могут расходиться по следующим параметрам:

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

Единственный источник истины интегрированной среды — deploy. Standalone Garden Projects из ai-platform и langflow удалены после переноса их поддерживаемых сценариев. Не возвращайте их как локальное исключение: недостающий сценарий добавляется в общий граф либо оформляется отдельным изолированным verification capsule.

Изолированные проекты в каталогах verification выполняют узкие проверки и не считаются второй интегрированной средой, пока не берут во владение общие ресурсы платформы.

Проверка границы владения

Перед слиянием задайте четыре вопроса:

1. Может ли приложение развернуться без несвязанного рабочего каталога?
2. Не появился ли второй владелец существующего Kubernetes-ресурса?
3. Осталась ли конфигурация окружения в deploy?
4. Зафиксированы ли совместимые Git SHA для общей среды?

Если ответ на любой вопрос отрицательный, изменение требует исправления графа или отдельного архитектурного решения.

Ежедневный цикл разработки

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

Перед началом работы

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

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

cd deploy
garden get linked-repos --env dev-local
garden validate --env dev-local

Если нужного соответствия нет, повторите:

python3 scripts/link_local_actions.py

Цикл изменения

Рабочая последовательность:

1. Измените код в репозитории владельца компонента.
2. Выполните целевые тесты, проверку типов и форматирование этого репозитория.
3. Перейдите в deploy.
4. При необходимости посмотрите план выбранного развёртывания.
5. Разверните минимальную требуемую точку входа.
6. Проверьте логи и состояние ресурсов.
7. Выполните пользовательскую проверку через канонический адрес шлюза.

Пример команд:

cd deploy

garden deploy langflow --env dev-local --plan
garden deploy langflow --env dev-local --yes
garden logs langflow --env dev-local --tail 100

Чтобы развернуть компоненты Платформы ИИ, используйте target agent-platform:

garden deploy agent-platform --env dev-local --plan
garden deploy agent-platform --env dev-local --yes
garden logs agent-platform --env dev-local --tail 100

Garden пересчитывает версии действий по включённым исходным файлам. Изменение интерфейса не должно пересобирать несвязанный образ серверной части, а изменение одного продукта не должно развёртывать независимый target другого технического репозитория.

Доступ и проверка результата

В отдельном терминале должен работать локальный шлюз:

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

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

• Low-code Конструктор — http://ide.localhost:18086;
• API платформы — http://api-gw.localhost:18085;
• документация — http://docs.localhost:18086.

В зависимости от изменения проверьте:

• готовность компонента;
• вход через Keycloak и возврат на точный адрес приложения;
• изменённый пользовательский сценарий;
• отсутствие ошибок в логах;
• корректность HTTPRoute и публичного пути;
• сохранение данных после замены Pod, если изменение затрагивает хранение.

Успешный ответ прямого Service не заменяет проверку через шлюз: он обходит маршрутизацию, публичный адрес и часть OIDC-контракта.

Работа с тестовыми данными

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

garden run identity-fixtures --env dev-local --yes
garden deploy agent-platform-fixtures --env dev-local --yes
garden run langflow-fixtures --env dev-local --yes
garden deploy all-fixtures --env dev-local --yes

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

Изменение конфигурации Garden или Helm

Изменение графа, окружения или Helm-чарта требует дополнительных проверок:

cd deploy
python3 scripts/check_source_pins.py
python3 scripts/check_identity_contract.py
python3 scripts/check_fixture_route.py
garden validate --env dev-local
garden get graph --env dev-local --output json \
  | python3 scripts/check_graph.py

Также выполните проверки Helm-чарта во владеющем репозитории. Не копируйте манифест приложения в deploy ради удобства связывания.

Изменение нескольких репозиториев

Если одно изменение затрагивает реализацию компонента и композицию:

1. Подготовьте обратно совместимое изменение во владеющем репозитории.
2. Проверьте его локально через соответствия действий Garden.
3. Зафиксируйте изменение отдельным Git-коммитом.
4. Обновите полный SHA источника в deploy.
5. Отключите локальные соответствия либо выполните проверку в чистом операторском каталоге.
6. Повторите статические проверки и развёртывание по закреплённому SHA.

Плавающая ветка не является составом поставки общей среды.

Критерии готовности изменения

Перед передачей результата убедитесь, что:

• проверки владеющего репозитория прошли;
• конфигурация Garden разрешается без ошибок;
• изменённая точка входа развёрнута в dev-local;
• проверка выполнена через канонический адрес шлюза;
• ручные изменения управляемых Kubernetes-ресурсов не использовались;
• для изменения нескольких репозиториев обновлён закреплённый SHA;
• секреты, токены и содержимое kubeconfig не попали в логи или материалы проверки;
• явно перечислено, что не проверялось.

Диагностика

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

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

cd 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 Конструктора замените имя технической точки входа на langflow.

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

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

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

DEV_NAMESPACE="aip-dev-local"

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/aip-dev-local/.well-known/openid-configuration \
  | jq '.issuer'

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

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

Не исправляйте ошибку добавлением произвольного 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"

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