documentation for images

6 files changed, 148 insertions, 0 deletions

diff --git a/keps/sig-cluster-lifecycle/0023-documentation-for-images.md b/keps/sig-cluster-lifecycle/0023-documentation-for-images.md
new file mode 100644
index 00000000..c0ae3b8d
--- /dev/null
+++ b/keps/sig-cluster-lifecycle/0023-documentation-for-images.md
@@ -0,0 +1,148 @@
+
+
+# Documentation for images
+
+Open https://www.websequencediagrams.com/ and paste the spec for the desired image:
+
+- [kubeadm init](#kubeadm-init)
+- [kubeadm join (and join --control-plane)](#kubeadm-join-and-join---control-plane)
+- [kubeadm reset](#kubeadm-reset)
+- [kubeadm upgrade](#kubeadm-upgrade)
+- [kubeadm upgrade node](#kubeadm-upgrade-node)
+
+## kubeadm init
+
+```
+title kubeadm init (interactions with the v1beta1 configuration)
+
+participant "user" as u 
+participant "kubeadm" as k
+participant "kubelet" as kk
+participant "node\n(api object)" as n
+participant "kubeadm-config\nConfigMap" as cm
+participant "kubeproxy-config\nConfigMap" as kpcm 
+participant "kubelet-config\nConfigMap-1.*" as kcm
+
+u->k:provide\nInitConfiguration (with NodeRegistrationOptions, ControlPlaneConfiguration)\nClusterConfiguration\nkube-proxy component configuration\nkubelet component configuration 
+
+k->kk:write kubelet component configuration\nto /var/lib/kubelet/config.yaml
+k->kk:write NodeRegistrationOptions\nto /var/lib/kubelet/kubeadm-flags.env
+kk->n:start node
+k->n:save NodeRegistrationOptions.CRISocket\nto kubeadm.alpha.kubernetes.io/cri-socket annotation 
+
+k->k:use InitConfiguration\n(e.g. tokens)
+
+k->cm:save ClusterConfiguration
+k->cm:add Current ControlPlaneConfiguration to ClusterConfiguration.Status
+
+k->kpcm:save kube-proxy component configuration 
+k->kcm:save kubelet component configuration 
+```
+
+## kubeadm join (and join --control-plane)
+
+```
+title kubeadm join and join --control-plane (interactions with the v1beta1 configuration)
+
+participant "user" as u 
+participant "kubeadm" as k
+participant "kubeadm-config\nConfigMap" as cm
+participant "kubelet-config\nConfigMap-1.*" as kcm
+participant "kubelet" as kk
+participant "node\n(api object)" as n
+
+u->k:provide\nJoinConfiguration\n(with NodeRegistrationOptions) 
+
+k->cm:read ClusterConfiguration
+cm->k:
+k->k:use ClusterConfiguration\n(e.g. ClusterName)
+
+k->kcm:read kubelet\ncomponent configuration
+kcm->k:
+k->kk:write kubelet component configuration\nto /var/lib/kubelet/config.yaml
+k->kk:write NodeRegistrationOptions\nto /var/lib/kubelet/kubeadm-flags.env
+kk->n:start node
+k->n:save NodeRegistrationOptions.CRISocket\nto kubeadm.alpha.kubernetes.io/cri-socket annotation 
+
+k->cm:add new ControlPlaneConfiguration\nto ClusterConfiguration.Status\n(only for join --control-plane)
+```
+
+## kubeadm reset 
+
+```
+title kubeadm reset (interactions with the v1beta1 configuration)
+
+participant "user" as u 
+participant "kubeadm" as k
+participant "kubeadm-config\nConfigMap" as cm
+participant "node\n(api object)" as n
+
+
+u->k: 
+
+k->cm:read ClusterConfiguration
+cm->k:
+k->cm:remove ControlPlaneConfiguration\nfrom ClusterConfiguration.Status\n(only if the node hosts a control plane instance)
+
+k->n:read kubeadm.alpha.kubernetes.io/cri-socket annotation 
+n->k:
+k->k:use CRIsocket\nto delete containers
+```
+
+## kubeadm upgrade
+
+```
+title kubeadm upgrade apply (interactions with the v1beta1 configuration)
+
+participant "user" as u 
+participant "kubeadm" as k
+participant "kubeadm-config\nConfigMap" as cm
+participant "kubeproxy-config\nConfigMap" as kpcm 
+participant "kubelet-config\nConfigMap-1.*+1" as kcm
+participant "kubelet" as kk
+participant "node\n(api object)" as n
+
+u->k: UpgradeConfiguration
+note over u, n:Upgrade configuration should allow only well known changes to the cluster e.g. the change of custom images if used
+
+
+k->cm:read ClusterConfiguration
+cm->k:
+k->k:update\nClusterConfiguration\nusing api machinery
+k->cm:save updated ClusterConfiguration
+
+k->kpcm:read kube-proxy component configuration
+kpcm->k:
+k->k:update kube-proxy\ncomponent configuration\nusing api machinery
+k->kpcm:save updated kube-proxy component configuration
+note over kpcm, n:the updated kube-proxy component configuration will\nbe used by the updated kube-proxy DaemonSet 
+
+k->kcm:read kubelet component configuration
+kcm->k:
+k->k:update kubelet\ncomponent configuration\nusing api machinery
+k->kcm:save updated kubelet component configuration 
+k->kk:write kubelet component configuration\nto /var/lib/kubelet/config.yaml
+k->kk:write NodeRegistrationOptions\nto /var/lib/kubelet/kubeadm-flags.env
+kk->n:start node
+
+note over kcm, n:the updated kubelet component configuration\nwill be used by other nodes\nwhen running\nkubeadm upgrade nodes locally 
+
+```
+
+## kubeadm upgrade node
+
+```
+title kubeadm upgrade node (interactions with the v1beta1 configuration)
+
+participant "user" as u 
+participant "kubeadm" as k
+participant "kubelet-config\nConfigMap-1.*" as kcm
+participant "kubelet" as kk
+
+u->k: 
+
+k->kcm:read kubelet\ncomponent configuration
+kcm->k:
+k->kk:write kubelet component configuration\nto /var/lib/kubelet/config.yaml
+```
+
diff --git a/keps/sig-cluster-lifecycle/0023-kubeadm-init.png b/keps/sig-cluster-lifecycle/0023-kubeadm-init.png
index 9f7e97f1..69c402a9 100644
--- a/keps/sig-cluster-lifecycle/0023-kubeadm-init.png
+++ b/keps/sig-cluster-lifecycle/0023-kubeadm-init.png
diff --git a/keps/sig-cluster-lifecycle/0023-kubeadm-join.png b/keps/sig-cluster-lifecycle/0023-kubeadm-join.png
index 3a4b5d43..06bd0cef 100644
--- a/keps/sig-cluster-lifecycle/0023-kubeadm-join.png
+++ b/keps/sig-cluster-lifecycle/0023-kubeadm-join.png
diff --git a/keps/sig-cluster-lifecycle/0023-kubeadm-reset.png b/keps/sig-cluster-lifecycle/0023-kubeadm-reset.png
index cedb3a71..9cd4dfe2 100644
--- a/keps/sig-cluster-lifecycle/0023-kubeadm-reset.png
+++ b/keps/sig-cluster-lifecycle/0023-kubeadm-reset.png
diff --git a/keps/sig-cluster-lifecycle/0023-kubeadm-upgrade-apply.png b/keps/sig-cluster-lifecycle/0023-kubeadm-upgrade-apply.png
index a573f2bb..2ecbcc75 100644
--- a/keps/sig-cluster-lifecycle/0023-kubeadm-upgrade-apply.png
+++ b/keps/sig-cluster-lifecycle/0023-kubeadm-upgrade-apply.png
diff --git a/keps/sig-cluster-lifecycle/0023-kubeadm-upgrade-node.png b/keps/sig-cluster-lifecycle/0023-kubeadm-upgrade-node.png
index 2d6cbe2a..235ecece 100644
--- a/keps/sig-cluster-lifecycle/0023-kubeadm-upgrade-node.png
+++ b/keps/sig-cluster-lifecycle/0023-kubeadm-upgrade-node.png