Перейти к основному содержимому
Открыть Markdown

Жизненный цикл песочницы

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

Модель состояний​

Поле status в ответе GET /v1/sandboxes/{id} принимает следующие значения:

СостояниеЗначениеЧто делать
startingСреда выполнения загружаетсяОпросить ресурс до running или failed
runningСреда выполнения доступна для команд, файлов, терминалов и открытых сервисовВыполнить работу, остановить, гибернировать или удалить
stoppingVM остановлена, постоянное состояние диска финализируетсяДождаться 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, сохраните внешние данные и пересоздайте песочницу.