doc/admin/federation.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: admin
   4 title: Configuring federation
   5 ...
   6
   7 {% comment %}
   8 Copyright (C) The Arvados Authors. All rights reserved.
   9
  10 SPDX-License-Identifier: CC-BY-SA-3.0
  11 {% endcomment %}
  12
  13 This page describes how to enable and configure federation capabilities between clusters.
  14
  15 An overview on how this feature works is discussed in the "architecture section":{{site.baseurl}}/architecture/federation.html
  16
  17 h3. API Server configuration
  18
  19 To accept users from remote clusters, some settings need to be added to the @application.yml@ file. There are two ways in which a remote cluster can be identified: either explictly by listing its prefix-to-hostname mapping, or implicitly by assuming the given remote cluster is public and belongs to the @.arvadosapi.com@ subdomain.
  20
  21 For example, if you want to set up a private cluster federation, the following configuration will only allow access to users from @clsr2@ & @clsr3@:
  22
  23 <pre>
  24 production:
  25   remote_hosts:
  26     clsr2: api.cluster2.com
  27     clsr3: api.cluster3.com
  28   remote_hosts_via_dns: false
  29   auto_activate_users_from: []
  30 </pre>
  31
  32 The additional @auto_activate_users_from@ setting can be used to allow users from the clusters in the federation to not only read but also create & update objects on the local cluster. This feature is covered in more detail in the "user activation section":{{site.baseurl}}/admin/activation.html. In the current example, only manually activated remote users would have full access to the local cluster.
  33
  34 h3. Arvados controller & keepstores configuration
  35
  36 Both @arvados-controller@ and @keepstore@ services also need to be configured, as they proxy requests to remote clusters when needed.
  37
  38 Continuing the previous example, the necessary settings should be added to the @/etc/arvados/config.yml@ file as follows:
  39
  40 <pre>
  41 Clusters:
  42   clsr1:
  43     RemoteClusters:
  44       clsr2:
  45         Host: api.cluster2.com
  46         Proxy: true
  47       clsr3:
  48         Host: api.cluster3.com
  49         Proxy: true
  50 </pre>
  51
  52 Similar settings should be added to @clsr2@ & @clsr3@ hosts, so that all clusters in the federation can talk to each other.
  53
  54 h3. Testing
  55
  56 Following the above example, let's suppose @clsr1@ is our "home cluster", that is to say, we use our @clsr1@ user account as our federated identity and both @clsr2@ and @clsr3@ remote clusters are set up to allow users from @clsr1@ and to auto-activate them. The first thing to do would be to log into a remote workbench using the local user token. This can be done following these steps:
  57
  58 1. Log into the local workbench and get the user token
  59 2. Visit the remote workbench specifying the local user token by URL: @https://workbench.cluster2.com?api_token=token_from_clsr1@
  60 3. You should now be logged into @clsr2@ with your account from @clsr1@
  61
  62 To further test the federation setup, you can create a collection on @clsr2@, uploading some files and copying its UUID. Next, logged into a shell node on your home cluster you should be able to get that collection by running:
  63
  64 <pre>
  65 user@clsr1:~$ arv collection get --uuid clsr2-xvhdp-xxxxxxxxxxxxxxx
  66 </pre>
  67
  68 The returned collection metadata should show the local user's uuid on the @owner_uuid@ field. This tests that the @arvados-controller@ service is proxying requests correctly.
  69
  70 One last test may be performed, to confirm that the @keepstore@ services also recognize remote cluster prefixes and proxy the requests. You can ask for the previously created collection using any of the usual tools, for example:
  71
  72 <pre>
  73 user@clsr1:~$ arv-get clsr2-xvhdp-xxxxxxxxxxxxxxx/uploaded_file .
  74 </pre>