Project: Open Cluster Management (Orchestration & Management / Scheduling & Orchestration)
File: clusterjoinprocess.md

This is to describe the various process of cluster join Actors: cluster-admin on managed cluster cluster-admin on hub cluster hub controller agent on managed cluster Some rules on cluster join: The name of the cluster must be globally unique on hub and conforms to dns label format. cluster-admin on managed cluster gets a bootstrap kubeconfig to connect to hub, and deploy the agent on managed cluster. it has the identity to create `ManagedCluster` and create/watch csr. agent on managed cluster creates `ManagedCluster` if it does not exist. The name of `ManagedCluster` is read from Cluster UID in openshift. Otherwise agent generates an agent UID and use it as part of `CommonName` to request a certificate(step 3), and once the CSR is approved on the hub, the agent on the managed cluster will store it as `agent-name` in `Secret` `hub-kubeconfig-secret`(step 10), so restarting agent or redeploying agent will not lose the UID after the cluster is managed successfully. agent on managed cluster creates CSR on hub cluster using bootstrap kubeconfig. The subject in CSR is `{"Organization": ["system:open-cluster-management:clusterName"], "CommonName":"system:open-cluster-management:clusterName:agentName"}`. The name of the csr is the digest of subject and private key, with a common prefix. CSR will specify the signer name as the kube-client one. cluster-admin on hub-cluster approve the CSR. hub-controller creates a clusterrolebinding on the hub with the identity of `open-cluster-management:managedcluster:clusterName` Allows status update of `ManagedCluster` cluster-admin on hub update `spec.hubAcceptsClient` to `true`. Only user on hub who has the RBAC permission to update subresource of `managedclusters/accept` can update this field. hub-controller updates condition of `ManagedCluster` to `HubAcceptedManagedCluster`. hub-controller creates a namespace as the name of cluster on hub cluster if it does not exist. managed cluster can only join a hub once, and it can join to multiple hubs. The UID of the managed cluster is identical on each of the hub the Klusterlet agent joins. hub-controller creates rolebinding `open-cluster-management:managedcluster:clusterName:registration` binded to cluster role `open-cluster-management:managedcluster:registration` on the cluster namespace on the hub Allow the access of agent on managed cluster to the namespace. agent on managed cluster gets certificate in CSR status, uses the certificate to create a new kubeconfig `hub-kubeconfig-secret` and saves it as secret. agent on managed cluster connects to hub apiserver using the new kubeconfig. agent on managed cluster updates conditions of `ManagedCluster` as `ManagedClusterJoined`. agent on managed cluster appends updates other fields in status of `ManagedCluster`. agent on managed cluster detects the certificate is going to be expired. it checks if certificate will be expired in 20% of certificate duration. agent on managed cluster generates a new private key and submits a new CSR to hub apiserver. it uses the identity of `system:open-cluster management:clusterName:agentName` to create the csr the subject in the certificate should be `{"Organization": ["system:open-cluster-management:clusterName"], "CommonName":"system:open-cluster-management:clusterName:agentName"}` hub controller auto approves the csr. hub controller checks if the csr can be approved based on the following steps: check if organization field and commonName field is valid. check if user name in csr is the same as commonName in certificate to ensure the request is originated from the same identity. agent on managed cluster reconstructs the kubeconfig using the new key/certificate and saves it as a secret on managed cluster.