guide:schema-changes@de

Leitfäden

Ein Schema ändern und testen

Wie das Paper Änderungen an Namespace-Konfigurationen innerhalb einer Anfrage konsistent hält, warum das Entfernen einer Relation in heutigen Produkten drei Schritte braucht und wie man ein Modell mit Assertion-Dateien in der CI testet.

Fakten geprüft am Abschnitte im Paper §2.1, §2.3, §3.1.3, §3.2.2, §4

Ein Schema ist der Teil eines Autorisierungssystems, der sich am seltensten ändert und bei einer Änderung am meisten kaputtmacht. Im Paper ist es die Namespace-Konfiguration: “A namespace configuration specifies its relations as well as its storage parameters” (§2.3) (Eine Namespace-Konfiguration spezifiziert ihre Relationen sowie ihre Speicherparameter). Bei Google gab es “more than 1,500 namespaces” (mehr als 1.500 Namespaces), und ihre Konfigurationsdateien “range from tens of lines to thousands of lines, with the median near 500 lines” (§4) (reichen von Dutzenden bis zu Tausenden von Zeilen, mit einem Median von etwa 500 Zeilen). Diese Seite behandelt drei Dinge: wie das Paper verhindert, dass eine Konfigurationsänderung eine Anfrage in zwei Hälften teilt, wie heutige Produkte Sie eine Relation schrittweise entfernen lassen und wie man ein Modell testet, bevor es ausgeliefert wird.

Die Relationskonfigurationen selbst (_this, computed_userset, tuple_to_userset) werden unter Relationstupel und Usersets erklärt. Auf dieser Seite geht es darum, sie zu ändern.

Wie das Paper Namespace-Konfigurationen versioniert

Konfigurationen liegen in einer eigenen Spanner-Datenbank: “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) (Es gibt eine Datenbank für die Relationstupel jedes Client-Namespace, eine Datenbank für alle Namespace-Konfigurationen und eine Changelog-Datenbank, die alle Namespaces teilen). Die Konfigurationsdatenbank ist eine Tabelle plus ein Log:

Jede Konfigurationsversion hat also einen Commit-Zeitstempel, und jeder Server hält einen gewissen Bereich von Versionen. Die Gefahr ist eine Anfrage, die sich auffächert (siehe Architektur): Hat der Server, der sie empfängt, bereits eine neue Konfiguration geladen und der Server, an den er delegiert, noch nicht, würden die beiden Hälften eines Checks unter unterschiedlichen Regeln ausgewertet. Das Paper schließt das aus: “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” (§3.2.2) (Zanzibar wählt bei der Auswertung jeder Client-Anfrage einen einzigen Snapshot-Zeitstempel für die Konfigurationsmetadaten. Alle aclservers in einem Cluster verwenden für dieselbe Anfrage denselben Zeitstempel, einschließlich aller Teilanfragen, die sich aus der ursprünglichen Client-Anfrage auffächern).

Welchen Zeitstempel kann eine Anfrage verwenden, wenn die Server in einem Cluster unterschiedliche Konfigurationsversionen geladen haben?

Ein Konfigurationszeitstempel pro AnfrageEine neue Konfigurationsversion wird zum Zeitstempel T2 im Konfigurationsspeicher committet. aclserver 1 liest sie aus dem Changelog und hält nun Versionen bis T2; aclserver 2 hinkt hinterher und hält noch Versionen bis T1. Beide melden ihre Bereiche an den Überwachungsjob, der einen global verfügbaren Bereich meldet, der bei T1 endet. Eine Anfrage trifft bei aclserver 1 ein, der eine Zeit innerhalb dieses Bereichs wählt, also höchstens T1, und eine Teilanfrage mit demselben Konfigurationszeitstempel an aclserver 2 sendet. Später lädt aclserver 2 T2, und der globale Bereich wächst und umfasst T2.ZeitKonfigurationsspeicherÜberwachungsjobaclserver 1aclserver 2ChangelogBereicheBereichAuffächerungChangelogKonfig v2committet bei T2lädt v2:hält ≤ T2hinkt:hält ≤ T1globaler Bereichendet bei T1Anfrage: wählteine Zeit ≤ T1Teilanfrage zurselben Zeitlädt v2:hält ≤ T2globaler Bereichenthält nun T2
Die Anfrage wird auf beiden Servern unter v1 ausgewertet, weil v2 noch nicht auf jedem Server verfügbar ist.

Die neue Konfiguration wird nicht in dem Moment verwendet, in dem sie committet wird. Sie wird verwendbar, wenn jeder Server im Cluster sie bedienen kann. In den Worten des Papers: “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” (§3.2.2) (jeder Server in einem Cluster kann aufgrund von Neustarts oder Netzwerklatenz Zugriff auf einen anderen Bereich von Konfigurationszeitstempeln haben. Zanzibar muss einen Zeitstempel wählen, der auf allen verfügbar ist. Dazu verfolgt ein Überwachungsjob den für jeden Server verfügbaren Zeitstempelbereich, aggregiert diese und meldet jedem anderen Server einen global verfügbaren Bereich. Bei jeder eingehenden Anfrage wählt der Server eine Zeit aus diesem Bereich, wodurch sichergestellt ist, dass alle Server weiter bedienen können, auch wenn sie nicht mehr aus dem Konfigurationsspeicher lesen können).

Das Paper hört hier auf. Es sagt nicht, wie ein Client Tupel migriert, wenn er eine Relation entfernt, ob ein Konfigurations-Schreibvorgang gegen bestehende Tupel geprüft wird oder wie sich der Konfigurationszeitstempel zum Tupel-Snapshot verhält, der für dieselbe Anfrage gewählt wird. Es sagt nur, dass ⟨namespace⟩ und ⟨relation⟩ “are predefined in client configurations” (§2.1) (in Client-Konfigurationen vordefiniert sind) und dass eine Relation Teil des Primärschlüssels jedes Tupels ist (§2.1, §3.1.1). Der Rest dieser Seite handelt davon, wie die Open-Source-Systeme mit dieser Lücke umgehen.

Schemaversionen in zwei Produkten

Die beiden am besten dokumentierten Produkte haben unterschiedlich entschieden.

  • SpiceDB hat ein aktuelles Schema pro Installation, das mit WriteSchema ersetzt wird. Die Dokumentation von AuthZed sagt, SpiceDB “processes all calls to the WriteSchema in a safe manner: it is not possible to break the type safety of a schema” (verarbeitet alle Aufrufe von WriteSchema auf sichere Weise: Es ist nicht möglich, die Typsicherheit eines Schemas zu brechen), was bedeutet: “it is not possible to accidentally remove a relation that is still referenced by one or more relationships” (es ist nicht möglich, versehentlich eine Relation zu entfernen, auf die noch eine oder mehrere Beziehungen verweisen) (Migrating a Schema). Ein Beitrag von AuthZed aus dem Jahr 2022 ergänzt, dass Schema-Schreibvorgänge vollständig konsistent sind, sodass Beziehungs-Schreibvorgänge nach einem Schema-Schreibvorgang unter dem neuen Schema ausgewertet werden (Online Schema Migrations).
  • OpenFGA behält jede Version. “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.” (Autorisierungsmodelle in OpenFGA sind unveränderlich; sie werden einmal angelegt und können danach weder gelöscht noch geändert werden. Jedes Mal, wenn Sie ein Autorisierungsmodell schreiben, wird eine neue Version angelegt.) Anfragen können eine authorization_model_id nennen; ohne sie “OpenFGA will use the last created Authorization Model for that store” (verwendet OpenFGA das zuletzt angelegte Autorisierungsmodell dieses Stores) (Immutable Models). Die Dokumentation empfiehlt, die ID in der Konfiguration festzulegen, was auch Schattenprüfungen gegen ein neues Modell vor dem Umschalten erlaubt.

Das Design des Papers liegt zwischen den beiden: ein Changelog mit Commit-Zeitstempeln als Schlüssel wie die Versionshistorie von OpenFGA, aber mit Servern, die immer zur neuesten Version wechseln, wie SpiceDB. Mehr zu jedem Produkt: SpiceDB, OpenFGA.

Eine Relation zu entfernen braucht drei Schritte

Hinzufügen ist einfach. In SpiceDB gilt: “Adding a new relation to a definition is always allowed, as it cannot change any existing types or computation” (Eine neue relation zu einer definition hinzuzufügen ist immer erlaubt, da es keine bestehenden Typen oder Berechnungen ändern kann), und eine Änderung daran, wie eine Berechtigung berechnet wird, ist erlaubt, solange sie auf definierte Relationen oder Berechtigungen verweist (Migrating a Schema).

Entfernen ist es nicht. Dieselbe Seite: “For type safety reasons, any removal of a relation with data, or a relation or permission referenced by another relation or permission is disallowed.” (Aus Gründen der Typsicherheit ist jedes Entfernen einer relation mit Daten oder einer relation oder permission, auf die eine andere relation oder permission verweist, verboten.) Eine Relation kann erst entfernt werden, wenn ihre Tupel weg sind, und ihre Tupel können erst gefahrlos gelöscht werden, wenn nichts mehr Zugriff aus ihnen berechnet. Das Entfernen hat also eine Reihenfolge.

Nehmen Sie das doc des durchgehenden Beispiels mit einer hypothetischen zusätzlichen Relation editor, die das Team entfernen will. In der Schemasprache von SpiceDB beginnt es so:

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

Was ändert jeder Schritt, und warum kann keiner übersprungen werden?

AusgangslageDie Berechtigung view auf doc zeigt auf vier Relationen: owner, editor, viewer und parent. Die Relation editor hat gespeicherte Beziehungen, gezeichnet als Speicherkasten darunter.permission viewownereditorviewerparenteditor-Tupel
Ausgangslage: view liest editor, und editor enthält Daten.
Schritt 1: nicht mehr auf editor verweisenDas Schema wird neu geschrieben, mit view nur noch aus owner, viewer und parent berechnet. Die Relation editor existiert noch und enthält noch Beziehungen, aber nichts liest sie.permission viewownereditorviewerparenteditor-Tupel
Schritt 1 (WriteSchema): Bearbeiter verlieren jetzt den Zugriff über view.
Schritt 2: die editor-Tupel löschenEin Aufruf von DeleteRelationships entfernt jede Beziehung der Relation editor. Die Relation ist im Schema noch deklariert, aber leer und ohne Verweis.permission viewownereditorviewerparentkeine Tupel
Schritt 2 (DeleteRelationships): Die Relation ist leer.
Schritt 3: die Relation entfernenDas Schema wird ein drittes Mal geschrieben, ohne die Relation editor. view liest owner, viewer und parent.permission viewownerviewerparent
Schritt 3 (WriteSchema): editor ist weg.

Beachten Sie, wo sich der Zugriff tatsächlich ändert: in Schritt 1, nicht in Schritt 3. Sobald die Berechtigung editor nicht mehr liest, wird ein Bearbeiter, der nicht auch Eigentümer oder Betrachter ist, abgewiesen, während die Tupel noch auf der Platte liegen. Das ist der Punkt, an dem man anhalten und beobachten sollte. Der Beitrag von AuthZed, der seine Schritte anders nummeriert, sagt über diesen Zustand, bevor Daten gelöscht werden: “You can stay at step 2 for as long as desired, in production, to retain your ability to roll back the change” (Sie können in der Produktion so lange wie gewünscht bei Schritt 2 bleiben, um die Möglichkeit zu behalten, die Änderung zurückzunehmen) (Online Schema Migrations): Schritt 1 zurückzunehmen ist ein Schema-Schreibvorgang, während Schritt 2 zurückzunehmen bedeutet, Tupel wiederherzustellen. Die drei Schritte stammen aus der Migrationsdokumentation von AuthZed, die dasselbe Muster auch für das Entfernen eines erlaubten Subjekttyps aus einer Relation beschreibt (zuerst diese Beziehungen löschen, dann das Schema bearbeiten).

Eine Relation umzubenennen ist ein Entfernen plus ein Hinzufügen. Die SpiceDB-Dokumentation geht es durch: die neue Relation hinzufügen und in die Berechtigung aufnehmen, die Anwendung beide schreiben lassen, Bestandsdaten nachtragen (Backfill), die alte Relation aus der Berechtigung nehmen, aufhören, sie zu schreiben, und sie dann mit den drei obigen Schritten entfernen (Migrating a Schema). Die OpenFGA-Variante derselben Aufgabe stützt sich auf unveränderliche Modelle: das neue Modell schreiben (eine neue ID, die die Produktion noch nicht verwendet), die Anwendung aktualisieren, die Tupel auf den neuen Relationsnamen kopieren und dann die Anwendung mit der neuen Modell-ID ausrollen (Immutable Models).

Ein Modell mit Assertion-Dateien testen

Beide Produkte lesen eine YAML-Datei, die ein Modell, einige Tupel und die erwarteten Antworten enthält. Die folgenden Beispiele kodieren das durchgehende Beispiel (Anne ist Eigentümerin des Readmes; Beto ist in eng; die Mitglieder von eng sehen das Readme; Chen sieht Ordner A). Sie folgen dem dokumentierten Format des jeweiligen Produkts, wurden aber für diese Seite geschrieben und nicht ausgeführt.

OpenFGA: .fga.yaml

Eine .fga.yaml-Datei hat ein model (oder model_file), optionale tuples und tests; ein Test kann Blöcke check, list_objects und list_users enthalten, jeweils mit 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

Die OpenFGA-CLI führt sie mit fga model test --tests <filename>.fga.yaml aus und gibt pro Testart eine Zahl bestandener Tests aus (Testing Models).

SpiceDB: Validierungsdateien

Eine SpiceDB-Validierungsdatei hat ein schema (oder schemaFile), relationships als einen mehrzeiligen String statt einer YAML-Liste, assertions mit assertTrue und assertFalse und einen optionalen Block validation mit erwarteten Relationen, der jedes Subjekt mit Zugriff auflistet und wie es dazu kam (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 führt sie “using the same parsing logic that the SpiceDB binary uses” (mit derselben Parsing-Logik, die das SpiceDB-Binary verwendet) aus und nimmt seit zed v0.25.0 mehrere Dateien auf einmal (zed validate validations/*) (Validation, Testing, Debugging). Diese Seite lässt den Block validation weg, weil seine genaue Ausgabe für ein Gruppen-Userset nicht geprüft wurde; die Dokumentation zeigt die Form "[user:you] is <document:validation-testing-debugging#reader>".

Beide Dateien testen das Modell, gegen Tupel, die man erfindet. Sie sind Unit-Tests für das Schema, keine Prüfung der Produktionsdaten.

Die Tests in der CI ausführen

Wo gehört jede Art von Prüfung zwischen einem Pull Request und der Produktion hin?

Schematests in einer AuslieferungspipelineEin Pull Request mit einer Schemaänderung und ihrer Testdatei geht an die CI, die zed validate oder fga model test gegen die Tupel in der Testdatei ausführt. Wenn sie bestehen, schreibt ein Deploy-Schritt das Schema mit WriteSchema oder WriteAuthorizationModel in den laufenden Dienst, der es in seinem Datenspeicher ablegt. Bei OpenFGA wird die neue Modell-ID dann in der Konfiguration der Anwendung festgelegt. Eine Notiz neben dem Deploy-Schritt sagt, dass datenabhängige Schritte, etwa das Löschen von Tupeln vor dem Entfernen einer Relation, von den CI-Tests nicht abgedeckt werden.Pull Request:Schema + TestsCI: zed validate /fga model testDeploy: WriteSchema /WriteAuthorizationModelAutorisierungs-datenspeicherApp-Konfig: festeModell-ID (OpenFGA)nicht abgedeckt:bestehende Tupelbei PushTests bestanden
Die CI prüft das Modell gegen Testtupel. Ob ein Schreibvorgang gegen echte Daten gelingt, weiß man erst beim Deploy.

Beachten Sie die Notiz links. AuthZed sagt es direkt: “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” (ein Schema-Schreibvorgang kann trotzdem fehlschlagen, wenn eine Relation entfernt wird und es in Ihrer Datenbank noch Instanzen dieser Relation gibt. zed kennt Ihre Daten nicht) (Validation, Testing, Debugging). Das dreistufige Entfernen oben ist ein Auslieferungsverfahren, nichts, was eine Testdatei beweisen kann.

Beide Projekte veröffentlichen GitHub Actions. Für SpiceDB führt authzed/action-spicedb-validate die Validierung von zed auf einer Datei aus; AuthZed nennt es “highly recommended because it can prevent deployments of unverified changes” (sehr empfehlenswert, weil es das Ausrollen ungeprüfter Änderungen verhindern kann) (Dokumentation). Für OpenFGA installiert openfga/action-openfga-test die CLI und führt fga model test auf jeder Datei aus, die unter test_path auf *.fga.yaml passt (action.yml). Ein minimaler Workflow mit beiden:

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/

Für größere Änderungen liefert SpiceDB außerdem einen Integrationstestserver (spicedb serve-testing oder die Action authzed/action-spicedb), der jedem Preshared Key “an isolated, empty datastore” (einen isolierten, leeren Datenspeicher) gibt, sodass Anwendungstests parallel gegen eine Instanz laufen können (Dokumentation). Die festgelegten Modell-IDs von OpenFGA erlauben Schattenprüfungen: dieselbe Prüfung an das alte und das neue Modell senden und vor dem Umschalten vergleichen (Immutable Models).

Abschnitte des Papers: Namespace-Konfigurationen §2.3; Konfigurationsspeicher §3.1.3; ein Konfigurationszeitstempel pro Anfrage §3.2.2; Zahl der Namespaces und Größe der Konfigurationen §4. Die Begriffe stehen im Glossar.

Quellen