A cluster link is a unidirectional relationship between a cluster and another cluster.

You add and remove links from one cluster to another cluster using DC/OS™ CLI dcos cluster link and dcos cluster unlink commands and the cluster link API. Once a link is set up you can easily switch between clusters using the CLI or UI. If the links have been set up using an SSO provider, you will not need to provide credentials to switch clusters.

You must be a superuser or have the appropriate cluster link permission to view, add, and remove links and grant permissions to view linked clusters.

Enable access to cluster links using SSO

As superuser:

Configure an OpenID® IdP.
1. Ensure both cluster URLs are provided in Authorized JavaScript origins and Authorized redirect URIs fields in the Google® Dev console.
2. Give the OIDC name such as “google-idp”.
3. Ensure both clusters use the same Client-Id and Client-Secret when configuring OIDC.
Provide each user with permission to see services and linked clusters:
1. Select Organization -> Users.
2. Select a user.
3. Click Add Permission.
4. In the top right, click Insert Permission String.
5. Paste in the permissions:
```
dcos:adminrouter:ops:mesos full
dcos:adminrouter:ops:slave full
dcos:adminrouter:service:marathon full
dcos:service:marathon:marathon:services:/ full
dcos:cluster:linker:* read
```
6. Click Add Permission.

Add a link to a cluster

To add a link to another cluster, run the dcos cluster link command, supplying the URL of the cluster to link to:

dcos cluster link <dcos-url>
Choose the login method and provider to enable switching to this linked cluster::
1) Provider 1
2) Provider 2
(1-2):

Viewing linked clusters

To view all linked clusters, run the dcos cluster list command. If a cluster was linked, but not set up, its status is UNCONFIGURED. If a cluster is linked and attached, its status is AVAILABLE. Also see Viewing Connected Clusters.

Remove a linked cluster

To remove a link, dcos cluster unlink command and supply the name or ID of a linked cluster. For example:

dcos cluster unlink <linked-cluster>

Switch cluster

You can switch between linked clusters using the CLI or UI. When you switch clusters using the CLI, the new cluster becomes the CLI’s active cluster. The new cluster becomes the cluster you see in the UI. If you switch the cluster in the CLI it does not change the cluster in the UI; similarly, switching in the UI does not affect the attached cluster in the CLI.

Switch to a linked cluster from the DC/OS CLI

Run the dcos cluster attach command and supply the name or ID of a linked cluster:

dcos cluster attach <linked-cluster>

If you run dcos cluster list, <linked-cluster> will have an asterisk by its name.

Switch to a linked cluster from the DC/OS UI

At the top-right corner of the DC/OS web interface, click the down arrow to the right of your cluster name.

Figure 1 - Cluster dropdown
Select Switch Cluster.

Figure 2 - Cluster switch
Click the name of the cluster to switch to.

Figure 3 - Switch to linked cluster

If you are a superuser, you can also switch to a linked cluster in the Linked Clusters tab.

Select Cluster -> Linked Clusters.
At the far right of the cluster to switch to, click the vertical ellipsis and select Switch.

Figure 4 - Switch to linked clusters

Example of linking and switching cluster

Link clusters as a superuser operator using CLI

Set up cluster cluster-a using the dcos-user provider.
```
$ dcos cluster setup --provider=dcos-users https://cluster-a.us-west-2.elb.amazonaws.com
```
The response requests that you verify the fingerprint of the cluster certificate bundle, which must be accepted with the response yes. The CLI prompts for superuser credentials. Provide the credentials.
Set up cluster-b using the dcos-user provider.
```
$ dcos cluster setup --provider=dcos-users https://cluster-b.us-west-2.elb.amazonaws.com
```
The response requests that you verify the fingerprint of the cluster certificate bundle, which must be accepted with the response yes. The CLI prompts for superuser credentials. Enter the credentials.

Attach to cluster cluster-a and list.

dcos cluster attach cluster-a
dcos cluster list
      NAME                    CLUSTER ID                 STATUS   VERSION                                         URL
 cluster-b  34ddd64a-9301-40b1-bb6a-201ec55a0d80  AVAILABLE  1.12-dev   https://cluster-b.us-west-2.elb.amazonaws.com
cluster-a*  584d3e8f-c5c2-4c86-b180-ff3c1f15b0d5  AVAILABLE  1.12-dev  https://cluster-a.us-west-2.elb.amazonaws.com

Link to cluster cluster-b from cluster cluster-a.

dcos cluster link https://cluster-b.us-west-2.elb.amazonaws.com

The CLI prompts to choose the login provider for switching.

Choose the login method and provider to enable switching to this linked cluster:
1) Log in using a standard DC/OS user account (username and password)
2) Log in using OpenID Connect (Google IDP)
(1-2):

Choose Google® IDP (2).
```
(1-2): 2
```

If the cluster links successfully there is no response.

Attach to cluster cluster-b.
```
dcos cluster attach cluster-b
```

Link to cluster cluster-a from cluster cluster-b.

dcos cluster link https://cluster-a.us-west-2.elb.amazonaws.com

The CLI prompts to choose the login provider for switching.

Choose the login method and provider to enable switching to this linked cluster:
1) Log in using a standard DC/OS user account (username and password)
2) Log in using OpenID Connect (Google IDP)
(1-2):

Choose Google IDP (2).
```
(1-2): 2
```

List clusters.

dcos cluster list
      NAME                    CLUSTER ID                 STATUS   VERSION                                         URL
cluster-b*  34ddd64a-9301-40b1-bb6a-201ec55a0d80  AVAILABLE  1.12-dev   https://cluster-b.us-west-2.elb.amazonaws.com
 cluster-a  584d3e8f-c5c2-4c86-b180-ff3c1f15b0d5  AVAILABLE  1.12-dev  https://cluster-a.us-west-2.elb.amazonaws.com

Once an operator has set up links, you can switch between clusters using the UI or CLI.

Switch clusters using the web interface with Google SSO

You can easily switch to a linked cluster that has been set up with the Google OpenID provider.

Log in to DC/OS UI of cluster cluster-a as an external user using Google credentials.

Figure 5 - Google login
From the top left corner, click the down arrow next to the cluster name.

Figure 6 - Switch cluster
Click Switch Cluster. In the Linked Clusters pane, select cluster cluster-b. Cluster cluster-b’s UI displays.

Switch clusters using the CLI with Google SSO