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

Постоянные данные и хранилище

В Just Run есть два независимых способа хранить постоянные данные. Корневая файловая система принадлежит одной песочнице и подходит для рабочего дерева и установленных инструментов. Хранилище аккаунта — это опциональное объектное хранилище с явной выдачей доступа; оно подходит для артефактов, которые должны пережить песочницу или переходить между песочницами.

Выбор места для данных​

ТребованиеКорневая файловая системаХранилище аккаунта
Обычные POSIX-пути, установка пакетов, рабочее дерево GitДаНет; это объектное хранилище «ключ → байты»
Переживает остановку и возобновлениеДаДа
Сохраняет запущенные процессыТолько гибернация сохраняет память VMХранилище не хранит процессы
Доступно нескольким песочницамНетДа, внутри активного аккаунта
Переживает удаление песочницыНетДа, пока не удален объект
Доступно в каждой инсталляцииКорневая файловая система обязательнаНет; хранилище может быть отключено
Доступ с ноутбука или CIЧерез API файлов песочницыНапрямую через /v1/storage

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

Жизненный цикл корневой файловой системы​

Каждая песочница начинает работу с клона файловой системы шаблона. Изменения через терминал, /exec, API файлов или компонент подготовки попадают на корневой диск этой песочницы.

ДействиеКорневая файловая системаПроцессы и память
ОстановкаСохраняетсяТеряются
Возобновление после остановкиВосстанавливается при холодной загрузкеЗапускаются новые процессы
ГибернацияСохраняетсяПамять и состояние выполнения VM попадают в снимок
Пробуждение после гибернацииСохраняетсяСостояние снимка восстанавливается
УдалениеУничтожаетсяУничтожаются

У удаления нет публичной операции отмены или восстановления. Экспортируйте ценные результаты до удаления песочницы. Сохранение песочницы как шаблона полезно, когда вся настроенная файловая система должна стать переиспользуемой отправной точкой; для независимых объектов данных лучше подходит хранилище.

Переходы состояний описаны в жизненном цикле песочницы, а файловые операции — в разделе Файлы и Git.

Размер корневого диска​

Передайте disk_mb при создании песочницы. Значение задается в МиБ:

curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data '{
"template": "base",
"disk_mb": 16384,
"wait_until_ready": true
}' |
jq '{id, status, disk_mb}'

Итоговый размер определяется так:

  • при отсутствии значения используется значение шаблона по умолчанию, затем значение инсталляции по умолчанию;
  • диск не может быть меньше файловой системы, запеченной в шаблон;
  • шлюз поднимает запрос как минимум до 2048 МиБ и до минимума шаблона;
  • жесткий предел платформы — 65536 МиБ, но инсталляция может задать меньший;
  • запрос вне диапазона приводится к эффективному минимуму или максимуму;
  • диск можно увеличить только при создании, а изменить размер или уменьшить его позднее нельзя.

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

Размер диска и свободное место — не одно и то же

disk_mb — размер подготовленной корневой файловой системы. Часть места занимают файлы шаблона, установленные пакеты, логи и ваши данные. Проверяйте свободное место командой df -h внутри песочницы.

Хранилище аккаунта​

Хранилище — плоское пространство ключей и байтов в пределах аккаунта. Ключи наподобие runs/42/result.json выглядят иерархически, но каталоги в нем являются неявными префиксами. Пользователь аутентифицируется обычным bearer-токеном. Песочница получает отдельный токен с ограниченными правами, только если вы выдаете доступ ro или rw.

Создайте песочницу с доступом на чтение и запись:

{
"template": "base",
"storage_access": "rw"
}

Либо выдайте, измените или отзовите доступ существующей песочницы:

curl --fail-with-body --silent --show-error \
--request PATCH "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data '{"storage_access":"ro"}' |
jq '{id, storage_access}'

Для отзыва используйте "none". При выдаче доступа в окружение песочницы добавляются JR_STORAGE_URL и JR_STORAGE_TOKEN. При смене режима токен ротируется; отзыв инвалидирует старый токен и удаляет сохраненные переменные. Новые процессы видят обновленное окружение, а уже запущенный процесс сохраняет исходное.

Поддерживаемые шаблоны содержат вспомогательную утилиту jr-storage:

jr-storage usage
jr-storage put ./result.json runs/42/result.json
jr-storage get runs/42/result.json ./downloaded-result.json
jr-storage ls runs/42/
jr-storage rm runs/42/result.json

Режим ro разрешает список, метаданные, скачивание, потребление и presigned GET URL. Он запрещает загрузку, удаление и presigned PUT URL. Режим rw разрешает чтение и запись.

Обращайтесь к хранилищу вне песочницы​

Используйте персональный токен и REST API:

ОперацияЗапрос
Список ключейGET /v1/storage/objects?prefix=...&delimiter=/&cursor=...&limit=...
Загрузка сырых байтовPUT /v1/storage/objects/{key}
Скачивание сырых байтовGET /v1/storage/objects/{key}
Чтение метаданныхHEAD /v1/storage/objects/{key}
УдалениеDELETE /v1/storage/objects/{key}
URL для прямой передачиPOST /v1/storage/presign
Проверка объектной квотыGET /v1/storage/usage

Например, проверьте квоту и загрузите объект в теле запроса:

curl --fail-with-body --silent --show-error \
"$JUSTRUN_API/v1/storage/usage" \
--header "Authorization: Bearer $JUSTRUN_PAT" |
jq '{bytes_used, pending_bytes, quota_bytes, object_count}'

curl --fail-with-body --silent --show-error \
--request PUT "$JUSTRUN_API/v1/storage/objects/runs/42/result.json" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data-binary @result.json |
jq '{key, size, etag}'

Ограничения передачи в теле запроса задаются в инсталляции. Для крупных объектов запросите presigned GET или PUT URL и передавайте данные прямо в лежащее в основе объектное хранилище. Для presigned PUT нужен точный content_length; URL и срок его действия приходят в ответе.

Страница списка по умолчанию содержит 100 записей и принимает limit от 1 до 1000. Следуйте по непрозрачному next_cursor, пока он не станет null. Ключи объектов задаются относительно аккаунта, не могут начинаться или заканчиваться / и не могут содержать пустые сегменты, сегменты . или .., обратную косую черту и управляющие символы.

Квоты и доступность​

Квота корневых дисков и хранилища аккаунта — разные бюджеты:

  • GET /v1/account/overview показывает количество песочниц, vCPU, RAM и использование корневых дисков песочниц относительно лимитов аккаунта;
  • GET /v1/storage/usage показывает байты объектов, их количество, ожидающие presigned-загрузки и квоту объектного хранилища.

Не выводите один бюджет из другого. Запись в хранилище, которая превысит bytes_used + pending_bytes + incoming, возвращает HTTP 429.

Хранилище настраивается для каждой инсталляции. Когда оно отключено, маршруты /v1/storage/* не смонтированы и возвращают 404, а создание песочницы отвергает storage_access. Веб-интерфейс показывает область хранилища, только когда возможность доступна.

Границы безопасности и отказов​

  • Считайте JR_STORAGE_TOKEN и presigned URL bearer-учетными данными. Не выводите их в логи, не печатайте, не коммитьте и не передавайте другим.
  • Доступ к хранилищу, выданный песочнице, открывает общее пространство активного аккаунта. Используйте ro, если рабочая нагрузка не должна писать, и отзывайте ненужный доступ.
  • Удаление файла корневого диска или объекта хранилища нельзя отменить через публичный API.
  • Presigned-загрузка резервирует pending_bytes до сверки или истечения; незавершенная загрузка может временно уменьшить свободную квоту.
  • Ошибка бэкенда хранилища может вернуть 503. Сохраняйте локальный результат до успешной загрузки в хранилище и проверяйте важный объект через метаданные или скачивание.
  • Корневая файловая система — не механизм синхронизации. Для обмена между песочницами используйте неизменяемые или версионированные ключи хранилища, а не рассчитывайте на общую POSIX-семантику.