Querying Other Clusters

A query on one Berserk cluster can read tables that live in another: a regional cluster, a customer's install, or a cluster run by another team. Each cluster keeps its own data and its own users. The query runs where it was issued, and the other cluster runs its share of the work on its own data and sends back partial results, never raw rows.

Two admins set this up, one on each side:

Nothing else is shared: the clusters need no common identity provider, network or secret, and the remote can be reached over the internet through its gateway like any other client.

On the remote cluster: create a site principalCopy Anchor Link

A site principal is another cluster allowed to query this one. Create one per querying cluster, and decide which databases it reads: all of them, or a list.

bzrk site-principal create acme-eu --databases logs,traces --description "Acme's EU cluster"
bzrk site-principal token create acme-eu to-acme-eu

The token is shown once. Give it to the querying cluster's admin through a channel you trust. It does not expire unless you set --expires, so treat it like any long-lived credential.

What a site principal can do is narrow:

• It reaches only the site service, which runs a share of another cluster's query. It cannot run a query of its own, list or change the catalog, or use the UI or the API.
• Each share reads one database, and only one the principal was given. A share on any other database is refused, whatever the querying cluster asks.
• Users and service accounts of this cluster cannot use the site service.

The same is in the UI under Settings → Site access.

On the querying cluster: register the remote siteCopy Anchor Link

Register the remote with its gateway's URL and the token, piped in so it never appears in a command line or shell history:

bzrk remote-site add acme-eu --url https://berserk.acme.example --cluster-function no < token.txt

--cluster-function has no default. It decides how users reach the remote:

• no: users reach the remote only through remote tables you map into a local database (below). You decide here exactly what your users can read there.
• yes: users may also name any of the remote's tables in a query with cluster('acme-eu').database('logs').Table, within what the remote's site principal allows.

Map remote tables into a local database under a local name:

bzrk remote-site table map acme-eu --local-database default --local-name AcmeLogs \
  --remote-database logs --remote-table Logs

Users of default then query AcmeLogs as if it were a table of their own, alone or with local tables:

union Logs, AcmeLogs
| where severity == "ERROR"
| summarize errors = count() by bin(timestamp, 5m)

A local table of the same name always wins over a mapped one.

The same is in the UI under Settings → Remote sites.

What each side seesCopy Anchor Link

• The remote authorizes every share on its own: the site principal, and the databases it was given. It records the querying cluster's user with each share, as that cluster states it, for its logs. It never checks that user against anything of its own.
• The querying cluster records the query as it records any other, with the user who ran it.

Rotating and revokingCopy Anchor Link

On the remote cluster:

• Rotate a token: create a new one, have the querying cluster's admin replace it with bzrk remote-site set-token acme-eu < new-token.txt, then revoke the old one with bzrk site-principal token revoke <token-id>.
• Narrow or widen access: bzrk site-principal set-databases acme-eu logs takes effect on the next share.
• Cut a cluster off: bzrk site-principal disable acme-eu, or delete it. Its tokens stop working at once.

On the querying cluster, bzrk remote-site update acme-eu --disable stops every query from reaching the remote, and bzrk remote-site remove acme-eu removes it and its mapped tables.

When a query failsCopy Anchor Link