guide:schema-changes@ko

가이드

스키마 변경과 테스트

논문이 요청 하나 안에서 네임스페이스 설정 변경을 일관되게 유지하는 방법, 오늘날의 제품에서 관계 하나를 제거하는 데 세 단계가 걸리는 이유, 그리고 CI에서 단언 파일로 모델을 테스트하는 방법.

사실 확인일 논문 관련 절 §2.1, §2.3, §3.1.3, §3.2.2, §4

스키마는 인가 시스템에서 가장 드물게 바뀌지만, 바뀌면 가장 많이 망가지는 부분이다. 논문에서 이는 네임스페이스 설정이다. “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에 도착하면, aclserver 1은 그 범위 안의 시점, 즉 최대 T1을 고르고 같은 설정 타임스탬프로 aclserver 2에 하위 요청을 보낸다. 나중에 aclserver 2가 T2를 로드하면 전역 범위가 T2를 포함하도록 늘어난다.시간설정 저장소모니터링 작업aclserver 1aclserver 2변경 로그범위범위팬아웃변경 로그설정 v2T2에 커밋v2 로드:≤ T2 보유뒤처짐:≤ T1 보유전역 범위는T1에서 끝남요청: ≤ T1인시점 선택같은 시점의하위 요청v2 로드:≤ T2 보유전역 범위에이제 T2 포함
v2가 아직 모든 서버에서 사용 가능하지 않으므로, 요청은 두 서버 모두에서 v1으로 평가된다.

새 설정은 커밋되는 순간 쓰이지 않는다는 점에 주목하라. 클러스터의 모든 서버가 그것을 제공할 수 있을 때 쓸 수 있게 된다. 논문의 표현으로 “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)만 말한다. 이 페이지의 나머지는 오픈 소스 시스템들이 그 공백을 어떻게 다루는지에 관한 것이다.

두 제품의 스키마 버전

가장 문서화가 잘 된 두 제품은 서로 다른 선택을 했다.

  • SpiceDB는 배포마다 현재 스키마가 하나 있으며 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에 대한 모든 호출을 안전한 방식으로 처리한다. 스키마의 타입 안전성을 깨뜨리는 것은 불가능하다)라고 하며, 이는 “it is not possible to accidentally remove a relation that is still referenced by one or more relationships”(하나 이상의 관계가 여전히 참조하는 관계를 실수로 제거할 수 없다)는 뜻이다(migrating a schema). 2022년 AuthZed 글은 스키마 쓰기가 완전히 일관되므로, 스키마 쓰기 이후의 관계 쓰기는 새 스키마로 평가된다고 덧붙인다(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는 그 스토어에서 마지막으로 생성된 인가 모델을 쓴다)(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의 스키마 언어로는 다음과 같이 시작한다.

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 관계에는 저장된 관계가 있으며, 그 아래 저장소 상자로 그렸다.permission viewownereditorviewerparenteditor 튜플
시작: view가 editor를 읽고, editor에는 데이터가 있다.
1단계: editor 참조 중단스키마를 다시 써서 view를 owner, viewer, parent만으로 계산한다. editor 관계는 여전히 존재하고 여전히 관계를 가지고 있지만, 아무것도 그것을 읽지 않는다.permission viewownereditorviewerparenteditor 튜플
1단계(WriteSchema): 이제 편집자는 view를 통한 접근을 잃는다.
2단계: editor 튜플 삭제DeleteRelationships 호출이 editor 관계에 대한 모든 관계를 제거한다. 관계는 여전히 스키마에 선언되어 있지만 비어 있고 참조되지 않는다.permission viewownereditorviewerparent튜플 없음
2단계(DeleteRelationships): 관계가 비었다.
3단계: 관계 삭제editor 관계 없이 스키마를 세 번째로 쓴다. view는 owner, viewer, parent를 읽는다.permission viewownerviewerparent
3단계(WriteSchema): editor가 사라졌다.

접근이 실제로 바뀌는 곳은 3단계가 아니라 1단계라는 점에 주목하라. 권한이 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단계를 되돌리는 것은 스키마 쓰기이지만, 2단계를 되돌리려면 튜플을 복원해야 한다. 세 단계는 AuthZed의 마이그레이션 문서에서 왔으며, 이 문서는 관계에서 허용된 주체 타입 하나를 제거할 때도 같은 패턴(그 관계들을 먼저 삭제하고 그다음 스키마를 고친다)을 기술한다.

관계 이름 바꾸기는 제거와 추가를 합친 것이다. 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, 그리고 접근 권한을 가진 모든 주체와 그 경로를 나열하는 기대 관계(expected relations)의 선택적인 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>" 형태를 보여 준다.

두 파일 모두 여러분이 만들어 낸 튜플에 대해 모델을 테스트한다. 스키마에 대한 단위 테스트이지 프로덕션 데이터에 대한 검사가 아니다.

CI에서 실행하기

각 종류의 검사는 풀 리퀘스트와 프로덕션 사이의 어디에 속하는가?

배포 파이프라인 안의 스키마 테스트스키마 변경과 그 테스트 파일을 담은 풀 리퀘스트가 CI로 가고, CI는 테스트 파일의 튜플에 대해 zed validate나 fga model test를 실행한다. 통과하면 배포 단계가 WriteSchema나 WriteAuthorizationModel로 실행 중인 서비스에 스키마를 쓰고, 서비스는 이를 데이터 저장소에 저장한다. OpenFGA에서는 그다음 새 모델 ID를 애플리케이션 설정에 고정한다. 배포 단계 옆의 메모는 관계를 제거하기 전에 튜플을 삭제하는 것 같은 데이터 의존 단계는 CI 테스트가 다루지 않는다고 말한다.풀 리퀘스트:스키마 + 테스트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”(관계를 제거했는데 데이터베이스에 그 관계의 인스턴스가 아직 있으면 스키마 쓰기는 여전히 실패할 수 있다. 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). 둘을 모두 쓰는 최소 워크플로는 다음과 같다.

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 액션)도 제공하며, 이 서버는 사전 공유 키마다 “an isolated, empty datastore”(격리된 빈 데이터 저장소)를 주므로 애플리케이션 테스트를 한 인스턴스에 대해 병렬로 실행할 수 있다(docs). OpenFGA의 고정된 모델 ID는 섀도 검사를 가능하게 한다. 전환하기 전에 같은 검사를 옛 모델과 새 모델에 보내 비교하는 것이다(immutable models).

논문의 절: 네임스페이스 설정 §2.3, 설정 저장소 §3.1.3, 요청마다 설정 타임스탬프 하나 §3.2.2, 네임스페이스 수와 설정 크기 §4. 용어는 용어집에 있다.

출처