本頁面由英文在 AI 協助下翻譯而成。若兩者有出入,請以英文版本為準。
Provider 工作階段與祕密
另請參閱:
[SET] [UNSET] [ 工作階段變數 ] [ 全域旗標 ]
工作階段可以用別名繫結 Provider,並為其指定專屬的憑證、租用標籤、參數預設值與要求並行限制,因此可以在同一個工作階段中,甚至在同一個陳述式中,查詢同一個 Provider 的多個帳戶或租用戶。也可以針對工作階段覆寫憑證欄位,並將祕密保存在工作階段記憶體中,或在維運人員選擇加入後,保存在作業系統的祕密存放區中。以上所有設定都透過 SET 與 UNSET 完成,適用於 StackQL v1.0 及更新版本。
這裡說明的所有內容都限定在目前的工作階段。連到 stackql srv 伺服器的各個獨立連線不會共用繫結或祕密,而且每個 MCP 要求都是獨立的工作階段,因此使用 MCP 伺服器時,請在同一個陳述式批次中完成設定與查詢。
Provider 別名
SET "$.providers.<alias>" 會將別名繫結到 Provider。其值是存放在字串中的 JSON 文件:
| 鍵 | 必要 | 描述 |
|---|---|---|
provider | 是 | 別名所解析成的標準 Provider,例如 aws。 |
tenancy | 是 | 分組標籤,例如帳戶或租用戶名稱。StackQL 不會向 Provider 核對此標籤。 |
auth | auth 與 auth_secret 擇一 | 驗證文件,其結構與 Provider 在 --auth 物件中的項目相同。別名不會沿用標準 Provider 的憑證。 |
auth_secret | auth 與 auth_secret 擇一 | 保存驗證文件的工作階段祕密名稱。 |
params | 否 | 已宣告之 Provider 參數的預設值,包括已宣告的伺服器參數。查詢中的述詞會覆寫預設值。 |
tuning | 否 | 此別名之要求的 max_concurrent 與 max_per_host 限制。Provider 與租用標籤都相同的別名會共用這些控制項,且必須宣告相同的 tuning 設定。 |
以下範例以不同的別名繫結兩個 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 憑證還需要工作階段權杖欄位或其環境變數參考。
對中繼資料與資料陳述式而言,別名的行為與其 Provider 相同:SHOW、DESCRIBE、SELECT、INSERT、UPDATE、DELETE 與 EXEC 都接受以別名取代 Provider 名稱。別名不適用於原生內建關聯,也不適用於預覽版 IaC 關聯。使用不同別名的 UNION ALL 分支會依序執行。
每個查詢都會取得別名憑證的獨立快照。變更繫結會影響之後的查詢,不會影響已在執行中的查詢。UNSET "$.providers.<alias>" 會移除繫結。
覆寫憑證欄位
SET "$.auth.<provider>.<field>" 會在工作階段中變更 Provider 驗證內容的一個欄位,欄位名稱即 Provider 之 --auth 項目中的鍵:
SET "$.auth.github.credentialsenvvar" = 'GITHUB_TOKEN_READONLY';
SELECT name FROM github.repos.repos WHERE org = 'stackql';
UNSET "$.auth.github.credentialsenvvar";
與別名相同,變更會套用到 SET 之後才開始的查詢。若查詢的 Provider 驗證已被取消設定,或其別名沒有可用的 auth,查詢會在送出任何要求之前失敗。
工作階段祕密
根據預設,每個工作階段都有一個僅存在於記憶體中的祕密存放區,不需任何設定。SET "$.secrets.<name>" 會儲存一個常值字串,通常是 JSON 驗證文件,Provider 別名則以 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 後端。將敏感資料放入一般變數或資料表,是呼叫端的責任。
持續性 OS 祕密存放區
持續性儲存預設為停用,只有維運人員以 --allow-persistent-secrets 啟動 StackQL 才能啟用;無法透過 SQL 授與。設定此旗標後,工作階段可以使用下列陳述式選取 OS 存放區:
SET "$.secret_store" = '{"backend": "os", "namespace": "stackql/provider-auth"}';
存放區是 macOS Keychain、Linux Secret Service(需搭配工作階段服務可正常運作的 secret-tool)或 Windows Credential Manager。只接受 os 後端:即使設定了旗標,平面檔案存放區、檔案路徑以及任何隱含的檔案後援都會遭到拒絕;OS 功能無法使用時會直接失敗,而不會改用檔案。
寫入 OS 存放區的值在 SQL 工作階段結束後仍會保留,必須以 UNSET "$.secrets.<name>" 明確刪除。重設存放區繫結不會刪除已保存的值。對存放區的存取取決於 StackQL 處理程序的作業系統身分;命名空間並不是個別使用者的存取控制,因此請勿將這項選擇加入的功能視為多使用者保管庫。
SQL 中的祕密值
除非維運人員以 --allow-secret-dereference 啟動 StackQL,否則祕密值絕不會被解除參考到 SQL 中。設定此旗標後,"$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
*/
如註解掉的副本所示,未設定此旗標而啟動時,相同的陳述式會在任何求值之前遭到拒絕。設定此旗標即表示承認明確解除參考的值可能進入 SQL 暫存、結果、記錄以及保存的查詢成品。一般的 Provider 驗證不需要此旗標。
權限
啟用存取管理時,讀取變數與祕密需要 session/variables:read,SET 或 UNSET 則需要 session/config:write。解析後的別名會在執行前以其標準 Provider 的身分進行授權。個別變數與個別祕密的擁有權及授與並未實作。