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

Create namespace kasten-io-mc.

$ kubectl create namespace kasten-io-mc

A bootstrap object needs to be created in the newly created kasten-io-mc namespace.

$ 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: primary-cluster-1
         primary: true
         k10:
             namespace: kasten-io
             releaseName: k10
             ingress:
                 url: "https://primary-cluster-1.dev.kasten.io/k10"
EOF

$ kubectl create -f sample-primary-bootstrap.yaml
bootstrap.dist.kio.kasten.io/bootstrap-primary created

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: primary-cluster-1
 namespace: kasten-io-mc
spec:
 k10:
    ingress:
      url: "https://primary-cluster-1.dev.kasten.io/k10"
 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 endpoint and token.

The endpoint is the primary cluster's endpoint for multi-cluster communication. 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:
 endpoint: <encoded_primary_endpoint>
 token: <encoded_join_token>

Join Secret

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

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

This will trigger a join from the secondary 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 will have no effect on the system.

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.