NestedControlPlane & NestedCluster Proposal

docs/Makefile

@@ -0,0 +1,36 @@
+# Copyright 2019 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+ROOT_DIR:=$(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))
+
+SOURCES := $(shell find ${ROOT_DIR} -name \*.plantuml)
+DIAGRAMS := $(SOURCES:%.plantuml=%.png)
+
+# Hosts running SELinux need :z added to volume mounts
+SELINUX_ENABLED := $(shell cat /sys/fs/selinux/enforce 2> /dev/null || echo 0)
+
+ifeq ($(SELINUX_ENABLED),1)
+  DOCKER_VOL_OPTS?=:z
+endif
+
+.PHONY: diagrams
+diagrams: $(DIAGRAMS)
+
+%.png: %.plantuml
+	docker run \
+		--rm \
+		--volume ${ROOT_DIR}:/workdir$(DOCKER_VOL_OPTS) \
+		--user $(shell id -u):$(shell id -g) \
+		k8s.gcr.io/cluster-api/plantuml:1.2019.6 \
+		-v /workdir/$(shell echo '$^' | sed -e 's,.*docs/,,g' )

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

@@ -146,7 +146,7 @@ The component controller will create the component under the in-tree mode, which
 
 Each component's controller will generate necessary certificates for the component and store them to the [secret resources](https://cluster-api.sigs.k8s.io/tasks/certs/using-custom-certificates.html) defined by CAPI. Also, The KAS controller will store the content of the kubeconfig file in a secret named `[clustername]-kubeconfig`.
 
-![Control Plane Creating Process](in-tree.png)
+![Control Plane Creating Process](images/componentcontrollers/in-tree.png)
 
 The creating process will include six steps:
 
@@ -164,7 +164,7 @@ The creating process will include six steps:
 
 If users intend to use an external controller to create the NCP component, they may need to implement a new component controller that can interact with the component CR and the external controller to create the component. For example, if the user wanted to use the [etcd-cluster-operator](https://github.com/improbable-eng/etcd-cluster-operator) that requires the [EtcdCluster](https://github.com/improbable-eng/etcd-cluster-operator/blob/master/api/v1alpha1/etcdcluster_types.go) CR. They need to implement a custom controller that watches the `NestedEtcd` resource, creates the necessary CRs for that implementation, and updates the required status fields on `NestedEtcd` to allow dependent services to be provisioned. This can be done using the [kubebuilder-declarative-pattern](https://github.com/kubernetes-sigs/kubebuilder-declarative-pattern) like is done for in-tree component controllers.
 
-![Creating a Control Plane using out-of-tree provisioners](out-of-tree.png)
+![Creating a Control Plane using out-of-tree provisioners](images/componentcontrollers/out-of-tree.png)
 
 In the following example, we assume that the user intends to use Etcd-cluster-operator(ECO) as the Etcd controller. The creating process will include seven steps:
 
@@ -203,11 +203,11 @@ type NestedEtcdStatus struct {
     // Ready is set if all resources have been created
     Ready bool `json:"ready,omitempty"`
 
-    // EtcdDomain defines how to address the etcd instance
+    // Addresses defines how to address the etcd instance
     Addresses []NestedEtcdAddress `json:"addresses,omitempty"`
 
     // CommonStatus allows addons status monitoring 
-    addonv1alpha1. CommonStatus `json:",inline"`
+    addonv1alpha1.CommonStatus `json:",inline"`
 }
 
 // EtcdAddress defines the observed addresses for etcd

docs/proposals/images/nestedcontrolplane/nc-activity.plantuml

@@ -0,0 +1,81 @@
+@startuml
+skinparam roundcorner 20
+skinparam ParticipantPadding 20
+skinparam BoxPadding 50
+skinparam Shadowing false
+skinparam NoteBorderColor #444
+skinparam NoteBackgroundColor #fff
+skinparam NoteFontColor #444
+skinparam EntityBackgroundColor #fff
+skinparam EntityBorderColor #444
+skinparam ArrowFontColor #444
+skinparam ArrowColor #444
+skinparam ArrowLollipopColor #444
+skinparam ArrowThickness 1
+skinparam ControlBorderColor #444
+skinparam ControlBackgroundColor #fff
+skinparam ParticipantBorderColor #444
+skinparam ParticipantBackgroundColor #fff
+skinparam ParticipantFontSize 17
+skinparam ParticipantFontColor #444
+skinparam ActorBorderColor #444
+skinparam ActorFontColor #444
+skinparam ActorFontSize 17
+skinparam ActorBackgroundColor #fff
+skinparam GroupBorderColor #444
+skinparam GroupBorderThickness 1
+skinparam GroupHeaderFontColor #444
+skinparam GroupFontColor #444
+skinparam SequenceLifeLineBorderColor #444
+skinparam ActivityBorderColor #444
+skinparam ActivityBackgroundColor #fff
+skinparam ActivityDiamondBorderColor #444
+skinparam ActivityDiamondBackgroundColor #fff
+
+title NestedCluster Creation
+
+start
+
+if (NC exists?) then (no)
+    :return nil;
+    end
+else (yes)
+endif
+
+if (deletionTimestamp?) then (yes)
+    :handle deletion;
+    end
+else (no)
+endif
+
+if (owningCluster exists?) then (no)
+    :return nil;
+    end
+else (yes)
+endif
+
+if (cluster paused?) then (yes)
+    :return nil;
+    end
+else (no)
+endif
+
+if (controlPlane exists?) then (no)
+    :return failed to get control plane;
+    end
+endif
+
+:set cluster.Status.Ready == ncp.Status.Ready;
+:set cluster.Spec.ControlPlaneEndpoint == ncp.Spec.ControlPlaneEndpoint;
+
+:patch cluster;
+if (errors?) then (yes)
+    :return error;
+    end
+endif
+
+:return nil;
+
+end
+
+@enduml

docs/proposals/images/nestedcontrolplane/ncp-activity.plantuml

@@ -0,0 +1,117 @@
+@startuml
+skinparam roundcorner 20
+skinparam ParticipantPadding 20
+skinparam BoxPadding 50
+skinparam Shadowing false
+skinparam NoteBorderColor #444
+skinparam NoteBackgroundColor #fff
+skinparam NoteFontColor #444
+skinparam EntityBackgroundColor #fff
+skinparam EntityBorderColor #444
+skinparam ArrowFontColor #444
+skinparam ArrowColor #444
+skinparam ArrowLollipopColor #444
+skinparam ArrowThickness 1
+skinparam ControlBorderColor #444
+skinparam ControlBackgroundColor #fff
+skinparam ParticipantBorderColor #444
+skinparam ParticipantBackgroundColor #fff
+skinparam ParticipantFontSize 17
+skinparam ParticipantFontColor #444
+skinparam ActorBorderColor #444
+skinparam ActorFontColor #444
+skinparam ActorFontSize 17
+skinparam ActorBackgroundColor #fff
+skinparam GroupBorderColor #444
+skinparam GroupBorderThickness 1
+skinparam GroupHeaderFontColor #444
+skinparam GroupFontColor #444
+skinparam SequenceLifeLineBorderColor #444
+skinparam ActivityBorderColor #444
+skinparam ActivityBackgroundColor #fff
+skinparam ActivityDiamondBorderColor #444
+skinparam ActivityDiamondBackgroundColor #fff
+
+title NestedControlPlane Creation
+
+start
+
+if (NCP exists?) then (no)
+    :return nil;
+    end
+else (yes)
+endif
+
+if (deletionTimestamp?) then (yes)
+    :handle deletion;
+    end
+endif
+
+if (component CRs exist?) then (no)
+    :emit event;
+    :return retryAfter;
+    end
+else (yes)
+    if (has ownerReferences?) then (no)
+        :setup OwnerReferences back;
+    endif
+endif
+
+if (cluster CA/Certs exists?) then (no)
+    :call secret.NewCertificatesForInitialControlPlane;
+    :store certs as secrets;
+    if (errors?) then (yes)
+        :return err;
+        end
+    elseif (error with Conflicts?) then (yes)
+        :return retryAfter;
+        end
+    else (no)
+    endif
+endif
+
+if (ControlPlaneEndpoint set?) then (no)
+    :return nil;
+    end
+endif
+
+
+if (admin kubeconfig exists?) then (no)
+    :get ControlPlaneEndpoint;
+    :create kubeconfig;
+    if (errors?) then (yes)
+        :return err;
+        end
+    endif
+elseif (kubeconfig owned?) then (no)
+    :adopt kubeconfig;
+else (yes)
+    if (certs need rotation?) then (yes)
+        :regenerate and store;
+        if (errors?) then (yes)
+        :return err;
+        end
+    endif
+    endif
+endif
+
+if (conditions updated?) then (no)
+    if (etcd managed?) then (yes)
+        :try to fetch common status fields;
+        if (errors?) then (yes)
+            :set etcd as unknown state;
+        endif
+    endif
+    :get nested component statuses;
+    :update NestedControlPlane status;
+    if (errors?) then (yes)
+        :return err;
+        end
+    endif
+endif
+
+:return nil;
+
+end
+
+@enduml