Руководство разработчика

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

Что такое Garden

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

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

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

Пунктирная стрелка обозначает необязательный путь с тестовыми данными: он задействуется только при выборе соответствующего target. Точный граф для текущей рабочей копии можно получить командой из раздела «Garden: граф и targets». Отдельно запускаемый dev-local-edge-forward, отключённые действия других окружений и внутренние рёбра групп на схеме намеренно не показаны.

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

Этот сценарий предназначен для подготовленной рабочей станции. 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 ap-deploy
python3 scripts/link_local_actions.py
garden validate --env dev-local
garden get linked-repos --env dev-local

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

# Target langflow: Low-code IDE
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 ap-deploy
garden run dev-local-edge-forward --env dev-local

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

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

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

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

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

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

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

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

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

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

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

Почему не Docker Compose

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

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

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

Дальнейшее чтение

• Первичная настройка — инструменты, Kind, kubeconfig и первый запуск.
• Garden: граф и targets — зависимости, команды и карта конфигурации.
• Ежедневный цикл разработки — изменение, тестирование, развёртывание и критерии готовности.
• Репозитории и владение — выбор места изменения и согласование нескольких репозиториев.
• Окружения — различия dev-local и ST.
• Диагностика — типовые ошибки и безопасные проверки.