README.md

Cluster Registration

Contains controllers that support:

• the registration of managed clusters to a hub to place them under management (see cluster join process for design deatails)
• the concept of clusterset (see KEP-1645 for details) by ManagedClusterSet API to group managed clusters (see managed cluster set for design deatails)
• the concept of clusterclaim (see KEP-2149 for details) by ManagedClusterClaim API to collect the cluster information from a managed cluster (see cluster claim for design deatails)
• the management of managed cluster add-ons (see managed cluster addons management for design deatails)

Quickstart

Prepare

1. Clone this repo:

git clone https://github.com/open-cluster-management-io/registration.git && cd registration

2. Prepare a kind cluster, like:

kind create cluster # if you want to deploy on two clusters, you can exec `kind create cluster --name=<cluster-name> to prepare another cluster`

Note: The Kubernetes cluster needs v1.19 or greater

Deploy

Deploy on one single cluster

1. Export your kind cluster config, like:

export KUBECONFIG=$HOME/.kube/config

2. Override the docker image (optional)

export IMAGE_NAME=<your_own_image_name> # export IMAGE_NAME=quay.io/open-cluster-management/registration:latest

3. Deploy the hub control plane and the registration agent:

make deploy

Deploy on two clusters

1. Set environment variables.

• Hub and managed cluster share a kubeconfig file

  export KUBECONFIG=</path/to/kubeconfig>
  export HUB_KUBECONFIG_CONTEXT=<hub-context-name>
  export SPOKE_KUBECONFIG_CONTEXT=<spoke-context-name>

• Hub and managed cluster use different kubeconfig files.

  export HUB_KUBECONFIG=</path/to/hub_cluster/kubeconfig>
  export SPOKE_KUBECONFIG=</path/to/managed_cluster/kubeconfig>

2. Set cluster ip if you are deploying on KIND clusters.

export CLUSTER_IP=<host_name/ip_address>:<port> # export CLUSTER_IP=hub-control-plane:6443

If you are not using KIND, you can get the above information with command below.

kubectl --kubeconfig </path/to/hub_cluster/kubeconfig> -n kube-public get configmap cluster-info -o yaml

3. Override the docker image (optional)

export IMAGE_NAME=<your_own_image_name> # export IMAGE_NAME=quay.io/open-cluster-management/registration:latest

4. Deploy the hub control plane and the registration agent

make deploy

Approve your cluster

You now have a cluster with registration up and running. The cluster has been registered to the hub.

Next you need to approve your cluster like this:

1. Approve the managed cluster

kubectl config use-context <hub-context-name>
kubectl patch managedcluster cluster1 -p='{"spec":{"hubAcceptsClient":true}}' --type=merge

2. Apporve the CSR of the managed clsuter

kubectl get csr -l open-cluster-management.io/cluster-name=cluster1 | grep Pending | awk '{print $1}' | xargs kubectl certificate approve

3. Finally, you can find the managed cluster is joined and available

kubectl get managedcluster

NAME                HUB ACCEPTED   MANAGED CLUSTER URLS   JOINED   AVAILABLE   AGE
cluster1            true                                  True     True        2m21s

You can find more details for cluster join process from this design doc, and after the registration is deployed, you can try the following features

Cluster Set

1. Create a cluster set by ManagedClusterSet API

cat << EOF | kubectl apply -f -
apiVersion: cluster.open-cluster-management.io/v1beta1
kind: ManagedClusterSet
metadata:
  name: clusterset1
EOF

2. Add your cluster to the created cluster

kubectl label managedclusters cluster1 "cluster.open-cluster-management.io/clusterset=clusterset1" --overwrite

3. Then, you can find there is one managed cluster is selected from the managed cluster set status, e.g:

kubectl get managedclustersets clusterset1 -o jsonpath='{.status.conditions[?(@.type=="ClusterSetEmpty")]}'

{"lastTransitionTime":"2021-08-17T06:18:26Z","message":"1 ManagedClusters selected","reason":"ClustersSelected","status":"False","type":"ClusterSetEmpty"}

You can find more details from the managed cluster set design doc

Cluster Claim

1. Create a ClusterClaim to claim the ID of this cluster

kubectl config use-context <spoke-context-name>

cat << EOF | kubectl apply -f -
apiVersion: cluster.open-cluster-management.io/v1alpha1
kind: ClusterClaim
metadata:
  name: id.k8s.io
spec:
  value: cluster1
EOF

2. Then, you can find the claim from the managed cluster status, like:

kubectl config use-context <hub-context-name>

kubectl get managedcluster cluster1 -o jsonpath='{.status.clusterClaims}'

[{"name":"id.k8s.io","value":"cluster1"}]

You can find more details from the cluster claim design doc

Managed Cluster Add-Ons

A managed cluster add-ons is deployed on the managed cluster to extend the capability of managed cluster. Developers can leverage add-on framework to implement their add-ons. The registration provides the management of the lease update and registration for all managed cluster addons, you can find more details from the Managed cluster addons management design doc

Note: The addon-management is in alpha stage, it is not enabled by default, it is controlled by feature gate AddonManagement

Community, discussion, contribution, and support

Check the CONTRIBUTING Doc for how to contribute to the repo.

Communication channels

Slack channel: #open-cluster-mgmt

License

This code is released under the Apache 2.0 license. See the file LICENSE for more information.