mirror of
https://github.com/open-cluster-management-io/ocm.git
synced 2026-05-18 23:29:40 +00:00
196 lines
7.1 KiB
Markdown
196 lines
7.1 KiB
Markdown
# Cluster Registration
|
|
|
|
Contains controllers that support:
|
|
|
|
- the registration of managed clusters to a hub to place them under management
|
|
(see [cluster join process](https://github.com/open-cluster-management-io/api/blob/main/docs/clusterjoinprocess.md) for design deatails)
|
|
- the concept of clusterset (see [KEP-1645](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/1645-multi-cluster-services-api) for details)
|
|
by `ManagedClusterSet` API to group managed clusters
|
|
(see [managed cluster set](https://github.com/open-cluster-management-io/api/blob/main/docs/clusterset.md) for design deatails)
|
|
- the concept of clusterclaim (see [KEP-2149](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/2149-clusterid) for details)
|
|
by `ManagedClusterClaim` API to collect the cluster information from a managed cluster
|
|
(see [cluster claim](https://github.com/open-cluster-management-io/api/blob/main/docs/clusterset.md) for design deatails)
|
|
- the management of [managed cluster add-ons](https://github.com/open-cluster-management-io/api/blob/main/addon/v1alpha1/types_managedclusteraddon.go)
|
|
(see [managed cluster addons management](https://github.com/open-cluster-management-io/enhancements/tree/main/enhancements/sig-architecture/12-addon-manager) 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](https://kind.sigs.k8s.io/) 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)
|
|
```sh
|
|
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
|
|
```sh
|
|
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.
|
|
```sh
|
|
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.
|
|
```sh
|
|
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.
|
|
```sh
|
|
kubectl --kubeconfig </path/to/hub_cluster/kubeconfig> -n kube-public get configmap cluster-info -o yaml
|
|
```
|
|
|
|
3. Override the docker image (optional)
|
|
```sh
|
|
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](https://github.com/open-cluster-management-io/api/blob/main/docs/clusterjoinprocess.md), 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](https://github.com/open-cluster-management-io/api/blob/main/docs/clusterset.md)
|
|
|
|
### 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](https://github.com/open-cluster-management-io/enhancements/tree/main/enhancements/sig-architecture/4-cluster-claims)
|
|
|
|
### 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](https://github.com/open-cluster-management-io/addon-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](https://github.com/open-cluster-management-io/enhancements/tree/main/enhancements/sig-architecture/12-addon-manager)
|
|
|
|
> 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](CONTRIBUTING.md) for how to contribute to the repo.
|
|
|
|
### Communication channels
|
|
|
|
Slack channel: [#open-cluster-mgmt](http://slack.k8s.io/#open-cluster-mgmt)
|
|
|
|
## License
|
|
|
|
This code is released under the Apache 2.0 license. See the file [LICENSE](LICENSE) for more information.
|
|
|
|
|
|
<!--
|
|
## XXX References
|
|
|
|
If you have any further question about xxx, please refer to
|
|
[XXX help documentation](docs/xxx_help.md) for further information.
|
|
-->
|