Cluster Links

ENTERPRISE

Managing links between clusters

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:

  1. 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.

  2. 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:

      1. dcos:adminrouter:ops:mesos full
      2. dcos:adminrouter:ops:slave full
      3. dcos:adminrouter:service:marathon full
      4. dcos:service:marathon:marathon:services:/ full
      5. 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:

  1. dcos cluster link <dcos-url>
  2. Choose the login method and provider to enable switching to this linked cluster::
  3. 1) Provider 1
  4. 2) Provider 2
  5. (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:

  1. 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:

  1. 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

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

    Linked Cluster link

    Figure 1 - Linked Clusters link

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

    open cluster popup

    Figure 2 - Open cluster menu

  3. Select Switch Cluster.

    swi cluster

    Figure 3 - Switch clusters

  4. Click the name of the cluster to switch to.

    swi linked cluster

    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.

  1. Select Cluster > Linked Clusters.

  2. At the far right, click the vertical ellipsis and select Switch.

    swi linked cluster2

    Figure 5 - Switching to linked clusters

Linking and switching cluster examples

Link clusters as a superuser operator via CLI

  1. Set up cluster cluster-a using the dcos-user provider.

    1. $ 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.

  2. Set up cluster-b using the dcos-user provider.

    1. $ 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.

  3. Attach to cluster cluster-a and list.

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

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

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

    The CLI prompts you to choose the login provider for switching.

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

  5. Choose Google IDP (2). If the cluster links successfully, there will be no response.

    1. (1-2): 2

  6. Attach to cluster cluster-b.

    1. $ dcos cluster attach cluster-b

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

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

    The CLI prompts to choose the login provider for switching.

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

  8. Choose Google IDP (2).

    1. (1-2): 2

  9. List clusters.

    1. dcos cluster list
    2.       NAME                    CLUSTER ID                 STATUS   VERSION                                         URL
    3. cluster-b*  34ddd64a-9301-40b1-bb6a-201ec55a0d80  AVAILABLE  1.12-dev   https://cluster-b.us-west-2.elb.amazonaws.com
    4.  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.

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

    google login

    Figure 6 - Google login

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

    open cluster popup

    Figure 7 - Switch cluster

  3. Click Switch Cluster.

Switch clusters using the CLI with Google SSO

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

  1. List authentication providers.

    1. dcos auth list-providers https://cluster-a.us-west-2.elb.amazonaws.com
    2. PROVIDER ID    AUTHENTICATION TYPE
    3. dcos-services  Log in using a DC/OS service user account (username and private key)
    4. dcos-users     Log in using a standard DC/OS user account (username and password)
    5. google-idp     Log in using OpenID Connect (Google IDP)

  2. Set up cluster with Google IDP.

    1. dcos cluster setup --provider=google-id 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.

  3. Copy the authentication token from the browser and paste in the terminal.

  4. List clusters. The setup cluster shows as AVAILABLE and attached and the previously linked cluster shows as UNCONFIGURED.

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

  5. Attach to UNCONFIGURED cluster.

    1. dcos cluster attach cluster-b

    The response requests that you verify the fingerprint of the cluster certificate bundle, which must be accepted with the response yes.

  6. Copy the authentication token from the browser and paste in the terminal. The CLI successfully attaches to cluster cluster-b.

  7. List clusters to verify attachment to cluster-b.

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