Автоматическая оценка кода с использованием агентской песочницы в GKE

1. Введение

В этом практическом задании вы развернете приложение Hackathon Judge на Google Kubernetes Engine (GKE) и используете песочницу Kubernetes-sigs Agent Sandbox для безопасного и надежного запуска агентских рабочих нагрузок.

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

Что вы будете делать

  • Разверните целевые сервисы Google Cloud и настройте целевые API.
  • Инициализируйте GKE Autopilot и установите CRD-файлы песочницы агента, конфигурации кластера и маршрутизатор песочницы.
  • Разверните шлюз песочницы, шаблон запроса на развертывание в песочнице и пул тепловых ресурсов для песочницы.
  • Разверните REST-бэкэнд API, агент ADK Judging worker Agent и фронтенд-интерфейс React.
  • Подключите внешнюю маршрутизацию с балансировкой нагрузки и получите доступ к платформе для запуска безопасных, изолированных рабочих процессов оценки.

Что вам понадобится

  • Веб-браузер, например Chrome .
  • Проект Google Cloud с включенной функцией выставления счетов.

Затраты на выполнение заданий, созданных в рамках этого практического занятия, должны составить менее 5 долларов.

2. Проблема: Безопасная оценка ненадежного кода

Хакатоны — это динамичные инновационные мероприятия, где участники создают и представляют проекты — часто с исходным кодом — для оценки. Ручная оценка этих работ отнимает много времени и ресурсов. Использование агентов искусственного интеллекта для автоматизации оценки — многообещающее решение, но оно создает серьезную проблему безопасности: как безопасно запускать предоставленный участниками код, который может содержать ошибки, быть вредоносным или ресурсоемким?

Запуск ненадежного кода непосредственно в вашей инфраструктуре подвергает вас таким рискам, как:

  • Внедрение кода : вредоносные скрипты могут попытаться получить доступ к конфиденциальным данным или изменить их.
  • Повышение привилегий : Код может попытаться получить несанкционированный доступ к другим системам или сетевым ресурсам.
  • Злоупотребление ресурсами : Некачественно написанный код или атаки типа «отказ в обслуживании» могут потреблять чрезмерное количество ресурсов ЦП, памяти или сетевой пропускной способности, влияя на другие операции.

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

3. Решение: Песочница агента GKE

Функция GKE Agent Sandbox разработана именно для решения этой задачи. Она помогает управлять изолированными, сохраняющими состояние и однорепликационными рабочими нагрузками в GKE и оптимизирована для таких сценариев использования, как среды выполнения агентов ИИ, где ненадежный код должен выполняться безопасно и эффективно.

Основные преимущества Agent Sandbox включают:

  • Изоляция на уровне ядра : Обеспечивает надежную изоляцию на уровне ядра для ненадежного кода с использованием таких технологий, как gVisor , предотвращая доступ кода к хост-системе или другим контейнерам.
  • Выделение ресурсов менее чем за секунду : Обеспечивает быстрое выделение тестовых сред (обычно менее чем за 1 секунду), что критически важно для оценки кода по запросу.
  • Расширяемость, присущая облачным технологиям : использует возможности Kubernetes и управляемую инфраструктуру GKE.

Используя Agent Sandbox, мы можем создавать изолированные среды по запросу для каждой работы, представленной на хакатоне. Затем ИИ-агент, осуществляющий оценку, может давать Agent Sandbox указания запускать тесты, компилировать код или выполнять другие этапы оценки в этой защищенной песочнице, не рискуя целостностью всей платформы. Это обеспечивает масштабируемый, безопасный и эффективный способ автоматизации оценки работ на хакатонах.

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

Запустить Cloud Shell

Нажмите кнопку ниже, чтобы запустить Google Cloud Shell, который поставляется с предварительно настроенными необходимыми утилитами для разработчиков и командной строки облачных сервисов.

Включить API

Выполните следующую команду в Cloud Shell, чтобы включить все необходимые для работы платформы API Google Cloud:

gcloud services enable \
  container.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  pubsub.googleapis.com \
  aiplatform.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  bigquery.googleapis.com \
  bigqueryconnection.googleapis.com

Почему мы включаем эти API: Сервисы Google Cloud по умолчанию отключены для предотвращения несанкционированного доступа и списания средств. Мы включаем эти конкретные API для активации оркестрации контейнеров (GKE), безопасного хранения контейнеров (Artifact Registry), бессерверной сборки (Cloud Build), надежных очередей сообщений (Pub/Sub), сервисов моделей ИИ (Vertex AI), конфигурации проекта (Cloud Resource Manager и IAM), бессерверной аналитики данных (BigQuery) и привязок ИИ на уровне базы данных (BigQuery Connection).

5. Создание инфраструктуры

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

Клонируйте репозиторий

Клонируйте репозиторий, содержащий все службы приложений, скрипты настройки и объявления манифеста Kubernetes:

git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
git sparse-checkout set codelabs/ai-toolkit-lab-2/hackathon-judge
cd codelabs/ai-toolkit-lab-2/hackathon-judge

Запуск скрипта развертывания

Базовая настройка облачных ресурсов, моделей баз данных и основных политик кластера Kubernetes автоматизирована с помощью скрипта deploy.sh .

Запустите скрипт:

./deploy.sh

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

Вот целевые операции, выполняемые скриптом:

1. Настройка конфигурации среды

Скрипт создает конфигурационный файл .env для хранения параметров GKE, Pub/Sub, BigQuery и переменных проекта. Динамическое заполнение этого файла автоматически определяет все последующие значения манифеста Kubernetes.

Зачем мы настраиваем этот файл среды: файл .env централизует параметры конфигурации, гарантируя, что манифесты GKE, которые мы применяем вручную на последующих этапах, используют идентичные региональные настройки, имена проектов и ресурсы, что строго отделяет конфигурацию среды от исходного кода.

2. Настройка Google Cloud CLI и целевого проекта.

Этот скрипт проверяет наличие установленных утилит gcloud , bq , kubectl и envsubst , проверяет состояние аутентификации и привязывает активные целевые объекты конфигурации к вашему активному проекту Google Cloud.

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

3. Включение целевых API Google Cloud

Скрипт выполняет идемпотентную проверку для подтверждения и включения целевых API-интерфейсов сервисов Google Cloud (GKE, Artifact Registry, Cloud Build, Pub/Sub, Vertex AI, BigQuery и IAM).

Почему мы включаем API Google Cloud: управляемые облачные сервисы необходимо активировать до того, как станут доступны их конечные точки или можно будет создавать ресурсы. Включение их на начальном этапе подготавливает региональный шлюз API GCP к обработке последующих команд по предоставлению ресурсов.

4. Подготовка репозитория Docker для реестра артефактов

Скрипт создает репозиторий контейнеров Docker с именем hackathon-judge-repo в выбранном целевом местоположении.

Зачем мы создаём репозиторий Artifact Registry: кластерам GKE требуется безопасный доступ к частным реестрам контейнеров в той же региональной сети для быстрой загрузки образов приложений. Artifact Registry предоставляет безопасный частный хост для каталогизации, сканирования и хранения образов контейнеров Docker.

5. Настройка кластера автопилота GKE

Этот скрипт создает кластер Google Kubernetes Engine (GKE) Autopilot под названием hackathon-judge-cluster .

Почему мы развертываем кластер GKE Autopilot: GKE Autopilot автоматически управляет выделением узлов, масштабированием, мониторингом состояния и обновлениями безопасности хост-системы. Он предоставляет платформу контейнеров производственного уровня для оркестрации наших постоянных сервисов и динамически планирует создание защищенных рабочих песочниц по запросу.

6. Настройка тем и подписок Pub/Sub

Скрипт создает темы сообщений ( judging-tasks и judging-results ) вместе с соответствующими подписками на обработчики и API.

Почему мы используем темы и подписки Pub/Sub: Оценка отправленного кода — медленный и ресурсоемкий процесс. Использование архитектуры очередей сообщений позволяет отделить синхронный API, ориентированный на пользователя, от рабочих узлов. API-бэкенд отправляет задания в тему judging-tasks , а рабочие агенты извлекают задания по мере их доступности, предотвращая блокировку API и обеспечивая возможность автоматического повтора попыток.

7. Настройка наборов данных, таблиц и подключений к ИИ в BigQuery

Скрипт создает набор данных hackathon_judge , применяет структурированные схемы базы данных SQL, загружает исходные записи и предоставляет необходимые роли для работы с ИИ и хранилищем учетной записи службы подключения BigQuery ML.

8. Запуск сборки контейнеров с помощью Cloud Build

Скрипт запускает выполнение определения cloudbuild.yaml для компиляции нашего React UI, Go REST-сервера, Python ADK worker и FastAPI sandbox, упаковывая их в изолированные образы контейнеров, помеченные SHA-хешем активного репозитория Git-коммита, и сохраняя их в Artifact Registry.

9. Определение пользовательских ресурсов (CRD) в тестовой среде агента регистрации

Скрипт загружает и регистрирует последние определения пользовательских ресурсов песочницы агента Kubernetes-sigs ( manifest.yaml и extensions.yaml ) для расширения основных возможностей GKE.

Почему мы устанавливаем инфраструктуру Agent Sandbox: Стандартные кластеры Kubernetes не поддерживают выделение защищенных песочниц по запросу. Регистрация CRD Agent Sandbox расширяет плоскость управления GKE, позволяя Kubernetes нативно управлять безопасными микроконтейнерами в песочнице с помощью пользовательских ресурсов (таких как SandboxTemplates и SandboxClaims).

10. Настройка пространств имен, учетных записей служб и идентификации рабочих нагрузок

Скрипт создает пространство имен hackathon-judge , регистрирует учетные записи служб Kubernetes (KSA) и устанавливает сопоставления идентификаторов рабочих нагрузок для предоставления подам GKE целевых разрешений Google Cloud.

11. Развертывание маршрутизатора в песочнице

Скрипт применяет манифест k8s/sandbox_router.yaml , инициирует развертывание и работу сервиса Sandbox Router и ожидает, пока они не достигнут работоспособного состояния.

Почему мы используем Sandbox Router: Sandbox Router — это центральный внутренний шлюз плоскости управления. Он предоставляет простой API, который агент ADK, выполняющий проверку, вызывает для получения доступа к защищенным песочницам, управления маршрутизацией и абстрагирования распределения подов на уровне кластера от логики приложения.

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

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

Исходные переменные среды

Перед применением шаблонов, требующих переменных окружения, выполните скрипт setup-env.sh , чтобы проанализировать и экспортировать все необходимые переменные в вашу оболочку:

source ./setup-env.sh

Применить шлюз песочницы

Разверните шлюз, специально настроенный для маршрутизации трафика в тестовой среде:

kubectl apply -f k8s/sandbox-gateway.yaml

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

Применить шаблон заявки для песочницы

Используйте envsubst для заполнения определения шаблона песочницы активными переменными среды и примените его:

source ./setup-env.sh
envsubst < k8s/sandbox-claim-template.yaml | kubectl apply -f -

Зачем мы используем шаблон запроса на использование песочницы: Шаблон запроса на использование песочницы служит в качестве схемы конфигурации, определяющей среду. Он указывает образ контейнера для запуска (предварительно упакованный с инструментами разработчика), параметры среды (идентификатор проекта GCP), порты и ограничения ресурсов (целевые значения ЦП/памяти). Он настраивает GKE для запуска этих экземпляров контейнеров с использованием gVisor (среда выполнения gvisor) , гарантируя, что ненадежный код участников будет выполняться под дополнительным уровнем изоляции виртуализации ядра.

Применить Sandbox WarmPool

Используйте Sandbox WarmPool для предварительной инициализации работающих песочниц:

kubectl apply -f k8s/sandbox-warmpool.yaml

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

kubectl get pods -n hackathon-judge -l app=sandbox

Почему мы используем Sandbox WarmPool: Подготовка, планирование, загрузка образов и запуск новых контейнерных подов по запросу приводят к существенным накладным расходам при запуске (время холодного запуска составляет более 30 секунд). Sandbox WarmPool поддерживает резервный пул активных, предварительно подготовленных подов песочницы (по умолчанию 5 реплик). Когда рабочий агент запрашивает среду для оценки, Sandbox Router немедленно выделяет работающий предварительно подготовленный под, сокращая задержки запуска до менее чем секунды.

7. Развертывание компонентов приложения

После полной активации защищенной инфраструктуры песочницы вы сможете развернуть центральный бэкэнд API, агент рабочих процессов, веб-интерфейс React и сопоставление шлюза входящих запросов.

Развертывание бэкэнда

Разверните бэкэнд REST API оркестратора:

source ./setup-env.sh
envsubst < k8s/backend.yaml | kubectl apply -f -

Развернуть агент

Разверните агента-судью ADK: 

source ./setup-env.sh
envsubst < k8s/agent.yaml | kubectl apply -f -

Развернуть интерфейс

Разверните интерактивный веб-интерфейс пользователя: 

source ./setup-env.sh
envsubst < k8s/frontend.yaml | kubectl apply -f -

Настройка внешнего шлюза и маршрутизации.

Разверните основной шлюз и входящие HTTP-маршруты, сопоставляющие внешний клиентский трафик: 

kubectl apply -f k8s/gateway.yaml

Почему мы используем внешний шлюз входящего трафика: внешний шлюз предоставляет доступ к нашим сервисам через API шлюза Kubernetes. Он выделяет балансируемый публичный IP-адрес и сопоставляет маршруты на основе правил пути — направляя запросы API из каталога /api/* к бэкенду Go и сопоставляя весь остальной веб-трафик клиентов ( / ) с фронтендом React, обеспечивая безопасный доступ к публичному кластеру.

Проверка развертывания

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

kubectl rollout status deployment/backend -n hackathon-judge --timeout=300s
kubectl rollout status deployment/agent -n hackathon-judge --timeout=300s
kubectl rollout status deployment/frontend -n hackathon-judge --timeout=300s

8. Проверьте и используйте приложение.

Получите доступ к пользовательскому интерфейсу.

Получите внешний публичный IP-адрес недавно настроенного главного шлюза балансировки нагрузки:

Чтобы отслеживать статус инициализации в режиме реального времени, выполните команду с флагом наблюдения ( -w ) и дождитесь, пока в поле ADDRESS не появится публичный IP-адрес: 

kubectl get gateway -n hackathon-judge hackathon-judge-gateway -w

После успешного выполнения инициализации вы должны увидеть вывод, аналогичный следующему: 

NAME                      CLASS    ADDRESS          PROGRAMMED   AGE
hackathon-judge-gateway   gke-l7   34.120.120.120   True         3m

Как только в столбце ADDRESS отобразится действительный публичный IP-адрес, а статус PROGRAMMED будет True , нажмите Ctrl+C чтобы остановить наблюдение.

Почему мы получаем статус «Шлюз»: API шлюза обрабатывает публичный входящий трафик. Проверка статуса шлюза возвращает публичный, балансируемый внешний IP-адрес, выделенный глобальным внешним балансировщиком нагрузки Google Cloud для нашего кластера, который представляет собой публичный адрес нашей платформы.

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

Отправить задания

  • Используйте пользовательский интерфейс фронтенда, чтобы перейти к панели управления и выбрать хакатон.

Панель управления

  • В любом из проектов вы можете нажать кнопку Run Agent , чтобы запустить оценку проекта агентом в соответствии с критериями.

Проекты

Смотрите старт сезона Sandbox

Отслеживайте активные поды в пространстве имен hackathon-judge , чтобы увидеть, как динамически запрашивается и выделяется под в песочнице для выполнения проверки: 

kubectl get pods -n hackathon-judge -w

Просмотрите логи пода рабочего агента, чтобы увидеть пошаговую логику оценки соответствия требованиям ADK: 

kubectl logs -l app=agent -n hackathon-judge

Зачем мы изучаем журналы агентов: Изучение журналов рабочих агентов отображает подробные внутренние этапы конвейера оценки в режиме реального времени. Вы можете отслеживать, как агент ADK получает задачу, запрашивает контейнер песочницы, выполняет цели компиляции, анализирует отчеты с помощью Gemini и публикует оценочные таблицы.

9. (Необязательно) Как это работает

Архитектура агентской песочницы

Хотя функции искусственного интеллекта BigQuery невероятно полезны для оценки текстовых заявок и утверждений в файлах README, для оценки инженерного проекта требуется компиляция кода, установка сторонних библиотек и запуск реальных наборов тестов.

Выполнение пользовательского кода в необработанном виде сопряжено с огромными рисками для безопасности, включая компрометацию хоста, выход за пределы контейнеров и несанкционированный доступ к ресурсам. Платформа GKE Agent Sandbox снижает эти риски, организуя изолированные рабочие нагрузки в песочнице с использованием виртуализации gVisor (runsc) .

Схема взаимодействия системы

Приведенная ниже диаграмма показывает, как различные элементы нашей системы, управляемой событиями, взаимодействуют во время безопасного выполнения оценки в изолированной среде:

Как взаимодействуют инструменты и компоненты.

  • React Frontend UI : Предоставляет интерактивный интерфейс, где пользователи настраивают модели критериев, регистрируют команды, отправляют URL-адреса проектов и просматривают окончательные оценочные листы, включая полные расхождения в файлах и комментарии разработчиков.
  • Go REST Backend API : управляет глобальными конечными точками API. Он хранит конфигурации проектов в BigQuery и отправляет задачи оценки в Pub/Sub для развязки ресурсоемких вычислительных конвейеров.
  • Google Pub/Sub : ориентированный на сообщения брокер, который безопасно хранит сообщения задач в очереди, организуя асинхронную связь между API и активными экземплярами рабочих процессов.
  • Python ADK Worker (Supervisor Agent) : фоновый процесс, который получает задачи из Pub/Sub. Он использует Google Agent Development Kit (ADK) для запуска высокоуровневого агента-супервайзера, которому поручено координировать оценку. Супервайзер вызывает свой основной инструмент, evaluate_repository , для делегирования глубокого тестирования исходных команд.
  • Sandbox Router & Gateway (GKE Control Plane) : Внутренний управляющий шлюз, который регистрирует стандартные определения пользовательских ресурсов песочницы ( SandboxClaims , SandboxTemplates ). Он координирует сети GKE для выделения и защиты подов, возвращая потоки соединений обратно клиентским рабочим процессам.
  • Sandbox WarmPool : Чтобы избежать длительного времени запуска контейнеров GKE («холодных запусков» продолжительностью более 30 секунд), WarmPool поддерживает активные резервные поды. Когда песочница занята, маршрутизатор немедленно, менее чем за секунду, подключает её к сети, а затем планирует перезапуск при освобождении.
  • Изоляция gVisor (runsc) : Виртуальное ядро ​​пользовательского пространства, действующее как безопасная граница песочницы. Оно перехватывает системные вызовы из пространства контейнера к ядрам узлов GKE, гарантируя, что опасные необработанные команды (например, системные скрипты или настройка пакетов) выполняются в условиях абсолютной виртуализации.
  • FastAPI Sandbox Runtime : Легковесный сервер API на Python, работающий внутри контейнера песочницы. Он предоставляет защищенные конечные точки ( /execute , /upload , /download ), которые позволяют внешним рабочим инструментам манипулировать файлами и запускать задачи оболочки.
  • Gemini CLI ( @google/gemini-cli ) : скрипт автономного агента, устанавливаемый внутри песочницы. При запуске с флагом среды выполнения разработчика ( --yolo ) он использует строгий лист инструкций по оценке ( prompt.md ) и определение критериев ( criteria.md ) для:
    • Динамический анализ иерархии кодовой базы (с использованием таких инструментов, как tree или ripgrep ).
    • Автоматическая установка необходимых зависимостей (с помощью команд типа npm install , pip install , go build ).
    • Для проверки функциональности запустите реальные тесты разработки (например, npm test или pytest ).
    • Вызовите модели Vertex AI (используя учетные данные привязки Workload Identity контейнера) для оценки логики файлов, сверки утверждений с файлом README, обнаружения «фантомных» функций, регистрации проблем с качеством и записи структурированного отчета в файл evaluation.json .
  • Стандартные среды разработки : включают в себя node, npm, yarn, pnpm, python, pip, uv, go, gh, git, tree, ripgrep и playwright в образ контейнера песочницы, предоставляя автономному суб-агенту полноценное рабочее пространство для тестирования.

10. Уборка

Чтобы избежать дальнейших списаний средств с вашего аккаунта Google Cloud, удалите ресурсы, созданные в ходе этого практического занятия. 

./destroy.sh

Почему мы очищаем ресурсы: Google Cloud выставляет счета по модели использования ресурсов. Активные ресурсы, такие как кластеры GKE Autopilot, сетевые балансировщики нагрузки и постоянные диски, влекут за собой постоянные расходы, даже когда они простаивают. Выполнение этого шага удаляет пространство имен кластера для очистки объектов Kubernetes и удаляет сам хост кластера GKE Autopilot, чтобы немедленно прекратить все связанные с ним платежи.

11. Поздравляем!

Поздравляем! Вы успешно развернули приложение Hackathon Judge с помощью Agent Sandbox в GKE!

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

Что вы узнали

  • Инфраструктура GKE : Как настроить GKE Autopilot и вспомогательные сервисы Google Cloud, такие как Pub/Sub и BigQuery.
  • Настройка песочницы агента : как настроить определения пользовательских ресурсов, шаблоны песочницы, утверждения песочницы и высокопроизводительные пулы теплых песочниц.
  • Развертывание микросервисов : как настроить привязки Workload Identity и развернуть многокомпонентную микросервисную архитектуру (Frontend React, REST Go, Worker ADK Agent и изолированная песочница).
  • Безопасная песочница : как использовать виртуализированные контейнеры gVisor для безопасного выполнения ненадежных команд сторонних разработчиков на узлах GKE.

Следующие шаги

Справочная документация