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 h2. Configuration
  18
  19 To enable a cluster to communicate with other clusters, some settings need to be added to the @config.yml@ file.  Federated clusters are identified by listing the cluster-to-hostname mapping in the @RemoteClusters@ section.
  20
  21 Here is an example of the settings that should be added to the @/etc/arvados/config.yml@ file:
  22
  23 <pre>
  24 Clusters:
  25   clsr1:
  26     RemoteClusters:
  27       clsr2:
  28         Host: api.cluster2.example
  29         Proxy: true
  30         ActivateUsers: true
  31       clsr3:
  32         Host: api.cluster3.example
  33         Proxy: true
  34         ActivateUsers: false
  35 </pre>
  36
  37 Similar settings should be added to @clsr2@ & @clsr3@ hosts, so that all clusters in the federation can talk to each other.
  38
  39 The @ActivateUsers@ setting indicates whether users from a given cluster are automatically activated or they require manual activation.  User activation is covered in more detail in the "user activation section":{{site.baseurl}}/admin/user-management.html.  In the current example, users from @clsr2@ would be automatically activated but users from @clsr3@ would require an admin to activate the account.
  40
  41 Note: The @Proxy:@ variable is intended for future use, and should always be set to @true@.
  42
  43 h2(#LoginCluster). User management
  44
  45 A federation of clusters can be configured to use a separate user database per cluster, or delegate a central cluster to manage the database.
  46
  47 h3. Peer federation
  48
  49 If clusters belong to separate organizations, each cluster will have its own user database for the members of that organization.  Through federation, a user from one organization can be granted access to the cluster of another organization.  The admin of the second cluster can control access on a individual basis by choosing to activate or deactivate accounts from other organizations.
  50
  51 h3. Centralized (LoginCluster) federation
  52
  53 If all clusters belong to the same organization, and users in that organization should have access to all the clusters, user management can be simplified by setting the @LoginCluster@ which manages the user database used by all other clusters in the federation.  To do this, choose one cluster in the federation which will be the 'login cluster'.  Set the @Login.LoginCluster@ configuration value on all clusters in the federation to the cluster id of the login cluster.  After setting @LoginCluster@, restart arvados-api-server and arvados-controller.
  54
  55 <pre>
  56 Clusters:
  57   clsr2:
  58     Login:
  59       LoginCluster: clsr1
  60 </pre>
  61
  62 The @LoginCluster@ configuration redirects all user logins to the LoginCluster, and the LoginCluster will issue API tokens which will be accepted by the federation.  Users are activated or deactivated across the entire federation based on their status on the login cluster.
  63
  64 Note: tokens issued by the login cluster need to be periodically re-validated when used on other clusters in the federation.  The period between revalidation attempts is configured with @Login.RemoteTokenRefresh@.  The default is 5 minutes.  A longer period reduces overhead from validating tokens, but means it may take longer for other clusters to notice when a token has been revoked or a user has changed status (being activated/deactivated, admin flag changed).
  65
  66 To migrate users of existing clusters with separate user databases to use a single LoginCluster, use "arv-federation-migrate":merge-remote-account.html .
  67
  68 h2. Groups
  69
  70 In order for a user to see (and be able to share with) other users, the admin needs to create a "can_read" permission link from the user to either the "All users" group, or another group that grants visibility to a subset of users.
  71
  72 In a peer federation, this means that for a user that has joined a second cluster, that user needs to be added to the "All users" group on the second cluster as well, to be able to share with other users.
  73
  74 In a LoginCluster federation, all visibility of users to share with other users is set by the LoginCluster.  It is not necessary to add users to "All users" on the other clusters.
  75
  76 h3. Trusted clients
  77
  78 When a cluster is configured to use a LoginCluster, the login flow goes to the LoginCluster to log in and issue a token, then returns the user to the starting workbench.  In this case, you want to configure the LoginCluster to "trust" the workbench instances associated with the other clusters.
  79
  80 <pre>
  81 Clusters:
  82   clsr1:
  83     Login:
  84       TrustedClients:
  85         "https://workbench.cluster2.example": {}
  86         "https://workbench2.cluster2.example": {}
  87         "https://workbench.cluster3.example": {}
  88         "https://workbench2.cluster3.example": {}
  89 </pre>
  90
  91 h2. Testing
  92
  93 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:
  94
  95 1. Log into the local workbench and get the user token
  96 2. Visit the remote workbench specifying the local user token by URL: @https://workbench.cluster2.example?api_token=token_from_clsr1@
  97 3. You should now be logged into @clsr2@ with your account from @clsr1@
  98
  99 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:
 100
 101 <pre>
 102 user@clsr1:~$ arv collection get --uuid clsr2-xvhdp-xxxxxxxxxxxxxxx
 103 </pre>
 104
 105 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.
 106
 107 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:
 108
 109 <pre>
 110 user@clsr1:~$ arv-get clsr2-xvhdp-xxxxxxxxxxxxxxx/uploaded_file .
 111 </pre>