Arvados

h1. Routing multi cluster requests

h2. Concept

The goal of federation is to present an interface that fuses multiple clusters into a single view.

The role of arvados-controller is to determine which cluster(s) a request should go.

h2. Examples

My "home cluster" is qr1hi.  I have a token qr1hi-secretsecretsecret.

h3. I want to read a collection on c97qk using the Python SDK.

<pre>

c = CollectionReader("c97qk-...")

</pre>

# The CollectionReader sends a request to arvados-controller.

# arvados-controller examines the prefix c97qk and contacts c97qk.arvadosapi.com.

# The request router uses the "salted" token hmac(c97qk, qr1hi-secretsecretsecret) → qr1hi-secretsecretc97qk

# c97qk gets the token and notices the qr1hi prefix.

# c97qk contacts qr1hi to determine if the token is valid and what user is associated with the token.

# c97qk caches the token and sets current_user.  The request proceeds as normal.

# The response is returned to arvados-controller

# The manifest_text needs is updated by arvados-controller to transform the block signatures from "+A..." to "+Rc97qk-..." to indicate the signatures are valid for c97qk

# The response is returned to CollectionReader.

# The CollectionReader sends a block read request to a qr1hi keepstore with the +Rc97qk signature

# The keepstore recognizes that it is a remote signature and contacts the remote cluster to fetch the block.  The signature is transformed from a remote signature back to a regular one.

# The block is returned to the client.

h3. I want to search for a collection across clusters

<pre>

c = router.collections().list(filters=[["name", "like", "sample-1234%"]]).execute()

</pre>

# arvados-controller has a "search list" of clusters (where does this come from??? maybe an attribute of the primary user account  on qr1hi?)

# arvados-controller sends the request to each cluster in parallel using federated identity / salted token described above.

# arvados-controller gathers the results.

# arvados-controller collates the results (will need to understand "order" option to do this properly)

# Collated results are returned

# Paging - ???  likely need to keep track of some state locally to be able to be able to issue correct follow-up requests to each cluster.  Can have consistent ordering within a page but not across pages unless all pages are fetched first.

Another case: I want to list the contents of a project across clusters.  Same query process.

<pre>

c = router.collections().list(owner_uuid="qr1hi-....").execute()

</pre>

h3. I want to create a collection on another cluster.

Provide "owner_uuid" of a project or group on a foreign cluster.

<pre>

router.collections().create(body={"owner_uuid": "c97qk-...."}).execute()

</pre>

# arvados-controller examines the prefix c97qk and contacts c97qk.arvadosapi.com using federated identity / salted token described above .

# The cluster determines if the user has write access to the group or project and validates the create request as normal.

# The newly created record is returned.

No "owner_uuid" means creating the object on the "home" cluster.

h3. I want to update an object on another cluster.

<pre>

router.collections().update(uuid="c97qk-....", body={....}).execute()

</pre>

# arvados-controller examines the prefix c97qk and contacts c97qk.arvadosapi.com using federated identity / salted token described above .

# The cluster determines if the user has write access to object and validates the update request as normal.

# The updated record is returned.

h3. I want to change the ownership of a remote object to a project on my home cluster.

The object is located on c97qk and currently owned by me, I'd like to make it owned by a project qr1hi-...

# Route an "update" request to change "owner_uuid" to c97qk as described above.

# c97qk contacts qr1hi and asks if the user has write access to the project.

# The object is updated and returned to the user

(This suggests I can only share things with groups on the same home cluster as me.  hmm.)

h3. I want to change the ownership of an object on my home cluster object to a project on a remote cluster.

# Route the "update" as described above to qr1hi.

# qr1hi contacts c97qk _using the c97qk salted token_ and asks if the user has write access to the project.

# The object is updated and returned to the user

h3. I want to change the ownership of an object from one remote project (c97qk) to another (4xphq).

Can't be done directly (???) because c97qk and 4xphq don't talk to each other directly.  (The token given to c97qk is not valid for accessing 4xphq and likewise).  Could be done as a two-step process where ownership is assigned from c97qk to qr1hi, then from qr1hi to 4xphq.