Жизненный цикл песочницы
Песочница — это постоянный ресурс со средой выполнения, который может работать или находиться на паузе. Остановка, гибернация и удаление по-разному влияют на данные и возможность восстановления.
Модель состояний
Поле status в ответе GET /v1/sandboxes/{id} принимает следующие значения:
| Состояние | Значение | Что делать |
|---|---|---|
starting | Среда выполнения загружается | Опросить ресурс до running или failed |
running | Среда выполнения доступна для команд, файлов, терминалов и открытых сервисов | Выполнить работу, остановить, гибернировать или удалить |
stopping | VM остановлена, постоянное состояние диска финализируется | Дождаться stopped перед зависимой работой |
stopped | Файловая система сохранена, но процессы и память — нет | Выполнить холодный запуск через resume |
resuming | Сохраненная файловая система восстанавливается и загружается | Опросить ресурс до running или failed |
hibernating | Создается полный снимок VM | Дождаться hibernated |
hibernated | Сохранены диск, память, CPU и состояние процессов | Восстановить состояние VM через wake |
failed | Среда выполнения не смогла перейти или остаться в рабочем состоянии | Проверить error_reason и вкладку События, затем перезапустить или пересоздать |
Готовность подготовки не совпадает с состоянием среды выполнения. Песочница
может уже быть running, пока provisioning.status остается in_progress.
Перед использованием клонированного репозитория или другого подготовленного
артефакта дождитесь provisioning.status: "ready".
Обычные переходы:
create → starting → running
running → stopping → stopped → resuming → running
running → hibernating → hibernated → running
starting/running/transition → failed → running
любое существующее состояние → delete → ресурс больше не существует
Последний переход failed → running — восстановительный перезапуск, а не обычная
перезагрузка исправной песочницы.
Остановка, гибернация или удаление
| Действие | Что сохраняется | Что теряется | Возврат |
|---|---|---|---|
| Остановка | Ресурс песочницы и состояние файловой системы | Работающие процессы и состояние в памяти | Возобновление |
| Гибернация | Файловая система, память VM, CPU и процессы | Активным сетевым соединениям все равно может потребоваться восстановление на уровне приложения | Пробуждение |
| Удаление | Ничего из данных, принадлежащих только этой песочнице | Ресурс песочницы и его данные | Создать новую песочницу |
Используйте Остановить в меню действий песочницы, если в дальнейшем допустима холодная загрузка. Возобновленная песочница может быть размещена на подходящем узле и принимать необязательные новые значения vCPU или RAM.
Используйте В гибернацию, когда важно продолжить работу из состояния в памяти. Снимок памяти принадлежит записанному узлу, поэтому пробуждение также зависит от его доступности.
Используйте Удалить, только когда песочница и ее данные больше не нужны. Публичный API не восстанавливает удаленную песочницу. Если состояние может пригодиться повторно, сначала сохраните его как шаблон.
Личную песочницу можно сохранить как шаблон. Видимость private созданного
шаблона действует на весь аккаунт: другие участники организации смогут
создать песочницу из снимка корневой файловой системы. В снимке могут остаться файлы, настройки
и секреты, записанные на диск исходной песочницы. Перед сохранением проверьте
содержимое файловой системы.
Изменение состояния в веб-интерфейсе
Откройте меню действий песочницы:
- для активной песочницы доступны Остановить и В гибернацию;
- для остановленной — Запустить;
- для песочницы в гибернации — Разбудить;
- для песочницы со сбоем — Перезапустить;
- после подтверждения ресурс можно Удалить.
Страница песочницы опрашивает переходные состояния и открывает вкладки среды выполнения
после перехода в running. Вкладки Настройки и События остаются
доступны для стабильных состояний stopped, hibernated и failed.
Изменение состояния через API
Для каждого действия жизненного цикла предназначен отдельный эндпоинт:
# Running → Stopped
curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/stop" \
--header "Authorization: Bearer $JUSTRUN_PAT" |
jq
# Stopped → Running
curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/resume" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data '{}' |
jq
# Running → Hibernated
curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/hibernate" \
--header "Authorization: Bearer $JUSTRUN_PAT" |
jq
# Hibernated → Running
curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/wake" \
--header "Authorization: Bearer $JUSTRUN_PAT" |
jq
После действия опрашивайте сам ресурс, а не считайте любой переход завершенным при получении ответа:
curl --fail-with-body --silent --show-error \
"$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
--header "Authorization: Bearer $JUSTRUN_PAT" |
jq '{id, status, error_reason, started_at, stopped_at}'
После остановки ресурс может ненадолго показывать stopping, пока
финализируется постоянное состояние. Во время возобновления или пробуждения он может
находиться в переходном состоянии, пока среда выполнения загружается.
Автоматическая пауза и пробуждение
Поведение жизненного цикла настраивается для каждой песочницы:
idle_pause_msставит работающую песочницу на паузу после окна простоя;idle_pause_actionвыбираетstopилиhibernate;wake_on_requestпозволяет подходящему входящему запросу вернуть песочницу в состояниеrunning;timeout_msзадает окно истечения, которое запускается заново при возобновлении или пробуждении.
Пробуждение по запросу штатно пробуждает песочницу в гибернации. Остановленную
песочницу можно возобновить внутри запроса только тогда, когда это разрешено в
инсталляции и существует актуальная теплая локальная копия. В противном случае
запрос получает повторяемую ошибку недоступности, а клиент должен явно вызвать
resume.
Значения по умолчанию и семантика PATCH описаны в разделе Настройка песочницы.
Границы и ошибки
- Действие из неверного состояния возвращает HTTP
409. Дляstoppedиспользуйтеresume, а дляhibernated—wake. - Возобновление может вернуть HTTP
503, если нет здорового узла с достаточными ресурсами. Повторите то же возобновление; не создавайте замену, если это не является желаемым результатом. restartпринимается только дляfailedили прерванногоstoppingи требует доступного локального датасета. Это не перезагрузка исправной работающей песочницы.- Действия жизненного цикла могут конфликтовать с сохранением шаблона. Дождитесь завершения сохранения и повторите запрос.
- Песочницу после сбоя не всегда можно восстановить. Если перезапуск
продолжает завершаться ошибкой, изучите вкладку События и
error_reason, сохраните внешние данные и пересоздайте песочницу.