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

Использование секретов с песочницами

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

В этом руководстве используется секрет типа env с именем sandbox-demo и переменной DEMO_API_TOKEN. Проверка подтвердит наличие переменной, не печатая ее значение.

Перед началом​

Вам нужны:

  • секрет в том же активном аккаунте, где будет создана песочница;
  • право на создание и использование песочниц в этом аккаунте;
  • шаблон, доступный аккаунту;
  • cURL, jq и персональный токен с правами Полные для REST-варианта.

В организации личный секрет можно подключить только к новой личной песочнице того же автора. Общая песочница ("visibility": "org") принимает секреты организации. E2B создает личную песочницу и принимает личные секреты ее автора.

Создайте пример sandbox-demo по руководству Создание и управление секретами, затем задайте:

export JUSTRUN_API="https://your-just-run-host"
export JUSTRUN_PAT="your-personal-access-token"
export JUSTRUN_TEMPLATE="base"
export SECRET_NAME="sandbox-demo"

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

Создание через веб-интерфейс​

  1. Откройте Песочницы → Новая песочница и выберите карточку каталога.
  2. Проверьте шаблон и настройки ресурсов.
  3. Раскройте Дополнительные настройки, затем в разделе Интеграции раскройте Секреты.
  4. Найдите и выберите каждый секрет для материализации. В этой же панели можно создать новый секрет — он выберется автоматически.
  5. Нажмите Создать песочницу.

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

Создание через REST API​

Соберите запрос из шаблона и имени секрета, затем сохраните ID созданной песочницы:

CREATE_RESPONSE="$(
jq -n '{
template: env.JUSTRUN_TEMPLATE,
name: "secret-consumer-demo",
secrets: [env.SECRET_NAME]
}' |
curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: secret-consumer-demo-1" \
--data-binary @-
)"

SANDBOX_ID="$(jq -er '.id' <<<"$CREATE_RESPONSE")"
jq '{id, status, provisioning}' <<<"$CREATE_RESPONSE"

Новая песочница возвращает HTTP 201. Разрешение секретов происходит до передачи запроса узлу. Если хотя бы одно явно выбранное имя неизвестно, API возвращает 404 и не создает песочницу.

Используйте один Idempotency-Key для одной логической операции создания. Повторяйте его только при неопределенном результате того же запроса.

Ожидание готовности результата​

Создание может вернуться до завершения асинхронной подготовки. Опрашивайте песочницу, пока она не станет running, а необязательная сводка подготовки — ready:

while :; do
SANDBOX="$(
curl --fail-with-body --silent --show-error \
"$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
--header "Authorization: Bearer $JUSTRUN_PAT"
)"

STATUS="$(jq -r '.status' <<<"$SANDBOX")"
PROVISIONING="$(jq -r '.provisioning.status // "ready"' <<<"$SANDBOX")"

if [ "$STATUS" = "failed" ] || [ "$PROVISIONING" = "failed" ]; then
jq '{status, provisioning}' <<<"$SANDBOX"
exit 1
fi

if [ "$STATUS" = "running" ] && [ "$PROVISIONING" = "ready" ]; then
break
fi

sleep 2
done

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

Проверка без раскрытия значения​

Проверьте условие внутри песочницы вместо печати токена:

curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/exec" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data '{
"cmd": "sh",
"args": [
"-lc",
"test -n \"$DEMO_API_TOKEN\" && printf \"secret-present\\n\""
],
"timeout": 30000
}' |
jq '{exit_code, stdout, stderr}'

Ожидаемый вывод:

{
"exit_code": 0,
"stdout": "secret-present\n",
"stderr": ""
}

HTTP 200 означает только завершение выполнения команды. Проверяйте exit_code: ненулевой результат означает отсутствие переменной или ошибку проверки.

Результат материализации​

При создании песочницы поддерживаются все типы секретов Just Run:

  • env добавляет переменные окружения;
  • git_credential настраивает HTTPS-аутентификацию для подходящих хостов Git;
  • repo добавляет клонирование репозитория и при необходимости разрешает связанный git_credential;
  • mcp_server добавляет удаленный сервер в конфигурацию MCP-клиента песочницы;
  • ssh_key записывает файлы ключей и необязательный known_hosts;
  • registry_credential записывает аутентификацию в реестре пакетов или контейнеров;
  • file записывает декодированные байты с заданными путем и правами доступа.

Если путь секрета типа file начинается с ~/, Just Run разрешает ~ в домашний каталог настроенного пользователя по умолчанию и передает этому пользователю владение новым файлом. Явный абсолютный путь вроде /root/credentials сохраняется без изменения; процесс по умолчанию без прав root не сможет прочитать файл, принадлежащий root, с правами 0600.

Репозитории из секретов и репозитории, заданные напрямую в песочнице, добавляются друг к другу. Ошибка клонирования обязательного репозитория переводит подготовку в failed. Если сохраненный репозиторий ссылается на отсутствующие учетные данные Git или секрет неверного типа, разрешение продолжится без учетных данных, после чего приватный клон может завершиться ошибкой.

Приоритет и жизненный цикл​

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

{
"template": "base",
"env": {
"DEMO_API_TOKEN": "inline-value"
},
"secrets": ["sandbox-demo"]
}

В этом запросе будет использовано значение, заданное напрямую. Среди секретов переменные окружения конфликтуют по ключу, учетные данные Git — по хосту, MCP-серверы — по имени. Порядок списка в запросе не задает приоритет; устраняйте пересечения записей вместо зависимости от внутренних ID.

Материализация создает снимок:

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

Очистка​

Удалите демонстрационную песочницу:

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

Успешное удаление возвращает HTTP 204. Сохраните переиспользуемый секрет или отдельно удалите демонстрационный секрет на странице Секреты либо через его ID в API секретов.

Решение проблем​

  • HTTP 404 до создания: как минимум одно выбранное имя отсутствует в активном аккаунте.
  • HTTP 503: в инсталляции не настроен ключ шифрования секретов или ни один узел сейчас не может принять песочницу.
  • status: "running" при provisioning.status: "failed": проверьте provisioning.steps, чтобы найти сбойный шаг записи файла, клонирования или настройки.
  • Вместо значения секрета появилось значение, заданное напрямую: поля, заданные напрямую, имеют намеренный приоритет.
  • В старой песочнице нет ротированного значения: создайте новую песочницу; живой связи с исходным секретом нет.