Getting Started

Note

This method is only available to clusters with K10 version 6.5 and higher. Refer to k10multicluster Tool if using a lower version.

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 Clusters

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

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

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>

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 mc-join-config ConfigMap in the secondary cluster or clusters to configure optional information like cluster name and primary endpoint.

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 primary-endpoint is specified, the provided endpoint will be used during the join process to connect to the primary.

  • If primary-endpoint is not specified, the join process will use the endpoint 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>
 primary-endpoint: <optional primary endpoint 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.