Tuples
Tenant-aware relationship authorization service for Data resources.
Component Category
Data authorization
Component Description
Tuples is the Data service that exposes relationship-based authorization backed by OpenFGA. Its model covers users, nested groups, spaces with a governing group, buckets, datasets, and tables with owner, editor, contributor, viewer, and discoverer relationships. Buckets and datasets have a parent space, and tables have a parent dataset. A tenant-level data-platform object holds the auditor relation.
Why It Is Used
In BullSequana AI, Tuples gives Data services a tenant-aware authorization boundary for shared resources. Each configured tenant gets its own OpenFGA store and Keycloak service client, so relationship data does not share a store across tenants.
Learn More
Deployment notes
BullSequana AI deploys Tuples 2.0.0 as raw Kubernetes resources at sync wave 3, after OpenFGA and Keycloak. The tenants list of the Tuples component declares each tenant: its Keycloak organization, its Tuples client in the shared realm, and an optional kafka_topic. Bootstrap jobs reconcile each tenant's OpenFGA store and authorization model and create the corresponding Keycloak client credentials. An init container injects the live store IDs and client secrets into runtime configuration. Tuples authenticates to OpenFGA with its own pre-shared key.
When network policies are enabled, which is the default, and the cluster enforces them, the Tuples API on port 8080 accepts in-cluster traffic only from the BSQAI API and the Kubeflow profile bucket provisioner. Tuples has no public route. A client outside that list, such as a Developer Workspace notebook, needs an operator-added NetworkPolicy before it can call the API.
The BSQAI API manages the Tuples roles of tenant administrators. When a user becomes a tenant administrator through the Portal or the BSQAI API, the BSQAI API assigns them the tuples-writer and tuples-reader client roles on the tenant's Tuples client. When tenant administration is revoked, it removes both roles before it removes the group membership. The Tuples bootstrap job records each tenant's Tuples client in the bsqai.tuples.client-id attribute of the tenant's Keycloak organization, which is how the BSQAI API finds the client. Bootstrap jobs grant these roles only to the tenant's own service account and revoke none, so assignments made at runtime persist across GitOps re-syncs.
Tuples emits an audit event for every request it handles. A tenant with kafka_topic configured in its tenant entry gets its own dedicated Kafka topic and producer identity for these events; a tenant without kafka_topic only logs write events through the platform's standard logging path. A subject holding both the auditor authorization relation and the tuples-auditor Keycloak client role can also mint a per-subject Kafka credential scoped to their own tenant's audit topic, and consume it directly without going through Tuples' API. See Authorization Events Audit for the full setup.
The data-platform roles endpoint (POST and DELETE /api/v1/data-platform/roles) also accepts the admin relation for user subjects (user:<email>) in the caller's tenant. Tuples doesn't write an OpenFGA tuple for admin. It assigns the user the create and modify privileges on the tenant's Lakekeeper project directly, so /check endpoints don't accept admin. Tuples rejects a user outside the tenant with 400 and answers 503 when the tenant has no metastore project. The BSQAI API uses this path when a tenant administrator assigns or revokes the data_admin functional role, or removes a member who holds it. It first checks that the caller administers the tenant, directly or through inheritance. It then calls Tuples with a token of the tenant's own Tuples client, not the caller's token, and reads that client's secret through its Keycloak administration client. Tuples therefore records the tenant's Tuples service account as the actor of these changes, and the BSQAI API writes an audit log line that names the acting user. See Access roles.
Interacts With
OpenFGA, which stores each tenant's authorization model and relationship tuples.Lakekeeper, which receives project-levelcreateandmodifyassignments for users granted theadminrelation.Keycloak, which issues tenant-aware service tokens and holds thetuples-auditorclient role used to gate direct Kafka audit access.Kafka, which receives each tenant's audit events on its dedicated topic and issues per-subject SCRAM credentials for direct audit consumption.Kubeflow, whose profile bucket provisioner queries a user's space memberships and writes bucket ownership and parent-space relationships through the Tuples API.BSQAI API, which manages the Tuples roles of tenant administrators and thedata_adminassignment, and reads discoverable tables and grants for the data catalog.- Data services, which enforce access to spaces, buckets, and other governed resources.