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 logged in as 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 that both cluster URLs are provided in Authorized JavaScript origins and Authorized redirect URIs fields in the Google Dev console.
2. Give the OIDC a name, such as “google-idp”.
3. Ensure that 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, it status is UNCONFIGURED. If a cluster is linked and attached, its status is AVAILABLE. Also see Viewing Connected Clusters.

Remove a link to a 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 clusters

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. When you switch clusters using the UI, the new cluster becomes the cluster you see in the UI. If you switch the cluster in the CLI, it doesn’t change the cluster in the UI; similarly, switching in the UI doesn’t 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

From the left hand navigation menu, select Cluster > Linked Clusters.

Figure 1 - Linked Clusters link
At the top-right corner of the DC/OS UI, click the down arrow to the right of your cluster name.

Figure 2 - Open cluster menu
Select Switch Cluster.

Figure 3 - Switch clusters
Click the name of the cluster to switch to.

Figure 4 - Switching to linked cluster

Switching clusters as a superuser

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

Select Cluster > Linked Clusters.
At the far right, click the vertical ellipsis and select Switch.

Figure 5 - Switching to linked clusters

Linking and switching cluster examples

Link clusters as a superuser operator via 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. Provide 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 you 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). If the cluster links successfully, there will be no response.
```
(1-2): 2
```
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 UI 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 6 - Google login
At the top-right corner of the DC/OS UI, click the down arrow to the right of your cluster name.

Figure 7 - Switch cluster
Click Switch Cluster.

Switch clusters using the CLI with Google SSO