edit the proposal

Author: charleszheng44

proposals/20201026-creating-control-plane-components.md

@@ -68,7 +68,7 @@ The goal of this proposal is to define CRDs of the three major components (kube-
 
 ## Motivation
 
-CAPN aims at providing control plane level isolation while sharing physical resources among control planes. There exist various approaches to creating isolated control planes. For example, one can run components of the nested control plane as pods on the underlying clusters, create NCPs through cloud providers' Kubernetes services or use third-party component providers to create each component. In this proposal, we try to define CRDs of the NCP's three major components and a standard process of creating the three components regardless of which underlying approach is used. As examples, we introduce two setups that 1) creating each component natively, 2) creating KAM and KCM natively while using the [Etcd-cluster-operator](https://github.com/improbable-eng/etcd-cluster-operator) to create the Etcd.
+CAPN aims at providing control plane level isolation while sharing physical resources among control planes. There exist various approaches to creating isolated control planes. For example, one can run components of the nested control plane as pods on the underlying clusters, create NCPs through cloud providers' Kubernetes services or use out-of-tree component controllers to create each component. In this proposal, we try to define CRDs of the NCP's three major components and a standard process of creating the three components regardless of which underlying approach is used. As examples, we introduce two setups that 1) creating each component natively, 2) creating KAM and KCM natively while using the [Etcd-cluster-operator](https://github.com/improbable-eng/etcd-cluster-operator) to create the Etcd.
 
 ### Goals
 
@@ -118,17 +118,17 @@ The `CommonSpecs` and the `PatchSpec` are defined in [kubebuilder-declarative-pa
 ```go
 // CommonSpec defines the set of configuration attributes that must be exposed on all addons.
 type CommonSpec struct {
-	// Version specifies the exact addon version to be deployed, eg 1.2.3
-	// It should not be specified if Channel is specified
-	Version string `json:"version,omitempty"`
-	// Channel specifies a channel that can be used to resolve a specific addon, eg: stable
-	// It will be ignored if Version is specified
-	Channel string `json:"channel,omitempty"`
+    // Version specifies the exact addon version to be deployed, eg 1.2.3
+    // It should not be specified if Channel is specified
+    Version string `json:"version,omitempty"`
+    // Channel specifies a channel that can be used to resolve a specific addon, eg: stable
+    // It will be ignored if Version is specified
+    Channel string `json:"channel,omitempty"`
 }
 
 // +k8s:deepcopy-gen=true
 type PatchSpec struct {
-	Patches []*runtime.RawExtension `json:"patches,omitempty"`
+    Patches []*runtime.RawExtension `json:"patches,omitempty"`
 }
 ```
 
@@ -138,10 +138,26 @@ type PatchSpec struct {
 
 We assume that the APIServer, ContollerManager, Etcd and the NCP CR are located in the same namespace. To create an NCP, we need to first create APIserver CR, ControllerManager CR, Etcd CR, NCP CR, and a namespace that holds all the CRs, then the component controller can cooperate with each other to create components for the NCP. 
 
-As there exist dependencies between components, i.e., KAS cannot run without Etcd, KCM cannot work without KAS, when creating NCP components, component controllers will need to get information and status of other CRs. Also, as all CRs of an NCP will be located in the same namespace, we will set `metav1.OwnerReference` in each component CR as the NCP that owns the CR, which can help the CR to find its belonging NCP. As the NCP status will include all required [CAPI status](https://cluster-api.sigs.k8s.io/developer/architecture/controllers/control-plane.html#required-status-fields), we can then use the `Selector` field to get the desired CR.
+As there exist dependencies between components, i.e., KAS cannot run without Etcd, KCM cannot work without KAS, when creating NCP components, component controllers will need to get information and status of other CRs. To achieve this, we will add three `ObjectReference` to the `NestedControlPlaneSpec` with each `ObjectReference` points to a component.
 
-### Creation
+```go
+type NestedControlPlaneSpec struct {
+    // other fields ...
+    
+    // Etcd is the eference to the NestedEtcd 
+    Etcd *corev1.ObjectReference `json:"etcd,omitempty"` 
+    
+    // APIServer is the reference to the NestedAPIServer 
+    APIServer *corev1.ObjectReference `json:"apiserver,omitempty"` 
+    
+    // ContollerManager is the reference to the NestedControllerManager
+    ControllerManager *corev1.ObjectReference `json:"controllerManager,omitempty"`
+}
+```
 
+After applying the NCP CR, the NCP controller will find the three associated components and set their `metav1.OwnerReference` as the NCP CR. Then, when creating the component workload, the component controller can find other CRs through the owner NCP.
+
+### Creation
 End-users can create component CRs manually and apply them to the cluster with an NCP to create the resources. In the future, we might introduce the `Template` CR, which will handle the creation of the component CRs in it's controller. If the end-user intend to use out-of-tree controllers, they can specify them in the NCP spec, we define three new types:
 
 ```go
@@ -203,7 +219,7 @@ The creating process will include six steps:
 
 3. The KAS controller creates a KAS service (for exposing the NCP), generates certificates (including a root CA, TLS serving certificates), creates the KAS workload, stores the certificates into `secret/[cluster-name]-ca`, creates a kubeconfig and stores it into `secret/[cluster-name]-kubeconfig`.
 
-4. The KCM controller generates the KCM kubeconfig (cluster CA can be read from the `secret/[cluster-name]-ca` and the KAS address can be extracted from the `KAS service`), creates the KCM workload which will talk to the KAS using the KCM kubeconfig.
+4. The KCM controller generates the KCM kubeconfig and creates the KCM workload.
 
 5. After all the three components are ready, the NCP controller marks the NCP CR as ready.