✨ Update docs/Makefile

docs/Dockerfile

@@ -14,21 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Recommended usage:
-#
-# - Run an ephemeral container
-# - Mount the current working directory into the container.
-# - Run the entrypoint as the user invoking docker run. Otherwise the output
-#   files will be owned by root, the default user.
-#
-# - Example:
-# docker run \
-# 	--rm \
-# 	--volume ${PWD}:/figures \
-# 	--user $(id --user):$(id --group) \
-# 	${IMAGE_TAG} \
-# 	-v /figures/*.plantuml
-
+# To generate diagrams run 'make diagrams' in the docs/ folder.
 FROM maven:3-jdk-8
 
 RUN apt-get update && apt-get install -y --no-install-recommends graphviz=2.42.2-5 fonts-symbola=2.60-1.1 fonts-wqy-zenhei=0.9.45-8 && rm -rf /var/lib/apt/lists/*

docs/Makefile

@@ -12,10 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-ROOT_DIR:=$(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))
+SHELL:=/usr/bin/env bash
 
-SOURCES := $(shell find ${ROOT_DIR} -name \*.plantuml)
-DIAGRAMS := $(SOURCES:%.plantuml=%.png)
+.DEFAULT_GOAL:=help
+
+DIAGRAM_SRCS := $(call rwildcard,.,*.md,*.plantuml)
 
 # Hosts running SELinux need :z added to volume mounts
 SELINUX_ENABLED := $(shell cat /sys/fs/selinux/enforce 2> /dev/null || echo 0)
@@ -24,13 +25,26 @@ ifeq ($(SELINUX_ENABLED),1)
   DOCKER_VOL_OPTS?=:z
 endif
 
+##@ PlantUML diagrams
+
 .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' )
+diagrams: plantuml-builder  diagrams-book diagrams-proposals ## Make all diagrams
+
+.PHONY: diagrams-book
+diagrams-book: plantuml-builder ## Make all book diagrams
+	-docker run -u $(UID):$(GID) -v $(abspath .):/docs$(DOCKER_VOL_OPTS) plantuml-builder /docs/book/**/*.md
+	-docker run -u $(UID):$(GID) -v $(abspath .):/docs$(DOCKER_VOL_OPTS) plantuml-builder /docs/book/**/*.plantuml
+
+.PHONY: diagrams-proposals
+diagrams-proposals: plantuml-builder ## Make all proposals diagrams
+	-docker run -u $(UID):$(GID) -v $(abspath .):/docs$(DOCKER_VOL_OPTS) plantuml-builder /docs/proposals/**/*.md
+	-docker run -u $(UID):$(GID) -v $(abspath .):/docs$(DOCKER_VOL_OPTS) plantuml-builder /docs/proposals/**/*.plantuml
+
+.PHONY: plantuml-builder
+plantuml-builder: Dockerfile  ## Make diagram build container
+	docker build -f Dockerfile -t "plantuml-builder" .
+
+##@ general
+
+help:  ## Display this help
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z0-9_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

docs/proposals/images/cluster-class/create.plantuml

@@ -16,7 +16,7 @@ end box
 
 User -> "API Server" : Create Cluster object with\n""Cluster.Spec.Managed.Class""
 "API Server" --> "Cluster Controller": New Cluster
-opt Required only if Cluster.Spec.Managed.Class is set
+opt #white Required only if Cluster.Spec.Managed.Class is set
 "Cluster Controller" --> "API Server": Creates the infrastructure cluster
 "Cluster Controller" -> "Cluster Controller": Checks for\nCluster.Spec.ControlPlaneRef
 opt Required only if Cluster.Spec.ControlPlaneRef is not set

docs/proposals/images/cluster-class/update.plantuml

@@ -16,7 +16,7 @@ end box
 
 User -> "API Server" : Update Cluster object with\n""Cluster.Spec.Class""
 "API Server" --> "Cluster Controller": Existing Cluster
-opt Required only if Cluster.Spec.Class is set
+opt #white Required only if Cluster.Spec.Class is set
   "Cluster Controller" -> "Cluster Controller": Fetches the InfrastructureCluster object\nset in Cluster.spec.infrastructureRef
   opt Update the InfrastructureCluster
     "Cluster Controller" -> "Cluster Controller": Updates InfrastructureCluster fields

docs/proposals/images/cluster-spec-crds/figure1.plantuml

@@ -21,24 +21,24 @@ end box
 User -> "API Server" : Create Cluster Infrastructure
 "API Server" -->> "Infrastructure Controller": New Provider Infrastructure
 
-opt IF Infrastructure has no owner ref
+opt #white IF Infrastructure has no owner ref
 "Infrastructure Controller"->"Infrastructure Controller": Do Nothing
 end
 
 User -> "API Server": Create Cluster
 "API Server" -->> "Cluster Controller": New Cluster
 "Cluster Controller" -> "API Server": Get Infrastructure
-opt Required Only if Infrastructure not seen before
+opt #white Required Only if Infrastructure not seen before
 "Cluster Controller" -> "Cluster Controller": Add Watcher for Cluster.InfrastructureRef.Kind objects
 end
 
-opt Required Only if Infrastructure has no owner
+opt #white Required Only if Infrastructure has no owner
 "Cluster Controller" -> "Cluster Controller": Set Infrastructure's owner to Cluster
 "Cluster Controller" -> "API Server": Update Infrastructure
 end
 
 "API Server" -->> "Infrastructure Controller": Infrastructure update
-opt Required only if Infrastructure has owner ref
+opt #white Required only if Infrastructure has owner ref
 "Infrastructure Controller" -> "API Server": Get Cluster
 "Infrastructure Controller" -> "Infrastructure Controller": Provision infrastructure
 "Infrastructure Controller" -> "Infrastructure Controller": Set Infrastructure.Status.APIEndpoint
@@ -47,7 +47,7 @@ opt Required only if Infrastructure has owner ref
 end
 
 "API Server" -->> "Cluster Controller": Infrastructure Update
-opt Only required if Infrastructure.Status.Ready is true
+opt #white Only required if Infrastructure.Status.Ready is true
 "Cluster Controller" -> "API Server": Get Cluster
 "Cluster Controller" -> "Cluster Controller": Set Cluster.Status.APIEndpoint = Infrastructure.Status.APIEndpoint
 "Cluster Controller" -> "Cluster Controller": Set Cluster.Status.InfrastructureReady true

docs/proposals/images/controlplane/controlplane-init-1.plantuml

@@ -22,17 +22,17 @@ activate "Cluster API Cluster Controller"
 
 note over "Cluster API Cluster Controller": - ✅ Cluster.Status.InfrastructureReady is false\n- ✅ Cluster.Spec.ControlPlaneRef is populated\n- ✅ Cluster.Spec.ControlPlaneRef -> Status.Ready is false
 
-opt Required only if the object hasn't been seen before
+opt #white Required only if the object hasn't been seen before
 "Cluster API Cluster Controller"-> "Cluster API Cluster Controller":Add watcher for \nCluster.Spec.ControlPlaneRef.Kind objects
 end
 
-opt Required only if the infrastructure object doesn't have a Cluster owner reference
+opt #white Required only if the infrastructure object doesn't have a Cluster owner reference
 "Cluster API Cluster Controller"-> "Cluster API Cluster Controller":Set Cluster.Spec.InfrastructureRef -> OwnerReferences[0] to Cluster
 "Cluster API Cluster Controller"->"API Server": Patch AWSCluster
 "Cluster API Cluster Controller"<<--"API Server": Response
 end
 
-opt Required only if the control plane object doesn't have a Cluster owner reference
+opt #white Required only if the control plane object doesn't have a Cluster owner reference
 "Cluster API Cluster Controller"-> "Cluster API Cluster Controller":Set Cluster.Spec.ControlPlaneRef -> OwnerReferences[0] to Cluster
 "Cluster API Cluster Controller"->"API Server": Patch KubeadmControlPlane
 "Cluster API Cluster Controller"<<--"API Server": Response

docs/proposals/images/controlplane/controlplane-init-2.plantuml

@@ -32,7 +32,7 @@ note over "KubeadmControlPlane Controller": - ✅ Cluster.Status.InfrastructureR
 "KubeadmControlPlane Controller"->"API Server": Get Machines matching label selector
 "KubeadmControlPlane Controller"<<--"API Server": Response
 
-opt KubeadmControlPlane.Spec.Replicas >= 1, no existing Machines found
+opt #white KubeadmControlPlane.Spec.Replicas >= 1, no existing Machines found
 
 "KubeadmControlPlane Controller"->"API Server": Create KubeadmConfig from KubeadmControlPlane.Spec.KubeadmConfigSpec
 "KubeadmControlPlane Controller"<<--"API Server": Response

docs/proposals/images/controlplane/controlplane-init-3.plantuml

@@ -32,7 +32,7 @@ note over "KubeadmControlPlane Controller": - ✅ Cluster.Status.InfrastructureR
 "KubeadmControlPlane Controller"->"API Server": Get Machines matching label selector
 "KubeadmControlPlane Controller"<<--"API Server": Response
 
-opt KubeadmControlPlane.Spec.Replicas >= 1, 1 or more existing Machines found that is "Ready"
+opt #white KubeadmControlPlane.Spec.Replicas >= 1, 1 or more existing Machines found that is "Ready"
 
 "KubeadmControlPlane Controller"-> "KubeadmControlPlane Controller":Set KubeadmControlPlane.Status.Initialized = true
 

docs/proposals/images/controlplane/controlplane-init-4.plantuml

@@ -18,7 +18,7 @@ end box
 "Cluster API Cluster Controller"-> "Cluster API Cluster Controller":Cluster Controller Reconcile
 activate "Cluster API Cluster Controller"
 
-opt Cluster.Spec.ControlPlaneRef -> Status.Initialized is true
+opt #white Cluster.Spec.ControlPlaneRef -> Status.Initialized is true
 
 "Cluster API Cluster Controller"-> "Cluster API Cluster Controller":Set Cluster.Status.ControlPlaneInitialized = true
 

docs/proposals/images/controlplane/controlplane-init-6.plantuml

@@ -32,7 +32,7 @@ note over "KubeadmControlPlane Controller": - ✅ Cluster.Status.InfrastructureR
 "KubeadmControlPlane Controller"->"API Server": Get Machines matching label selector
 "KubeadmControlPlane Controller"<<--"API Server": Response
 
-opt KubeadmControlPlane.Spec.Replicas >= 1, all existing Machines "Ready", num Machines < Replicas
+opt #white KubeadmControlPlane.Spec.Replicas >= 1, all existing Machines "Ready", num Machines < Replicas
 
 "KubeadmControlPlane Controller"->"API Server": Create KubeadmConfig from KubeadmControlPlane.Spec.KubeadmConfigSpec
 "KubeadmControlPlane Controller"<<--"API Server": Response

docs/proposals/images/controlplane/controlplane-init-7.plantuml

@@ -38,7 +38,7 @@ note over "KubeadmControlPlane Controller": - ✅ Cluster.Status.InfrastructureR
 
 note over "KubeadmControlPlane Controller": - Process for selecting a Machine to delete is TBD
 
-opt KubeadmControlPlane.Spec.Replicas >= 1, all existing Machines "Ready", num Machines > Replicas
+opt #white KubeadmControlPlane.Spec.Replicas >= 1, all existing Machines "Ready", num Machines > Replicas
 
 "KubeadmControlPlane Controller"->"Workload Cluster API Server": Remove etcd Member
 

docs/proposals/images/machine-states-preboot/Figure3.plantuml

@@ -23,25 +23,25 @@ activate "Cluster API Machine Controller"
 
 note over "Cluster API Machine Controller": - ✅ Machine.Status.Phase is empty\n- ✅ Machine.Spec.Bootstrap.Data is <nil>\n- ✅ Machine.Spec.Bootstrap.ConfigRef is populated\n- ✅ Machine.Spec.Bootstrap.ConfigRef -> Status.Ready is false
 
-opt Required only if the object hasn't been seen before
+opt #white Required only if the object hasn't been seen before
 "Cluster API Machine Controller"-> "Cluster API Machine Controller":Add watcher for \nMachine.Spec.Bootstrap.ConfigRef.Kind objects
 end
 
-opt Required only if the object hasn't been seen before
+opt #white Required only if the object hasn't been seen before
 "Cluster API Machine Controller"-> "Cluster API Machine Controller":Add watcher for \nMachine.Spec.InfrastructureRef.Kind objects
 end
 
-opt Required only if the object hasn't been seen before
+opt #white Required only if the object hasn't been seen before
 "Cluster API Machine Controller"-> "Cluster API Machine Controller":Add watcher for \nMachine.Spec.Bootstrap.ConfigRef.Kind objects
 end
 
-opt Required only if the object doesn't have a Machine owner reference
+opt #white Required only if the object doesn't have a Machine owner reference
 "Cluster API Machine Controller"-> "Cluster API Machine Controller":Set Machine.Spec.Bootstrap.ConfigRef -> OwnerReferences[0] to Machine
 "Cluster API Machine Controller"->"API Server": Update KubeadmBootstrapConfig
 "Cluster API Machine Controller"<<--"API Server": Response
 end
 
-opt Required only if the object doesn't have a Machine owner reference
+opt #white Required only if the object doesn't have a Machine owner reference
 "Cluster API Machine Controller"-> "Cluster API Machine Controller":Set Machine.Spec.InfrastructureRef -> OwnerReferences[0] to Machine
 "Cluster API Machine Controller"->"API Server": Update AWSInfrastructureConfig
 "Cluster API Machine Controller"<<--"API Server": Response

docs/proposals/images/machine-states-preboot/Figure8.plantuml

@@ -25,7 +25,7 @@ activate "Cluster API Machine Controller"
 
 note over "Cluster API Machine Controller": - ✅ Machine.Status.Phase is "Provisioned" \n- ✅ Machine.Spec.InfrastructureRef -> Status.Ready is true\n- ✅ Machine.Spec.InfrastructureRef -> Status.Addresses is not empty
 
-loop until timeout or Node's status is Ready
+loop #white until timeout or Node's status is Ready
 "Cluster API Machine Controller"->"Workload Cluster API Server": Get Node
 "Cluster API Machine Controller"<<--"Workload Cluster API Server": Response
 note over "Cluster API Machine Controller":Loop conditions:\n- ✅ Node.Spec.ProviderID matches Machine.Spec.ProviderID\n- ✅ Node status is "Ready"

docs/proposals/images/machinepool-api/figure1.plantuml

@@ -30,55 +30,55 @@ end
 
 User -> "API Server": Create MachinePool
 "API Server" -->> "MachinePool Controller": New MachinePool
-opt Required Only if MachinePool has no owner
+opt #white Required Only if MachinePool has no owner
 "MachinePool Controller" -> "MachinePool Controller": Set MachinePool's owner to Cluster
 "MachinePool Controller" -> "MachinePool Controller": Set MachinePool.Status.Phase to Pending
 "MachinePool Controller" -> "API Server": Update MachinePool
 "MachinePool Controller" -> "API Server": Update MachinePool
 end
 
 "MachinePool Controller" -> "API Server": Get Bootstrap
-opt Required Only if Bootstrap has no owner
+opt #white Required Only if Bootstrap has no owner
 "MachinePool Controller" -> "MachinePool Controller": Set Bootstrap's owner to MachinePool
 "MachinePool Controller" -> "API Server": Update Bootstrap
 end
-opt Required Only if Bootstrap not seen before
+opt #white Required Only if Bootstrap not seen before
 "MachinePool Controller" -> "MachinePool Controller": Add Watcher for MachinePool.Template.Bootstrap.Kind objects
 end
 
-opt If MachinePool in Pending state
+opt #white If MachinePool in Pending state
 "Bootstrap Controller"->"Bootstrap Controller": Generate BootstrapConfig.Status.BootstrapData
 "Bootstrap Controller"->"Bootstrap Controller": Set BootstrapConfig.Status.Ready=true
 end
 
-opt If Bootstrap has no Data and Status.BootstrapData
+opt #white If Bootstrap has no Data and Status.BootstrapData
 "MachinePool Controller"->"MachinePool Controller": Requeue
 end
 
-opt If Bootstrap has Data
+opt #white If Bootstrap has Data
 "MachinePool Controller" -> "MachinePool Controller": Set MachinePool.Status.BootstrapReady=true
 "MachinePool Controller" -> "API Server": Update MachinePool
 end
 
-opt If MachinePool.Template.Bootstrap.Data is empty
+opt #white If MachinePool.Template.Bootstrap.Data is empty
 "MachinePool Controller" -> "Bootstrap Controller": Get BootstrapConfig.Status.BootstrapData
 "MachinePool Controller" -> "MachinePool Controller": Set MachinePool.Template.Bootstrap.Data
 "MachinePool Controller" -> "MachinePool Controller": Set MachinePool.Status.BootstrapReady=true
 "MachinePool Controller" -> "API Server": Update MachinePool
 end
 
 "MachinePool Controller" -> "API Server": Get Infrastructure
-opt Required Only if Infrastructure has no owner
+opt #white Required Only if Infrastructure has no owner
 "MachinePool Controller" -> "MachinePool Controller": Set Infrastructure's owner to MachinePool
 "MachinePool Controller" -> "MachinePool Controller": Set MachinePool.Status.Phase to Provisioning
 "MachinePool Controller" -> "API Server": Update Infrastructure
 end
-opt Required Only if Infrastructure not seen before
+opt #white Required Only if Infrastructure not seen before
 "MachinePool Controller" -> "MachinePool Controller": Add Watcher for MachinePool.Template.InfrastructureRef.Kind objects
 end
 
 "API Server" -->> "Infrastructure Controller": Infrastructure Update
-opt Required only if Infrastructure has owner ref
+opt #white Required only if Infrastructure has owner ref
 "Infrastructure Controller" -> "API Server": Get MachinePool
 "Infrastructure Controller" -> "Infrastructure Controller": Provision infrastructure
 "Infrastructure Controller" -> "Infrastructure Controller": Set Infrastructure.Status.Replicas
@@ -87,23 +87,23 @@ opt Required only if Infrastructure has owner ref
 end
 
 "API Server" -->> "MachinePool Controller": Infrastructure Update
-opt Only required if Infrastructure.Status.Ready is true
+opt #white Only required if Infrastructure.Status.Ready is true
 "MachinePool Controller" -> "API Server": Get MachinePool
 "MachinePool Controller" -> "MachinePool Controller": Set MachinePool.Status.Replicas = Infrastructure.Status.Replicas
 "MachinePool Controller" -> "MachinePool Controller": Set MachinePool.Status.InfrastructureReady = Infrastructure.Status.Ready
 "MachinePool Controller" -> "API Server": Update MachinePool
 end
 
-opt If MachinePool.Status.Ready is true MachinePool.Spec.Replicas != MachinePool.Status.AvailableReplicas
+opt #white If MachinePool.Status.Ready is true MachinePool.Spec.Replicas != MachinePool.Status.AvailableReplicas
 "MachinePool Controller" -> "API Server": Get Nodes with MachinePool.Spec.Selector
 "MachinePool Controller" -> "MachinePool Controller": Update MachinePool.Status UpdatedReplicas, ReadyReplicas, AvailableReplicas, and UnavailableReplicas
 end
 
-opt If MachinePool.Status.Ready is true MachinePool.Spec.Replicas != MachinePool.Status.AvailableReplicas
+opt #white If MachinePool.Status.Ready is true MachinePool.Spec.Replicas != MachinePool.Status.AvailableReplicas
 "MachinePool Controller"->"MachinePool Controller": Requeue
 end
 
-opt If MachinePool.Status.Ready is true MachinePool.Spec.Replicas == MachinePool.Status.AvailableReplicas
+opt #white If MachinePool.Status.Ready is true MachinePool.Spec.Replicas == MachinePool.Status.AvailableReplicas
 "MachinePool Controller"->"API Server": Set MachinePool.Status.Phase to "Running"
 end
 

docs/proposals/images/topology-mutation-hook/topology-reconciliation.plantuml

@@ -26,7 +26,7 @@ activate "API Server"
 "API Server" -> "Cluster Topology Controller":
 deactivate "API Server"
 
-group Compute desired State
+group #white Compute desired State
   "Cluster Topology Controller" -> "Cluster Topology Controller": Compute desired State
   loop Ordered list of Patches
     alt