docs: add an architecture diagram

Signed-off-by: Suleyman Akbas <[email protected]>

README.md

@@ -7,7 +7,7 @@ This allows applications running on the cluster to consume storage from LVM logi
 
 The LVM Operator, in conjunction with the TopoLVM CSI Driver, Volume Group Manager, and other related components, collectively comprise the Logical Volume Manager Storage (LVMS) solution.
 
-Here is a brief overview of the operator:
+Here is a brief overview of how the Operator works. See [here](docs/design/architecture.md) for the architecture diagram.
 
 ```mermaid
 graph LR
@@ -36,9 +36,9 @@ end
 - [Deploying the LVM Operator](#deploying-the-lvm-operator)
     * [Using the pre-built images](#using-the-pre-built-images)
     * [Building the Operator yourself](#building-the-operator-yourself)
-    * [Deploying the operator](#deploying-the-operator)
+    * [Deploying the Operator](#deploying-the-operator)
     * [Inspecting the storage objects on the node](#inspecting-the-storage-objects-on-the-node)
-    * [Testing the operator](#testing-the-operator)
+    * [Testing the Operator](#testing-the-operator)
 - [Cleanup](#cleanup)
 - [Metrics](#metrics)
 - [Known Limitations](#known-limitations)
@@ -56,7 +56,7 @@ If you are comfortable using the pre-built images, simply proceed with the [depl
 
 ### Building the Operator yourself
 
-To build the operator, install Docker or Podman and log into your registry.
+To build the Operator, install Docker or Podman and log into your registry.
 
 1. Set the following environment variables to the repository where you want to host your image:
 
@@ -94,7 +94,7 @@ If you intend to deploy the Operator using the Operator Lifecycle Manager (OLM),
 
 Ensure that the OpenShift cluster has read access to that repository. Once this is complete, you are ready to proceed with the next steps.
 
-### Deploying the operator
+### Deploying the Operator
 
 You can begin the deployment by running the following command:
 
@@ -209,7 +209,7 @@ sh-4.4# lvs
   thin-pool-1 vg1 twi-a-tz-- <3.93t             0.00   1.19      
 ```
 
-### Testing the operator
+### Testing the Operator
 
 Once you have completed [the deployment steps](#deploying-the-operator), you can proceed to create a basic test application that will consume storage.
 
@@ -318,7 +318,7 @@ To perform a full cleanup, follow these steps:
 
 ## Metrics
 
-To enable monitoring on OpenShift clusters, you must assign the label `openshift.io/cluster-monitoring` to the namespace in which LVMS is running.
+The LVM Operator runs a metrics exporter sidecar to export Prometheus metrics. To enable monitoring on OpenShift clusters, assign the `openshift.io/cluster-monitoring` label to the same namespace that you deployed LVMS to.
 
 ```bash
 $ oc patch namespace/openshift-storage -p '{"metadata": {"labels": {"openshift.io/cluster-monitoring": "true"}}}'

controllers/lvmcluster_controller.go

@@ -335,7 +335,7 @@ func (r *LVMClusterReconciler) getExpectedVgCount(ctx context.Context, instance
 	return vgCount, nil
 }
 
-// NOTE: when updating this, please also update docs/design/reconciler.md
+// NOTE: when updating this, please also update docs/design/lvm-operator-manager.md
 type resourceManager interface {
 
 	// getName should return a camelCase name of this unit of reconciliation

docs/README.md

@@ -1,6 +1,6 @@
 # Contents
 
-1. [Reconciler Design](design/reconciler.md)
+1. [Reconciler Design](design/architecture.md)
 2. [The LVM Operator Manager](design/lvm-operator-manager.md)
 2. [The Volume Group Manager](design/vg-manager.md)
 5. [Thin Provisioning](design/thin-provisioning.md)

docs/design/architecture.md

@@ -0,0 +1,23 @@
+# Logical Volume Manager Storage (LVMS) Architecture
+
+![component diagram](http://www.plantuml.com/plantuml/png/VLDDIyD04BtlhnZgHGyzA8gGWxHDn8jLQBKUf8SbcQR1pSwIdHH4_Eysss087VOwxoDltcHdddN3RMsKSZh_qYN2v7cpN4DAjIEBblq4VXJ0vt4AhmuRpTHi-q5gMi_Om6MwogwsS37Fikl5JGTkoBGrmbD3hOEbjaVZVzK92v2W71DUgC0rQswzG7qZHrsib2mtP4pun33kj5lrEzxiRB5HL7_qNzpExn_lGXGggrmRE346hFCSzm7JwOEO1nB8q1dwzb55Y1hdYfN6DTAD4lZGdEzHvilNII1jK3DwK6eKEQY4dWQ1jWNK8Qi7qzCE9vfIyafICuEXETG5v6HtLGcxoc34vEoqIG_xFWAK0GWXULzPS4J6ouvYGKAfKMtypqxWtHMQGpDnRkIwAzmPpDa3xn5yq2WrGrjqR_mF)
+
+The following table provides a view of the containers in these components:
+
+| Component            | Kind       | Containers                                                                                          |
+|----------------------|------------|-----------------------------------------------------------------------------------------------------|
+| LVM Operator         | Deployment | [manager](lvm-operator-manager.md)                                                                  |
+|                      |            | [kube-rbac-proxy](https://github.com/brancz/kube-rbac-proxy#kube-rbac-proxy)                        |
+|                      |            | [metricsexporter](../../README.md#metrics)                                                          |
+| Volume Group Manager | DaemonSet  | [vg-manager](vg-manager.md)                                                                         |
+| TopoLVM Controller   | Deployment | [topolvm-controller](https://github.com/topolvm/topolvm/blob/main/docs/topolvm-controller.md)       |
+|                      |            | [csi-provisioner](https://github.com/kubernetes-csi/external-provisioner/blob/master/doc/design.md) |
+|                      |            | [csi-resizer](https://github.com/kubernetes-csi/external-resizer#csi-resizer)                       |
+|                      |            | [liveness-probe](https://github.com/kubernetes-csi/livenessprobe#liveness-probe)                    |
+|                      |            | [csi-snapshotter](https://github.com/kubernetes-csi/external-snapshotter#csi-snapshotter)           |
+| TopoLVM Node         | DaemonSet  | [topolvm-node](https://github.com/topolvm/topolvm/blob/main/docs/topolvm-node.md)                   |
+|                      |            | [lvmd](https://github.com/topolvm/topolvm/blob/main/docs/lvmd.md)                                   |
+|                      |            | [csi-registrar](https://github.com/kubernetes-csi/node-driver-registrar#node-driver-registrar)      |
+|                      |            | [liveness-probe](https://github.com/kubernetes-csi/livenessprobe#liveness-probe)                    |
+
+This architecture diagram describes how the LVMS components work together to enable dynamic provisioning and management of logical volumes using Logical Volume Manager (LVM) in OpenShift clusters. See also [this page](https://github.com/topolvm/topolvm/blob/main/docs/design.md) for further details on the TopoLVM design. 

docs/design/lvm-operator-manager.md

@@ -58,3 +58,27 @@ The `lvmVG` reconcile unit is responsible for deploying and managing the LVMVolu
 ## Openshift Security Context Constraints (SCCs)
 
 The Operator requires elevated permissions to interact with the host's LVM commands, which are executed through `nsenter`. When deployed on an OpenShift cluster, all the necessary Security Context Constraints (SCCs) are created by the `openshiftSccs` reconcile unit. This ensures that the `vg-manager`, `topolvm-node`, and `lvmd` containers have the required permissions to function properly.
+
+## Implementation Notes
+
+Each unit of reconciliation should implement the `reconcileUnit` interface. This is run by the controller. Errors and success messages are propagated as Operator status and events. This interface is defined in [lvmcluster_controller.go](../../controllers/lvmcluster_controller.go)
+
+```go
+type resourceManager interface {
+
+	// getName should return a camelCase name of this unit of reconciliation
+	getName() string
+
+	// ensureCreated should check the resources managed by this unit
+	ensureCreated(*LVMClusterReconciler, context.Context, lvmv1alpha1.LVMCluster) error
+
+	// ensureDeleted should wait for the resources to be cleaned up
+	ensureDeleted(*LVMClusterReconciler, context.Context, lvmv1alpha1.LVMCluster) error
+
+	// updateStatus should optionally update the CR's status about the health of the managed resource
+	// each unit will have updateStatus called induvidually so
+	// avoid status fields like lastHeartbeatTime and have a
+	// status that changes only when the operands change.
+	updateStatus(*LVMClusterReconciler, context.Context, lvmv1alpha1.LVMCluster) error
+}
+```

docs/design/vg-manager.md

@@ -1,6 +1,6 @@
 # The Volume Group Manager
 
-The Volume Group Manager manages a single controller/reconciler, which runs as `vg-manager` daemon set pods on a cluster. They are responsible for performing on-node operations for the node they are running on. They first identify disks that match the filters specified for the node. Next, they watch for the LVMVolumeGroup resource and create the necessary volume groups and thin pools on the node based on the specified deviceSelector and nodeSelector. Once the volume groups are created, vg-manager generates the `lvmd.yaml` configuration file for lvmd to use. Additionally, vg-manager updates the LVMVolumeGroupStatus with the observed status of the volume groups on the node where it is running.
+The Volume Group Manager manages a single controller/reconciler, which runs as `vg-manager` daemon set pods on a cluster. They are responsible for performing on-node operations for the node they are running on. They first identify disks that match the filters specified for the node. Next, they watch for the LVMVolumeGroup resource and create the necessary volume groups and thin pools on the node based on the specified deviceSelector and nodeSelector. Once the volume groups are created, vg-manager generates the `lvmd.yaml` configuration file for lvmd to use. Additionally, vg-manager updates the LVMVolumeGroupNodeStatus with the observed status of the volume groups on the node where it is running.
 
 ## Deletion