guide:schema-changes@zh-Hant

指南

變更與測試 schema

論文如何讓命名空間設定的變更在單一請求內保持一致、為什麼在今日的產品中移除一個關係需要三個步驟,以及如何在 CI 中以斷言檔測試模型。

事實查核日期 論文相關章節 §2.1, §2.3, §3.1.3, §3.2.2, §4

schema 是授權系統中最少變動、但一變動就最容易出問題的部分。在論文中,它是命名空間設定:“A namespace configuration specifies its relations as well as its storage parameters”(命名空間設定會指定其關係以及儲存參數)(§2.3)。在 Google 有 “more than 1,500 namespaces”(超過 1,500 個命名空間),其設定檔 “range from tens of lines to thousands of lines, with the median near 500 lines”(從數十行到數千行不等,中位數約 500 行)(§4)。本頁涵蓋三件事:論文如何避免設定變更把一個請求分裂成兩半、今日的產品如何讓你分步驟移除一個關係,以及如何在上線前測試模型。

關係設定本身(_this、computed_userset、tuple_to_userset)的說明見關係元組與使用者集合。本頁談的是如何變更它們。

論文如何為命名空間設定建立版本

設定存放在自己的 Spanner 資料庫中:“There is one database to store relation tuples for each client namespace, one database to hold all namespace configurations, and one changelog database shared across all namespaces”(每個客戶端命名空間各有一個資料庫用來儲存關係元組,另有一個資料庫存放所有命名空間設定,以及一個由所有命名空間共用的變更日誌資料庫)(§3)。設定資料庫是一張表加上一份日誌:

因此,每個設定版本都有一個提交時間戳記,而每台伺服器都持有某個範圍的版本。危險在於會扇出的請求(見架構):如果接收請求的伺服器已經載入了新設定,而它所委派的伺服器還沒有,同一次 Check 的兩半就會在不同的規則下評估。論文排除了這種情況:“Zanzibar chooses a single snapshot timestamp for config metadata when evaluating each client request. All aclservers in a cluster use that same timestamp for the same request, including for any subrequests that fan out from the original client request”(Zanzibar 在評估每個客戶端請求時,會為設定中繼資料選擇單一的快照時間戳記。叢集中的所有 aclservers 對同一請求都使用同一個時間戳記,包括從原始客戶端請求扇出的任何子請求)(§3.2.2)。

當叢集中的伺服器載入了不同的設定版本時,一個請求可以使用哪個時間戳記?

每個請求一個設定時間戳記新的設定版本於時間戳記 T2 提交到設定儲存區。aclserver 1 從變更日誌讀取它,現在持有到 T2 為止的版本;aclserver 2 落後,仍只持有到 T1 為止的版本。兩者都向監控工作回報其範圍,監控工作回報一個結束於 T1 的全域可用範圍。一個請求抵達 aclserver 1,它在該範圍內挑選一個時間,也就是最多 T1,並以相同的設定時間戳記向 aclserver 2 送出子請求。之後 aclserver 2 載入 T2,全域範圍擴大到包含 T2。時間設定儲存區監控工作aclserver 1aclserver 2變更日誌範圍範圍扇出變更日誌設定 v2於 T2 提交載入 v2:持有 ≤ T2落後:持有 ≤ T1全域範圍結束於 T1請求:挑選≤ T1 的時間以相同時間處理子請求載入 v2:持有 ≤ T2全域範圍現在含 T2
該請求在兩台伺服器上都以 v1 評估,因為 v2 尚未在每一台伺服器上可用。

請注意,新設定並不是在提交的那一刻就被使用。它要等到叢集中的每台伺服器都能提供它時才變得可用。用論文的話來說,“each server in a cluster may have access to a different range of config timestamps due to restarts or network latency. Zanzibar must pick a timestamp that is available across all of them. To facilitate this, a monitoring job tracks the timestamp range available to every server and aggregates them, reporting a globally available range to every other server. On each incoming request the server picks a time from this range, ensuring that all servers can continue serving even if they are no longer able to read from the config storage”(由於重新啟動或網路延遲,叢集中的每台伺服器可存取的設定時間戳記範圍可能各不相同。Zanzibar 必須挑選一個在所有伺服器上都可用的時間戳記。為此,一項監控工作會追蹤每台伺服器可用的時間戳記範圍並加以彙整,再將全域可用的範圍回報給其他每一台伺服器。對於每個傳入的請求,伺服器會從此範圍中挑選一個時間,確保即使伺服器已無法從設定儲存區讀取,所有伺服器仍能繼續提供服務)(§3.2.2)。

論文就說到這裡為止。它沒有說明客戶端在移除一個關係時如何遷移元組、設定的寫入是否會與既有元組比對,也沒有說明設定時間戳記與同一請求所選的元組快照之間有什麼關係。它只說 ⟨namespace⟩ 與 ⟨relation⟩ “are predefined in client configurations”(預先定義於客戶端設定中)(§2.1),以及關係是每一筆元組主鍵的一部分(§2.1、§3.1.1)。本頁其餘部分談的是開源系統如何處理這個缺口。

兩個產品中的 schema 版本

文件最完整的兩個產品做了不同的選擇。

  • SpiceDB 每個部署只有一份目前的 schema,以 WriteSchema 替換。AuthZed 的文件說 SpiceDB “processes all calls to the WriteSchema in a safe manner: it is not possible to break the type safety of a schema”(以安全的方式處理所有 WriteSchema 呼叫:不可能破壞 schema 的型別安全),這表示 “it is not possible to accidentally remove a relation that is still referenced by one or more relationships”(不可能意外移除仍被一筆或多筆 relationship 參照的關係)(migrating a schema)。AuthZed 2022 年的一篇文章補充,schema 寫入是完全一致的,因此在 schema 寫入之後的 relationship 寫入會在新 schema 下評估(online schema migrations)。
  • OpenFGA 保留每一個版本。“Authorization Models in OpenFGA are immutable, they are created once and then can no longer be deleted or modified. Each time you write an authorization model, a new version is created.”(OpenFGA 中的授權模型是不可變的,建立一次之後就無法再刪除或修改。每次寫入授權模型,都會建立一個新版本。)請求可以指名一個 authorization_model_id;若沒有,“OpenFGA will use the last created Authorization Model for that store”(OpenFGA 會使用該 store 最後建立的授權模型)(immutable models)。文件建議在設定中固定該 ID,這也讓你能在切換之前,對新模型進行影子檢查。

論文的設計介於兩者之間:以提交時間戳記為鍵的變更日誌,類似 OpenFGA 的版本歷史;但伺服器一律移往最新版本,類似 SpiceDB。各產品的更多資訊:SpiceDB、OpenFGA。

移除一個關係需要三個步驟

新增很容易。在 SpiceDB 中,“Adding a new relation to a definition is always allowed, as it cannot change any existing types or computation”(在 definition 中新增 relation 一律允許,因為它無法改變任何既有的型別或計算),而變更權限的計算方式也是允許的,只要它參照的是已定義的關係或權限(migrating a schema)。

移除則不然。同一頁面寫道:“For type safety reasons, any removal of a relation with data, or a relation or permission referenced by another relation or permission is disallowed.”(基於型別安全,不允許移除任何帶有資料的 relation,或被另一個 relation 或 permission 參照的 relation 或 permission。)一個關係只有在其元組都消失之後才能移除,而其元組只有在沒有任何東西再以它們計算存取權之後,才能安全地移除。因此移除有先後順序。

以貫穿全站範例中的 doc 為例,加上一個團隊想要拿掉的假設性額外關係 editor。以 SpiceDB 的 schema 語言,起始狀態如下:

definition doc {
  relation parent: folder
  relation owner: user
  relation editor: user
  relation viewer: user | group#member
  permission view = owner + editor + viewer + parent->view
}

每一步改變了什麼,為什麼任何一步都不能省略?

起始doc 上的權限 view 指向四個關係:owner、editor、viewer 與 parent。editor 關係存有 relationship,畫成其下方的一個儲存方框。permission viewownereditorviewerparenteditor tuples
起始:view 讀取 editor,而 editor 存有資料。
步驟 1:停止參照 editor重新寫入 schema,讓 view 只由 owner、viewer 與 parent 計算。editor 關係仍然存在,也仍存有 relationship,但沒有任何東西讀取它。permission viewownereditorviewerparenteditor tuples
步驟 1(WriteSchema):editor 此時就失去經由 view 的存取權。
步驟 2:刪除 editor 元組一次 DeleteRelationships 呼叫移除 editor 關係的所有 relationship。該關係仍在 schema 中宣告,但已為空且未被參照。permission viewownereditorviewerparentno tuples
步驟 2(DeleteRelationships):該關係已為空。
步驟 3:拿掉該關係第三次寫入 schema,不含 editor 關係。view 讀取 owner、viewer 與 parent。permission viewownerviewerparent
步驟 3(WriteSchema):editor 已不存在。

請注意存取權實際改變的位置:在步驟 1,而不是步驟 3。一旦權限不再讀取 editor,不同時是擁有者或檢視者的編輯者就會被拒絕,而此時元組仍在磁碟上。這就是應該停下來觀察的時間點。AuthZed 的文章(其步驟編號不同)在刪除任何資料之前的這個狀態下說:“You can stay at step 2 for as long as desired, in production, to retain your ability to roll back the change”(你可以在正式環境中停留在步驟 2 任意長的時間,以保留復原這項變更的能力)(online schema migrations):復原步驟 1 只是一次 schema 寫入,而復原步驟 2 則意味著要還原元組。這三個步驟出自 AuthZed 的遷移文件,該文件也描述了從關係中移除一種允許之主體型別的相同模式(先刪除那些 relationship,再編輯 schema)。

重新命名一個關係,就是一次移除加上一次新增。SpiceDB 的文件逐步說明了做法:新增新的關係並將它納入權限,讓應用程式同時寫入兩者,回填資料,將舊關係從權限中移除,停止寫入它,再以上述三個步驟將它移除(migrating a schema)。OpenFGA 處理同樣工作的方式則依賴不可變的模型:寫入新模型(一個正式環境尚未使用的新 ID)、更新應用程式、將元組複製到新的關係名稱,然後部署指向新模型 ID 的應用程式(immutable models)。

以斷言檔測試模型

兩個產品都會讀取一個 YAML 檔案,其中存放模型、一些元組,以及你預期的答案。下面的範例編碼了貫穿全站的範例(Anne 擁有 readme;Beto 屬於 eng;eng 的成員可檢視 readme;Chen 可檢視資料夾 A)。它們依照各產品文件中的格式撰寫,但是為本頁而寫,尚未實際執行。

OpenFGA:.fga.yaml

.fga.yaml 檔案有一個 model(或 model_file)、選擇性的 tuples,以及 tests;一個測試可以包含 check、list_objects 與 list_users 區塊,每一個都帶有 assertions(testing models)。

name: Running example
model: |
  model
    schema 1.1

  type user

  type group
    relations
      define member: [user]

  type folder
    relations
      define viewer: [user]

  type doc
    relations
      define parent: [folder]
      define owner: [user]
      define viewer: [user, group#member] or owner or viewer from parent

tuples:
  - user: user:anne
    relation: owner
    object: doc:readme
  - user: user:beto
    relation: member
    object: group:eng
  - user: group:eng#member
    relation: viewer
    object: doc:readme
  - user: folder:A
    relation: parent
    object: doc:readme
  - user: user:chen
    relation: viewer
    object: folder:A

tests:
  - name: readme access
    check:
      - user: user:anne
        object: doc:readme
        assertions:
          owner: true
          viewer: true
      - user: user:chen
        object: doc:readme
        assertions:
          owner: false
          viewer: true
    list_objects:
      - user: user:beto
        type: doc
        assertions:
          viewer:
            - doc:readme

OpenFGA CLI 以 fga model test --tests <filename>.fga.yaml 執行它,並為每一種測試印出通過數(testing models)。

SpiceDB:驗證檔

SpiceDB 的驗證檔有一個 schema(或 schemaFile)、以單一多行字串(而非 YAML 清單)表示的 relationships、帶有 assertTrue 與 assertFalse 的 assertions,以及選擇性的 validation 區塊,其中是預期關係,列出每一個具有存取權的主體及其取得方式(validation, testing, debugging)。

schema: |-
  definition user {}

  definition group {
    relation member: user
  }

  definition folder {
    relation viewer: user
    permission view = viewer
  }

  definition doc {
    relation parent: folder
    relation owner: user
    relation viewer: user | group#member
    permission view = owner + viewer + parent->view
  }

relationships: |-
  doc:readme#owner@user:anne
  group:eng#member@user:beto
  doc:readme#viewer@group:eng#member
  doc:readme#parent@folder:A
  folder:A#viewer@user:chen

assertions:
  assertTrue:
    - doc:readme#view@user:anne
    - doc:readme#view@user:beto
    - doc:readme#view@user:chen
  assertFalse:
    - doc:readme#owner@user:chen

zed validate 以 “using the same parsing logic that the SpiceDB binary uses”(與 SpiceDB 執行檔相同的剖析邏輯)執行它,而自 zed v0.25.0 起可以一次處理多個檔案(zed validate validations/*)(validation, testing, debugging)。本頁省略了 validation 區塊,因為未查核它對群組使用者集合的確切輸出;文件展示的形式是 "[user:you] is <document:validation-testing-debugging#reader>"。

兩種檔案測試的都是模型,所針對的是你自己編造的元組。它們是 schema 的單元測試,而不是對正式環境資料的檢查。

在 CI 中執行

從 pull request 到正式環境之間,每一種檢查應該放在哪裡?

交付管線中的 schema 測試一個含有 schema 變更及其測試檔的 pull request 送到 CI,CI 以測試檔中的元組執行 zed validate 或 fga model test。若通過,部署步驟以 WriteSchema 或 WriteAuthorizationModel 將 schema 寫入執行中的服務,由服務存入其資料儲存區。對 OpenFGA 而言,新的模型 ID 接著會被固定在應用程式的設定中。部署步驟旁的一則註記說明,依賴資料的步驟(例如在移除關係之前刪除元組)不在 CI 測試的涵蓋範圍內。pull request:schema + 測試CI:zed validate /fga model test部署:WriteSchema /WriteAuthorizationModel授權資料儲存區應用程式設定:固定的模型 ID(OpenFGA)未涵蓋:既有元組push 時測試通過
CI 以測試元組檢查模型。寫入能否在實際資料上成功,要到部署時才知道。

請注意左邊的註記。AuthZed 直接指出:“a schema write can still fail if a relation is removed and there are still instances of that relation in your database. zed doesn’t know about your data”(若移除了一個關係,而你的資料庫中仍有該關係的實例,schema 寫入仍可能失敗。zed 不知道你的資料)(validation, testing, debugging)。上述的三步驟移除是一套部署程序,不是測試檔能夠證明的東西。

兩個專案都發布了 GitHub Actions。對 SpiceDB,authzed/action-spicedb-validate 對一個檔案執行 zed 的驗證;AuthZed 稱它 “highly recommended because it can prevent deployments of unverified changes”(強烈建議使用,因為它能防止部署未經驗證的變更)(docs)。對 OpenFGA,openfga/action-openfga-test 安裝 CLI,並對 test_path 底下每一個符合 *.fga.yaml 的檔案執行 fga model test(action.yml)。同時使用兩者的最小 workflow:

name: Authorization model
on:
  pull_request:
    paths: ["authz/**"]

jobs:
  spicedb:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: authzed/action-spicedb-validate@v1
        with:
          validationfile: authz/spicedb.yaml

  openfga:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: openfga/action-openfga-test@v0.1.1
        with:
          test_path: authz/

對於較大的變更,SpiceDB 也提供一個整合測試伺服器(spicedb serve-testing,或 authzed/action-spicedb action),它為每個預共享金鑰提供 “an isolated, empty datastore”(一個隔離的空資料儲存區),讓應用程式測試可以平行地對同一個實例執行(docs)。OpenFGA 固定的模型 ID 則允許影子檢查:在切換之前,將同一個檢查送往舊模型與新模型並比較結果(immutable models)。

論文章節:命名空間設定 §2.3;設定儲存 §3.1.3;每個請求一個設定時間戳記 §3.2.2;命名空間數量與設定大小 §4。術語見術語表。

資料來源