Merge pull request #149 from skeeey/update-readme

update readme
2026-05-10 19:27:59 +00:00 · 2021-06-11 01:48:40 -04:00
parent f04906dad7 5a2ec4d0d5
commit 65bed99bb5
3 changed files with 144 additions and 28 deletions
--- 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.
+Now, you can follow the [getting started guide](./README.md#Quickstart) to work with the open-cluster-management registration repository.
--- a/6
+++ b/6
@@ -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

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

 <!--
 ## XXX References