diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 23e263948..bffdbd0f3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,18 +45,35 @@ Repo maintainers can assign you an issue or pull request by leaving a After your PR is ready to commit, please run following commands to check your code. -```shell -make verify -make test -``` +- verify your code + ```shell + make verify + ``` +- run the unit test + ```shell + make test + ``` +- run the integration test + ```shell + make test-integration + ``` +- run the end-to-end test, prepare a kind cluster and run the following command + ```shell + export KUBECONFIG={the kubeconfig of your kind cluster that will run the e2e test} + + make images + + kind load docker-image quay.io/open-cluster-management/registration --name {your kind cluster name} + + make test-e2e + ``` ## Build images Make sure your code build passed. ```shell -export BUILD_LOCALLY=1 -make +make images ``` -Now, you can follow the [getting started guide](./README.md#getting-started) to work with the open-cluster-management registration repository. \ No newline at end of file +Now, you can follow the [getting started guide](./README.md#Quickstart) to work with the open-cluster-management registration repository. diff --git a/Makefile b/Makefile index 35a2f431c..f55d94cd3 100644 --- a/Makefile +++ b/Makefile @@ -61,15 +61,17 @@ deploy-webhook: ensure-kustomize cluster-ip: CLUSTER_IP?=$(shell $(KUBECTL) get svc kubernetes -n default -o jsonpath="{.spec.clusterIP}") + CLUSTER_CONTEXT?=$(shell $(KUBECTL) config current-context) bootstrap-secret: cluster-ip cp $(KUBECONFIG) dev-kubeconfig - $(KUBECTL) config set clusters.kind-kind.server https://$(CLUSTER_IP) --kubeconfig dev-kubeconfig + $(KUBECTL) config set clusters.$(CLUSTER_CONTEXT).server https://$(CLUSTER_IP) --kubeconfig dev-kubeconfig + $(KUBECTL) delete secret bootstrap-secret -n open-cluster-management --ignore-not-found $(KUBECTL) create secret generic bootstrap-secret --from-file=kubeconfig=dev-kubeconfig -n open-cluster-management e2e-bootstrap-secret: cluster-ip cp $(KUBECONFIG) e2e-kubeconfig - $(KUBECTL) config set clusters.kind-kind.server https://$(CLUSTER_IP) --kubeconfig e2e-kubeconfig + $(KUBECTL) config set clusters.$(CLUSTER_CONTEXT).server https://$(CLUSTER_IP) --kubeconfig e2e-kubeconfig $(KUBECTL) delete secret e2e-bootstrap-secret -n open-cluster-management --ignore-not-found $(KUBECTL) create secret generic e2e-bootstrap-secret --from-file=kubeconfig=e2e-kubeconfig -n open-cluster-management diff --git a/README.md b/README.md index 31754ecf3..c402afb65 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,19 @@ # Cluster Registration -Contains controllers that support the registration of managed clusters to a hub to -place them under management. +Contains controllers that support: -## Community, discussion, contribution, and 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) + +## Community, discussion, contribution, development and support Check the [CONTRIBUTING Doc](CONTRIBUTING.md) for how to contribute to the repo. @@ -17,32 +27,119 @@ You can reach the maintainers of this project at: ------ -## Getting Started +## Quickstart -### Prerequisites +1. Clone this repo: + ``` + git clone https://github.com/open-cluster-management-io/registration.git + ``` -These instructions assume: +2. Prepare a [kind](https://kind.sigs.k8s.io/) cluster, like: + ``` + kind create cluster + ``` -- You have a running kubernetes cluster -- You have `KUBECONFIG` environment variable set to a kubeconfig file giving you cluster-admin - role on that cluster + > Note: The Kubernetes cluster needs v1.19 or greater -> Notice: The time of hub and managed clusters should be synchronized. +3. Export your kind cluster config, like: + ``` + export KUBECONFIG=$HOME/.kube/config + ``` -### Deploy Hub +4. Deploy the hub control plane: + ``` + make deploy-hub + make deploy-webhook + ``` -1. Run `make deploy-hub` -2. Run `make deploy-webhook` +5. Deploy the registraion agent: + ``` + make bootstrap-secret + make deploy-spoke + ``` -### Deploy Spoke +You now have a cluster with registraion up and running. The cluster has been registered to itself. -1. Run `make bootstrap-secret` -2. Run `make deploy-spoke` +Next you need to approve your cluster like this: -## Security Response +1. Approve the managed cluster + ``` + kubectl patch managedcluster local-development -p='{"spec":{"hubAcceptsClient":true}}' --type=merge + ``` -If you've found a security issue that you'd like to disclose confidentially please contact -Red Hat's Product Security team. Details at https://access.redhat.com/security/team/contact +2. Apporve the CSR of the managed clsuter + ``` + kubectl get csr -l open-cluster-management.io/cluster-name=local-development | 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 + local-development 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/v1alpha1 + kind: ManagedClusterSet + metadata: + name: clusterset1 + EOF + ``` +2. Add your cluster to the created cluster + ``` + kubectl label managedclusters local-development "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, like: + ``` + kubectl get managedclustersets clusterset1 -o jsonpath='{.status.conditions[?(@.type=="ClusterSetEmpty")]}' + + {"message":"1 ManagedClusters selected","reason":"ClustersSelected"} + ``` + +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 + ``` + cat << EOF | kubectl apply -f - + apiVersion: cluster.open-cluster-management.io/v1alpha1 + kind: ClusterClaim + metadata: + name: id.k8s.io + spec: + value: local-development + EOF + ``` + +2. Then, you can find the claim from the managed cluster status, like: + ``` + kubectl get managedcluster local-development -o jsonpath='{.status.clusterClaims}' + + [{"name":"id.k8s.io","value":"local-development"}] + ``` + +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`