Хранилище секретов

Хранилище секретов помогает держать тестовые учётные данные отдельно от моков. В пространстве имён можно создать локальное зашифрованное хранилище или читать значения из поддерживаемого внешнего сервиса. В теле мока или шаблоне запись $.secrets.<store>.<key> ссылается на секрет без копирования его значения в определение мока.

Содержание

1. Зачем нужно централизованное хранилище
2. Хранилища и записи
3. Разрешения
4. Ссылки на секреты в моках
5. Интеграция с Vault
6. Примеры для SDK и CLI

Зачем нужно централизованное хранилище

Храните учётные данные отдельно от определений моков: тогда значение можно заменить, не редактируя каждый мок. Список хранилищ и метаданные записей не показывают значения; для чтения значения локальной записи нужно право secret:read. При ротации передайте новое значение — Mockarty заменит старое и увеличит версию записи.

Для локальных хранилищ (inline) со стандартным программным хранением ключей администратор должен задать MOCKARTY_PII_ENCRYPTION_KEY перед запуском Mockarty. Без ключа шифрования создать или прочитать локальную запись не получится. Переменная описана в Руководстве администратора.

Хранилища и записи

Хранилище секретов — именованный контейнер внутри пространства имён. В inline-хранилище находятся записи с ключом и зашифрованным значением. Внешние бэкенды читают значения из соответствующих сервисов; сами значения нужно создавать и менять в этих сервисах.

Поле backend:

• inline — вариант по умолчанию; Mockarty хранит зашифрованные значения локально;
• vault — читает значения из HashiCorp Vault KV v1 или v2;
• aws_sm — читает из AWS Secrets Manager; нужны регион и учётные данные AWS;
• gcp_sm — читает из Google Secret Manager; нужны проект и учётные данные Google;
• azure_kv — читает из Azure Key Vault; нужны URL хранилища и учётные данные Azure;
• custom_api — читает из настроенного HTTPS-эндпоинта; поддерживаются заголовки запроса и необязательное извлечение через JSONPath.

Для внешнего бэкенда настройте подключение в разделе Хранилища → Секреты, а значения создавайте и меняйте во внешнем сервисе. Примеры создания и ротации записей ниже относятся к inline.

Список Хранилища → Секреты и окно записей отдельно показывают загрузку, пустой список, необходимость входа, отказ в доступе и временную недоступность. Если чтение не удалось, устраните причину и нажмите Повторить; вместо записей не выводится техническая ошибка HTTP.

Как выключить хранилище

По умолчанию хранилище включено. Когда вы его выключаете, Mockarty перестаёт
подставлять значения. API записей также отклоняет запись и ротацию с кодом
409 и названием выключенного хранилища. Мок со ссылкой на такую запись не
сможет подставить её значение.

Имена существующих записей остаются видимыми в списке. Включите хранилище,
чтобы снова использовать значения; выключение ничего не удаляет.

Разрешения

Токены без secret:read получают 403 при GET /api/v1/stores/secrets/:id/entries/:key.

При настройке токена Vault или секрета для аутентификации в пользовательском
API на вкладке Хранилища → Секреты нажмите Выбрать запись секрета
рядом с полем ID. Список ищет записи только во включённых inline-хранилищах
текущего пространства имён и показывает лишь имя хранилища и ключ записи.
Значение секрета не отображается и не возвращается. Для поиска требуется
secret:read; ID записи также можно ввести вручную. При смене пространства
имён редактор закрывается и сбрасывает текущий выбор.

Ссылки на секреты в моках

В теле мока, шаблоне или переменной тест-плана пишите:

Bearer $.secrets.payments.stripe_api_key

Mockarty ищет хранилище payments в текущем пространстве имён и подставляет текущее значение stripe_api_key. Если хранилище или ключ недоступны, Mockarty не сможет подставить значение и не вставит старое или чужое. Подставленное значение попадёт в ответ мока, поэтому используйте такую ссылку, только если вызывающий клиент должен его получить.

Интеграция с Vault

Для первого подключения Vault сохраните токен Vault как запись в активном inline-хранилище того же пространства имён. Скопируйте id записи из ответа на создание. Затем вызовите PUT /api/v1/namespaces/{ns}/integrations/vault с адресом Vault и tokenSecretId. Запрос создаст хранилище vault-default, читающее значения из Vault.

curl -sS -X PUT http://localhost:5770/api/v1/namespaces/production/integrations/vault \
  -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://vault.example.com","tokenSecretId":"<inline-entry-id>","mount":"secret","kvVersion":2}'

В CLI передайте тот же ID сохранённой записи:

mockarty-cli namespace vault-integrate --ns production \
  --url https://vault.example.com --token-secret-id "$VAULT_TOKEN_ENTRY_ID" \
  --mount secret

Запись с токеном должна уже существовать в production; для этого запроса требуется secret:write. Чтобы изменить существующее хранилище vault-default, используйте редактор хранилища, не повторяйте запрос на создание.

Примеры для SDK и CLI

Примеры используют inline-хранилище в sandbox. Создайте API-токен с правом secret:write; если нужно читать значения, добавьте secret:read. Замените демонстрационные значения своими и сохраните id из ответа на создание хранилища в STORE_ID.

cURL

# Создать хранилище
curl -sS -X POST http://localhost:5770/api/v1/stores/secrets \
  -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"payments","namespace":"sandbox","backend":"inline"}'

# Добавить запись
curl -sS -X POST http://localhost:5770/api/v1/stores/secrets/$STORE_ID/entries \
  -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"stripe_api_key","value":"example-old-value"}'

# Ротация
curl -sS -X POST http://localhost:5770/api/v1/stores/secrets/$STORE_ID/entries/stripe_api_key/rotate \
  -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":"example-new-value"}'

CLI

mockarty-cli secrets store create --name payments --backend inline
mockarty-cli secrets entry create --store "$STORE_ID" --key stripe_api_key --value example-old-value
mockarty-cli secrets entry rotate --store "$STORE_ID" --key stripe_api_key --value example-new-value
mockarty-cli secrets entry list   --store "$STORE_ID"

Go

store, err := client.Secrets().CreateStore(ctx, mockarty.SecretStore{Name: "payments", Backend: "inline"})
if err != nil { panic(err) }
_, err = client.Secrets().CreateEntry(ctx, store.ID, mockarty.SecretEntry{
    Key:   "stripe_api_key",
    Value: "example-old-value",
})
if err != nil { panic(err) }
_, err = client.Secrets().RotateEntry(ctx, store.ID, "stripe_api_key", "example-new-value")
if err != nil { panic(err) }

Python

store = client.secrets.create_store(name="payments", backend="inline")
client.secrets.create_entry(store["id"], key="stripe_api_key", value="example-old-value")
client.secrets.rotate_entry(store["id"], "stripe_api_key", "example-new-value")

Java

Map<String, Object> store = client.secrets().createStore("payments", null, "inline");
client.secrets().createEntry((String) store.get("id"), "stripe_api_key", "example-old-value", null);
client.secrets().rotateEntry((String) store.get("id"), "stripe_api_key", "example-new-value");

См. также: Руководство по JsonPath, Руководство администратора, Хранилище промптов.