Перейти до основного вмісту
Перекладена сторінка

Цю сторінку перекладено з англійської мови за допомогою ШІ. Якщо тексти відрізняються, еталоном є англійська версія.

Сеанси провайдерів і секрети

Див. також:
[SET] [UNSET] [ Змінні сеансу ] [ Глобальні прапорці ]

Сеанс може прив'язати провайдера під псевдонімом із власними обліковими даними, міткою tenancy, значеннями параметрів за замовчуванням і обмеженнями паралельності запитів, тож в одному сеансі, і навіть в одній інструкції, можна виконувати запити до кількох облікових записів або тенантів того самого провайдера. Поля облікових даних також можна перевизначити для сеансу, а секрети можна зберігати в пам'яті сеансу або, якщо оператор явно це ввімкне, у сховищі секретів операційної системи. Усе це налаштовують інструкціями SET і UNSET; ці можливості доступні в StackQL v1.0 і новіших версіях.

Усе, що тут описано, діє в межах поточного сеансу. Незалежні з'єднання із сервером stackql srv не мають спільних прив'язок чи секретів, а кожен запит MCP є окремим сеансом, тому під час роботи із сервером MCP налаштовуйте й виконуйте запити в одному пакеті інструкцій.

Псевдоніми провайдерів​

Інструкція SET "$.providers.<alias>" прив'язує псевдонім до провайдера. Значенням є документ JSON, записаний як рядок:

КлючОбов'язковийОпис
providerТакКанонічний провайдер, якому відповідає псевдонім, наприклад aws.
tenancyТакМітка групування, наприклад назва облікового запису або тенанта. StackQL не звіряє її з провайдером.
authОдин із auth або auth_secretДокумент автентифікації з тією самою формою, що й запис провайдера в об'єкті --auth. Псевдонім не запозичує облікові дані канонічного провайдера.
auth_secretОдин із auth або auth_secretІм'я секрету сеансу, що містить документ автентифікації.
paramsНіЗначення за замовчуванням для оголошених параметрів провайдера, зокрема оголошених параметрів сервера. Предикат у запиті перевизначає значення за замовчуванням.
tuningНіОбмеження max_concurrent і max_per_host для запитів псевдоніма. Псевдоніми зі спільними провайдером і tenancy мають спільні обмеження й повинні оголошувати однакові параметри налаштування.

У наступному прикладі два облікові записи AWS прив'язано до окремих псевдонімів, кожен із яких зчитує свої ключі зі змінних середовища з різними іменами, а потім до обох виконується запит в одній інструкції:

SET "$.providers.production" = '{
"provider": "aws",
"tenancy": "production-account",
"auth": {
"type": "aws_signing_v4",
"access_key_id_env_var": "PRODUCTION_AWS_ACCESS_KEY_ID",
"secret_access_key_env_var": "PRODUCTION_AWS_SECRET_ACCESS_KEY"
},
"params": {"region": "ap-southeast-2"},
"tuning": {"max_concurrent": 4, "max_per_host": 4}
}';

SET "$.providers.development" = '{
"provider": "aws",
"tenancy": "development-account",
"auth": {
"type": "aws_signing_v4",
"access_key_id_env_var": "DEVELOPMENT_AWS_ACCESS_KEY_ID",
"secret_access_key_env_var": "DEVELOPMENT_AWS_SECRET_ACCESS_KEY"
},
"params": {"region": "ap-southeast-2"},
"tuning": {"max_concurrent": 2}
}';

SELECT name, 'production' AS account FROM production.s3.buckets
UNION ALL
SELECT name, 'development' AS account FROM development.s3.buckets;

Посилання на змінні середовища визначаються із середовища процесу StackQL; локального середовища сеансу немає. Для тимчасових облікових даних AWS також потрібне поле токена сеансу або посилання на відповідну змінну середовища.

Для інструкцій метаданих і даних псевдонім поводиться як його провайдер: SHOW, DESCRIBE, SELECT, INSERT, UPDATE, DELETE і EXEC приймають псевдонім замість імені провайдера. Псевдоніми не поширюються на нативні вбудовані відношення та на відношення IaC, доступні як попередня версія. Гілки UNION ALL, що використовують різні псевдоніми, виконуються послідовно.

Кожен запит бере незалежний знімок облікових даних псевдоніма. Зміна прив'язки впливає на пізніші запити, а не на той, що вже виконується. Інструкція UNSET "$.providers.<alias>" видаляє прив'язку.

Перевизначення полів облікових даних​

Інструкція SET "$.auth.<provider>.<field>" змінює для сеансу одне поле контексту автентифікації провайдера; імена полів - це ключі запису провайдера в --auth:

SET "$.auth.github.password_var" = 'GITHUB_TOKEN_READONLY';
SELECT name FROM github.repos.repos WHERE org = 'stackql';
UNSET "$.auth.github.password_var";

Як і з псевдонімами, зміна застосовується до запитів, запущених після SET. Запити до провайдера, для автентифікації якого скасовано значення, або до провайдера, псевдонім якого не має придатного auth, завершуються помилкою ще до надсилання будь-якого запиту до API.

Секрети сеансу​

За замовчуванням кожен сеанс має сховище секретів лише в пам'яті, яке не потребує налаштування. Інструкція SET "$.secrets.<name>" зберігає літеральний рядок, зазвичай документ автентифікації JSON, а псевдонім провайдера посилається на нього через auth_secret:

SET "$.secrets.production" = '{"type":"aws_signing_v4","access_key_id_env_var":"PRODUCTION_AWS_ACCESS_KEY_ID","secret_access_key_env_var":"PRODUCTION_AWS_SECRET_ACCESS_KEY"}';
SET "$.providers.production" = '{"provider":"aws","tenancy":"production-account","auth_secret":"production","params":{"region":"ap-southeast-2"}}';

SELECT name FROM production.s3.buckets;

UNSET "$.secrets.production";

Ротація секрету впливає на пізніші запити; після його видалення подальші спроби використання завершуються помилкою. Новий сеанс отримує нове порожнє сховище, а завершення сеансу звільняє його. Інструкція UNSET "$.secret_store" скидає поточну прив'язку сховища й починає знову з порожньою пам'яттю сеансу.

Звичайне використання облікових даних та інструкції SET, що зберігають змінні або конфігурацію, не записують секрети в бекенд SQL. За розміщення конфіденційних даних у звичайній змінній або таблиці відповідає сторона, що викликає.

Постійні сховища секретів ОС​

Постійне зберігання за замовчуванням вимкнено, і ввімкнути його може лише оператор, запустивши StackQL із прапорцем --allow-persistent-secrets; SQL не може надати цю можливість. Якщо прапорець встановлено, сеанс вибирає сховище ОС так:

SET "$.secret_store" = '{"backend": "os", "namespace": "stackql/provider-auth"}';

Сховищем є macOS Keychain, Linux Secret Service (secret-tool із робочою службою сеансу) або Windows Credential Manager. Приймається лише бекенд os: сховища у звичайних файлах, шляхи до файлів і будь-який неявний резервний варіант із файлом відхиляються навіть зі встановленим прапорцем, а недоступний механізм ОС призводить до помилки замість переходу на файл.

Значення, записані у сховище ОС, існують і після завершення сеансу SQL; їх видаляють явно інструкцією UNSET "$.secrets.<name>". Скидання прив'язки сховища не видаляє вже збережені значення. Доступ до сховища визначається ідентичністю процесу StackQL в операційній системі; простір імен не є механізмом керування доступом для окремих користувачів, тому не розглядайте це явне ввімкнення як багатокористувацьке сховище секретів.

Значення секретів у SQL​

Значення секретів ніколи не розіменовуються в SQL, якщо оператор не запустив StackQL із прапорцем --allow-secret-dereference. З цим прапорцем посилання, як-от "$secrets.production", "$secrets.production.credentials", "$auth.github.password" і "$providers.production.auth.credentials", визначаються у виразах:

SELECT upper("$secrets.production.credentials") AS credential;

/*
-- the same statement in a session started without --allow-secret-dereference
SELECT upper("$secrets.production.credentials") AS credential;
-- FAILS with secret variable dereferencing is disabled
*/

Якщо StackQL запущено без цього прапорця, ту саму інструкцію буде відхилено ще до обчислення будь-чого, як показує закоментована копія. Прапорець є підтвердженням того, що явно розіменовані значення можуть потрапити в проміжне середовище SQL, результати, журнали та збережені артефакти запитів. Для звичайної автентифікації провайдера він не потрібен.

Дозволи​

Якщо ввімкнено керування доступом, для читання змінних і секретів потрібен дозвіл session/variables:read, а для SET або UNSET - session/config:write. Перед виконанням визначений псевдонім авторизується як його канонічний провайдер. Володіння й надання дозволів на рівні окремих змінних і секретів не реалізовано.