# Доступ к хранилищу из песочницы

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

## Перед началом[​](#before-you-begin "Прямая ссылка на Перед началом")

Вам нужны:

* инсталляция с включенным хранилищем аккаунта;
* право создавать или настраивать песочницы в активном аккаунте;
* шаблон с `jr-storage` либо `curl` и `jq` для прямого запасного варианта через REST.

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

Выбирайте режим с минимальными правами:

| Режим  | Что разрешено                                                                            |
| ------ | ---------------------------------------------------------------------------------------- |
| `ro`   | Список ключей, просмотр потребления и метаданных, скачивание, создание presigned GET URL |
| `rw`   | Все из `ro`, а также загрузка, перезапись, удаление и presigned PUT URL                  |
| `none` | У песочницы нет учетных данных хранилища                                                 |

Выданный доступ охватывает все пространство хранилища аккаунта, к которому относится песочница. Доступа к отдельным префиксам для песочницы нет. Префикс наподобие `pipelines/reader-a/` помогает организовать ключи, но не является границей доступа.

## Выдача доступа при создании песочницы[​](#grant-access-when-creating-a-sandbox "Прямая ссылка на Выдача доступа при создании песочницы")

В веб-интерфейсе откройте *Песочницы* → *Новая песочница*, выберите карточку каталога и перед созданием в блоке *Дополнительные настройки* установите *Доступ к хранилищу* в *Чтение* или *Чтение и запись*.

Через API передайте в `storage_access` значение `ro` или `rw`:

```
CREATE_RESPONSE="$(
  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",
      "storage_access": "ro",
      "wait_until_ready": true
    }'
)"

SANDBOX_ID="$(jq -er '.id' <<<"$CREATE_RESPONSE")"

curl --fail-with-body --silent --show-error \
  "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
  --header "Authorization: Bearer $JUSTRUN_PAT" |
  jq '{id, status, storage_access}'
```

В ответе на повторный запрос должно быть `"storage_access": "ro"`. Платформа добавляет в окружение песочницы `JR_STORAGE_URL` и отдельный `JR_STORAGE_TOKEN`. Не выводите их значения.

## Проверка доступа внутри песочницы[​](#verify-access-inside-the-sandbox "Прямая ссылка на Проверка доступа внутри песочницы")

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

```
test -n "$JR_STORAGE_URL"
test -n "$JR_STORAGE_TOKEN"

if command -v jr-storage >/dev/null; then
  jr-storage usage | jq '{bytes_used, object_count, pending_bytes, quota_bytes}'
else
  curl --fail-with-body --silent --show-error \
    "$JR_STORAGE_URL/v1/storage/usage" \
    --header "Authorization: Bearer $JR_STORAGE_TOKEN" |
    jq '{bytes_used, object_count, pending_bytes, quota_bytes}'
fi
```

Стандартная вспомогательная утилита поддерживает:

```
jr-storage put <local-file> <key>
jr-storage get <key> [output-file]
jr-storage ls [prefix]
jr-storage rm <key>
jr-storage usage
```

`put` и `get` запрашивают presigned URL, поэтому байты файла передаются напрямую между песочницей и лежащим в основе объектным хранилищем. `ls` возвращает только первую страницу до 100 объектов. Для полного списка используйте REST API с пагинацией.

Текущий `jr-storage put` также вызывает шлюз для завершения публикации и возвращает успех только после успешного завершения. Старую вспомогательную утилиту, которая только передает байты, нужно обновить. Завершение проверяет текущее право записи песочницы, включая отзыв после выдачи URL.

## Публикация и чтение артефакта[​](#publish-and-consume-an-artifact "Прямая ссылка на Публикация и чтение артефакта")

В режиме `rw` загрузите временный объект, скачайте его, сравните байты и выполните очистку:

```
KEY="examples/storage-access/result.txt"
SOURCE_FILE="/tmp/storage-source.txt"
DOWNLOADED_FILE="/tmp/storage-downloaded.txt"

printf 'sandbox storage round-trip\n' >"$SOURCE_FILE"
jr-storage put "$SOURCE_FILE" "$KEY"
jr-storage get "$KEY" "$DOWNLOADED_FILE"
cmp "$SOURCE_FILE" "$DOWNLOADED_FILE"
jr-storage rm "$KEY"
rm -f "$SOURCE_FILE" "$DOWNLOADED_FILE"
```

В режиме `ro` работают `get`, `ls` и `usage`, а `put` и `rm` завершаются с ненулевым кодом выхода, потому что шлюз возвращает HTTP `403`. Типичная схема конвейера выдает производителю режим `rw`, а потребителю — `ro`.

## Изменение и отзыв доступа[​](#change-or-revoke-access "Прямая ссылка на Изменение и отзыв доступа")

На вкладке *Настройки* песочницы найдите раздел *Доступ к хранилищу* и выберите *Нет доступа*, *Чтение* или *Чтение/запись*.

Эквивалентный API-запрос:

```
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":"rw"}' |
  jq '{id, storage_access}'
```

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

Отзовите доступ:

```
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":"none"}' |
  jq '{id, storage_access}'
```

Отзыв удаляет `JR_STORAGE_URL` и `JR_STORAGE_TOKEN` из сохраненного окружения. Уже запущенный процесс может по-прежнему хранить строку старого токена, но не сможет продолжать использовать его после распространения отзыва. Удаление песочницы тоже делает недействительными ее учетные данные хранилища, но не удаляет объекты хранилища аккаунта.

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

```
curl --fail-with-body --silent --show-error \
  --request DELETE "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
  --header "Authorization: Bearer $JUSTRUN_PAT"
```

Успешное удаление возвращает HTTP `204`. Ранее загруженные в хранилище аккаунта объекты сохраняются, пока их не удалят отдельно.

## Диагностика[​](#troubleshooting "Прямая ссылка на Диагностика")

| Симптом                                                                           | Причина и действие                                                                                                                                                                                   |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Создание песочницы или PATCH возвращает `400` и сообщает об отключенном хранилище | Инсталляция не предоставляет хранилище аккаунта; уберите выдачу доступа или обратитесь к оператору                                                                                                   |
| Нет `JR_STORAGE_*`                                                                | У песочницы `storage_access: none`, процесс запущен до выдачи доступа либо обновление в запущенной песочнице не сработало; проверьте песочницу и запустите новый процесс или перезапустите песочницу |
| `jr-storage: command not found`                                                   | В шаблоне нет вспомогательной утилиты; вызовите `/v1/storage` с подставленными переменными или используйте шаблон, в котором она есть                                                                |
| Чтение возвращает `401`                                                           | Учетные данные повреждены, ротированы, отозваны или относятся к удаленной песочнице; не повторяйте их                                                                                                |
| Запись возвращает `403`                                                           | У песочницы режим `ro`; выдавайте `rw`, только если рабочая нагрузка должна менять общее хранилище                                                                                                   |
| Запись возвращает `429`                                                           | Квота хранилища аккаунта исчерпана или зарезервирована незавершенной загрузкой; проверьте `jr-storage usage`                                                                                         |
| `jr-storage ls` не показывает ожидаемые ключи                                     | Он читает только первую страницу; используйте пагинацию по курсору в REST и проверьте префикс                                                                                                        |
| Нет доступа к URL прямой передачи                                                 | Presigned URL ведет в лежащее в основе объектное хранилище, а не в шлюз; проверьте исходящий трафик песочницы и повторите до `expires_at`                                                            |

## Для рабочей среды[​](#production-considerations "Прямая ссылка на Для рабочей среды")

* Никогда не логируйте, не выводите, не сохраняйте и не копируйте `JR_STORAGE_TOKEN` за пределы песочницы.
* Для потребителя предпочитайте `ro`. Песочница с `rw` может перезаписать или удалить любой объект в пространстве аккаунта.
* Отзыв не отменяет уже выполняющиеся запросы и presigned URL, созданные до него. Presigned URL остается пригодным до собственного `expires_at`.
* Используйте неизменяемые или версионированные ключи для артефактов конвейера. Общие изменяемые ключи требуют координации на уровне приложения.
* Доступ к хранилищу не связан с постоянством корневого диска. Остановка и гибернация сохраняют диск песочницы; объекты аккаунта переживают удаление песочницы.
* Отзыв не останавливает запущенный процесс и не стирает уже скачанные им файлы. Обрабатывайте копии данных согласно собственной политике жизненного цикла.

## Связанные разделы[​](#related "Прямая ссылка на Связанные разделы")

* [Постоянные данные и хранилище](/sandboxes/persistence-and-storage.md)
* [Загрузка и скачивание](/storage/upload-and-download.md)
* [Объекты и ключи](/storage/objects-and-keys.md)
* [Квоты и потребление](/storage/quotas-and-usage.md)
* [Настройка песочницы](/sandboxes/configure-a-sandbox.md)
* [Справочник REST API](/api-reference/rest.md)
