Getting Started

With K10 already installed in each cluster, a simple joining process enables the K10 multi-cluster manager. Through the joining process, one cluster will be setup as the primary. Additional clusters are then joined as secondaries.

Tip

To get started, just setting up a primary can be a great way to go! Secondaries can be added at any time.

Setting up Through the UI

Promoting a Primary Cluster

To initiate a multi-cluster setup, the first step is to designate one cluster as the primary, which will serve as the host for the Multi-cluster Manager.

1. Navigate to the Multi-Cluster page.

2. Click the Promote button inside the Promote to Primary card.

3. Enter a memorable name for the primary cluster. This name must adhere to specific formatting rules:

• Only lower case letters, numbers, hyphens -, or periods . are allowed.

• The name must start and end with an alphanumeric character (a letter or a number).

Additionally, the Primary Ingress field will be auto-populated with the browser's current protocol and domain. However, if necessary, it can be modified.

4. Click Promote Cluster.

When the promotion is successful, the application will redirect to the new Multi-Cluster Manager page, where the primary cluster should be visible in the list of clusters.

Creating a Join Token

1. Navigate to the Join Tokens page in the K10 Multi-Cluster manager on the Primary Cluster.

2. Click the Create New Join Token button.

3. Enter a memorable name for the Join Token. This name must adhere to specific formatting rules:

• Only lower case letters, numbers, hyphens -, or periods . are allowed.

• The name must start and end with an alphanumeric character (a letter or a number).

4. Click Confirm.

5. Click the Copy button to save the new Join Token to the clipboard.

6. Then, click Done. The newly created Join Token should be listed in the table.

Joining a Multi-Cluster System

Using a Join Token, it is possible to connect a secondary cluster to a Multi-Cluster primary instance.

1. On the secondary cluster, navigate to the Multi-Cluster page.

2. Click the Join button inside the Join a Multi-Cluster card.

3. Paste the Join Token that was into the Token input.

The ingress of the Primary cluster is encoded in the token, and that ingress is most likely the correct one. However, the option to override the ingress in the token is available and may be necessary in certain situations.

4. To override the token, enable the Override Primary Ingress switch and enter a URL in the Primary Ingress Override input.

5. Enter a memorable name for this cluster to be used by the Multi-Cluster. This name must adhere to specific formatting rules:

• Only lower case letters, numbers, hyphens -, or periods . are allowed.

• The name must start and end with an alphanumeric character (a letter or a number).

If a name is not entered, a random name will be assigned.

6. Click the Connect button.

7. Verify the information in the dialog box, then click Yes, Join.

The join process will take several seconds.

Afterwards, the K10 Multi-Cluster information page should be displayed.

If a Join Request is rejected (due to an expired token), an option to try again will be displayed, and users can return to the Join a Multi-Cluster form by clicking the Start Over button.

Setting Up Via CLI

Setup Primary

Note

If a secondary cluster needs to be set up as a primary, it cannot be done while it is a already a part of a multi-cluster system. Before proceeding, it is necessary to disconnect the cluster and then initiate the setup process.

Setting Up the Primary Cluster Using Helm

Setting up the primary cluster using Helm requires configuring all of the following Helm flags during the execution of helm install or helm upgrade:

• multicluster.primary.create=true

• multicluster.primary.name=<cluster name>

• multicluster.primary.ingressURL=<dashboard URL of primary cluster>

The format for multicluster.primary.ingressURL is <URL of cluster>/<helm release name> (e.g., https://cluster-name.dev.kasten.io/k10).

Setting Up the Primary Cluster Using kubectl

Create namespace kasten-io-mc.

$ kubectl create namespace kasten-io-mc

Create a bootstrap object in the newly created kasten-io-mc namespace. Assuming that K10 has been installed in the kasten-io namespace using k10 as the release name:

$ cat > sample-primary-bootstrap.yaml <<EOF
apiVersion: dist.kio.kasten.io/v1alpha1
kind: Bootstrap
metadata:
 name: bootstrap-primary
 namespace: kasten-io-mc
spec:
 clusters:
     primary-cluster:
         name: <cluster name>
         primary: true
         k10:
             namespace: kasten-io
             releaseName: k10
             ingress:
                 url: <cluster dashboard URL; e.g. "https://cluster-name.dev.kasten.io/k10">
EOF

Edit sample-primary-bootstrap.yaml to set <cluster name> and <cluster dashboard URL> values for the primary cluster.

Apply the manifest.

$ kubectl create -f sample-primary-bootstrap.yaml

When the bootstrap completes successfully, a cluster object is created in the kasten-io-mc namespace.

apiVersion: dist.kio.kasten.io/v1alpha1
kind: Cluster
metadata:
 labels:
    dist.kio.kasten.io/cluster-type: primary
 name: <cluster name>
 namespace: kasten-io-mc
spec:
 k10:
    ingress:
      url: <cluster dashboard URL>
 namespace: kasten-io
 releaseName: k10
 primary: true
status:
 id: <cluster_id>

Adding a Secondary Cluster

Join Tokens

Create a join token secret in the primary cluster to generate a join token that can be used by a secondary cluster to connect to the given primary.

apiVersion: v1
kind: Secret
metadata:
 generateName: join-token-secret-
 namespace: kasten-io-mc
type: dist.kio.kasten.io/join-token

The data will be automatically filled in and you can retrieve the token.

The token is used for authenticating the joining request from a secondary cluster.

Note

Do not share the join tokens. To revoke a token, simply delete the join token secret.

   apiVersion: v1
   kind: Secret
   metadata:
    generateName: join-token-secret-
    namespace: kasten-io-mc
   type: dist.kio.kasten.io/join-token
   data:
    token: <encoded_join_token>


.. note:: The token is encoded with the primary ingress specified in
    the primary cluster objects.

Join Secret

Create a mc-join secret in the secondary cluster or clusters with the above token.

apiVersion: v1
kind: Secret
metadata:
 name: mc-join
 namespace: kasten-io
data:
 token: <encoded_join_token>

Join ConfigMap

Create a ConfigMap with the name mc-join-config in the secondary cluster(s) to configure optional information like cluster name, cluster ingress and primary ingress.

Note

All fields are optional but the mc-join-config ConfigMap is required to trigger a join from the secondary.

• If the cluster-name is specified, the primary cluster will attempt to use it for identifying the created cluster resource. The cluster-name must adhere to Kubernetes naming conventions and be unique within the managed cluster set; otherwise, the join will fail.

• If cluster-name is not specified, the primary cluster will automatically generate the cluster name.

• If the cluster-ingress is specified, the primary cluster will attempt to use it for proxying dashboard requests to the secondary cluster. The cluster-ingress is the K10 ingress for the secondary cluster.

• If cluster-ingress is not specified, the primary cluster disables proxy. Additionally, click-through into the secondary cluster from the primary cluster dashboard will not be allowed.

• If primary-ingress is specified, the provided ingress will be used during the join process to connect to the primary. This will override the primary ingress encoded in the join token.

• If primary-ingress is not specified, the join process will use the ingress encoded in the join token in the mc-join secret.

apiVersion: v1
kind: ConfigMap
metadata:
 name: mc-join-config
 namespace: kasten-io
data:
 cluster-name: <optional cluster name>
 cluster-ingress: <optional cluster ingress>
 primary-ingress: <optional primary ingress override>

This will trigger a join from the secondary cluster to the primary cluster. The primary cluster will validate the token and admit the cluster.

Note

If K10 Multi-Cluster is disabled, creating the mc-join secret and mc-join-config ConfigMap will have no effect on the system.

Note

Both mc-join secret and mc-join-config ConfigMap are required to initiate a join.

Join Status Secret

The progress of the join will be recorded in the mc-join-status secret. Any failures will also be recorded in this secret.

You can see the status by looking at the mc-join-status secret.

$ kubectl get secret mc-join-status --namespace=kasten-io

apiVersion: v1
kind: Secret
metadata:
 name: mc-join-status
 namespace: kasten-io
data:
  msg: <failure_msg_if_any>
  status: <current status> # Joining, Joined, Rejected
  timestamp: <timestamp when status is recorded>
  mc-join.hash: <hash of mc-join>

The msg field will be populated with any failures (transient or permanent), recorded during the joining process. The status field records the current status.

Cluster Info Secret

Once the join is successful, the mc-cluster-info secret is created with information needed by the secondary cluster to communicate with the primary.

You can see the information by looking at the mc-cluster-info secret.

$ kubectl get secret mc-cluster-info --namespace=kasten-io

apiVersion: v1
kind: Secret
metadata:
 name: mc-cluster-info
 namespace: kasten-io
data:
  primary: false
  clusterName: <secondary_cluster_name>
  endpoint: <primary's_endpoint>
  token: <token_for_communication>
  primaryName: <primary_cluster_name>
  primaryPublicKey: <primary's_public_key>

A corresponding bootstrap and cluster object should be created in the primary cluster's kasten-io-mc namespace.