Merge branch 'main' into hp_section

Author: noctarius

docs/deployments/kubernetes/install-csi.md

@@ -169,7 +169,7 @@ To enable interaction with multiple clusters, there are two key changes:
 
 When the Simplyblock CSI driver is initially installed, only a single cluster can be referenced.
 
-```
+```bash title="Install the Simplyblock CSI driver via Helm"
 helm install simplyblock-csi ./ \
     --set csiConfig.simplybk.uuid=${CLUSTER_ID} \
     --set csiConfig.simplybk.ip=${CLUSTER_IP} \
@@ -210,12 +210,14 @@ To add a new cluster, the current secret must be retrieved from Kubernetes, edit
 and uploaded to the Kubernetes cluster.  
 
 
-```sh
+```bash
 # Save cluster secret to a file
-kubectl get secret simplyblock-csi-secret-v2 -o jsonpath='{.data.secret\.json}' | base64 --decode > secret.yaml
+kubectl get secret simplyblock-csi-secret-v2 \
+    -o jsonpath='{.data.secret\.json}' |\
+    base64 --decode > secret.yaml
 
-# Edit the clusters and add the new cluster's cluster_id, cluster_endpoint, cluster_secret
-# vi secret.json 
+# Edit the clusters and add the new cluster's cluster_id,
+# cluster_endpoint, cluster_secret vi secret.json 
 
 cat secret.json | base64 | tr -d '\n' > secret-encoded.json
 
@@ -227,12 +229,10 @@ kubectl -n simplyblock edit secret simplyblock-csi-secret-v2
 
 #### Option 1: Cluster ID–Based Method (One StorageClass per Cluster)
 
-In this approach, each SimplyBlock cluster has its own dedicated StorageClass that specifies which cluster to use for provisioning.
+In this approach, each simplyblock cluster has its own dedicated StorageClass that specifies which cluster to use for provisioning.
 This is ideal for setups where workloads are manually directed to specific clusters.
 
-For example:
-
-```yaml
+```yaml title="Example of Cluster ID-Based Selection"
 apiVersion: storage.k8s.io/v1
 kind: StorageClass
 metadata:
@@ -248,7 +248,7 @@ allowVolumeExpansion: true
 
 You can define another StorageClass for a different cluster:
 
-```yaml
+```yaml title="Example of selecting another cluster"
 apiVersion: storage.k8s.io/v1
 kind: StorageClass
 metadata:
@@ -263,26 +263,24 @@ allowVolumeExpansion: true
 ```
 
 Each StorageClass references a unique cluster_id.
-The CSI driver uses that ID to determine which SimplyBlock cluster to connect to.
+The CSI driver uses that ID to determine which simplyblock cluster to connect to.
 
 #### Option 2: Zone-Aware Method (Automatic Multi-Cluster Selection)
 
-This approach allows a single StorageClass to automatically select the appropriate SimplyBlock cluster based on the Kubernetes zone where the workload runs.
-It is recommended for multi-zone Kubernetes deployments that span multiple SimplyBlock clusters.
+This approach allows a single StorageClass to automatically select the appropriate simplyblock cluster based on the Kubernetes zone where the workload runs.
+It is recommended for multi-zone Kubernetes deployments that span multiple simplyblock clusters.
 
 `storageclass.zoneClusterMap`
 
-Sets the mapping between Kubernetes zones and SimplyBlock cluster IDs.
+Sets the mapping between Kubernetes zones and simplyblock cluster IDs.
 Each zone is associated with one cluster.
 
 `storageclass.allowedTopologyZones`
 
 Sets the list of zones where the StorageClass is permitted to provision volumes.
 This ensures that scheduling aligns with the clusters defined in `zoneClusterMap`.
 
-example:
-
-```yaml
+```yaml title="Example of zoneClusterMap usage"
 apiVersion: storage.k8s.io/v1
 kind: StorageClass
 metadata:
@@ -303,4 +301,53 @@ allowedTopologies:
       - us-east-1b
 ```
 
-This method allows Kubernetes to automatically pick the right cluster based on the pod’s scheduling zone.
+This method allows Kubernetes to automatically pick the right cluster based on the pod’s scheduling zone.
+
+#### Option 3: Region-Aware Method (Automatic Multi-Cluster Selection)
+
+This approach allows a single StorageClass to automatically select the appropriate simplyblock cluster based on the Kubernetes region where the workload runs.
+It’s recommended when:
+
+- your cluster spans multiple regions, and
+
+- each region maps to a different simplyblock backend, or
+
+- you want region-scoped placement rather than zone-scoped placement
+
+`storageclass.regionClusterMap`
+
+Sets the mapping between Kubernetes regions and simplyblock cluster IDs.
+Each region is associated with one cluster.
+
+`storageclass.allowedTopologyRegions`
+
+Sets the list of regions where the StorageClass is permitted to provision volumes.
+This ensures scheduling aligns with the clusters defined in `regionClusterMap`.
+
+```yaml title="Example of regionClusterMap usage"
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: simplyblock-csi-sc
+provisioner: csi.simplyblock.io
+parameters:
+  region_cluster_map: |
+    {"us-east-1":"cluster-uuid-a","us-west-2":"cluster-uuid-b"}
+  ... other parameters
+reclaimPolicy: Delete
+volumeBindingMode: WaitForFirstConsumer
+allowVolumeExpansion: true
+allowedTopologies:
+- matchLabelExpressions:
+  - key: topology.kubernetes.io/region
+    values:
+      - us-east-1
+      - us-east-1
+```
+
+This method allows Kubernetes to automatically pick the right cluster based on the pod’s scheduling region.
+
+!!! tip
+    The keys inside `region_cluster_map` must match the region labels present on your Kubernetes nodes
+    (typically `topology.kubernetes.io/region`). You can include as many regions as needed, each pointing to
+    the cluster ID defined in `simplyblock-csi-secret-v2`.

docs/deployments/kubernetes/k8s-storage-plane.md

@@ -176,8 +176,37 @@ mode. The most important ones are:
 | `storagenode.pciAllowed`      | Sets the list of allowed NVMe PCIe addresses.                                                                                                                                                                                                                                                                                                                                                                                                              | `<empty>` | 
 | `storagenode.pciBlocked`      | Sets the list of blocked NVMe PCIe addresses.                                                                                                                                                                                                                                                                                                                                                                                                              | `<empty>` | 
 | `storagenode.socketsToUse`    | Sets the list of NUMA sockets to use. If a worker node has more than 1 NUMA socket, it is possible to deploy more than one simplyblock storage node per host, depending on the distribution of NVMe devices and NICs across NUMA sockets and the resource demand of other workloads.                                                                                                                                                                       | 1         |
-| `storagenode.nodesPerSocket`  | Sets the number of storage nodes to be deployed per NUMA socket. It is possible to deploy one or two storage nodes per socket. This improves performance if one each NUMA socket has more than 32 cores.                                                                                                                                                                                                                                                   | 1         |  
+| `storagenode.nodesPerSocket`  | Sets the number of storage nodes to be deployed per NUMA socket. It is possible to deploy one or two storage nodes per socket. This improves performance if one each NUMA socket has more than 32 cores.| 1         |  
+| `storagenode.haJMCount` | Number of HA Journal Managers. | `<empty>` |
 | `storagenode.coresPercentage` | Sets the percentage of total cores (vCPUs) available to simplyblock storage node services. It must be ensured that the configured percentage yields at least 8 vCPUs per storage node. For example, if a host has 128 vCPUs on two NUMA sockets (64 each) and `--storagenode.socketsToUse=2` and `--storagenode.nodesPerSocket=1`, at least 13% (as `13% * 64 > 8`) must be set. Simplyblock does not use more than 32 vCPUs per storage node efficiently. | `<empty>` | 
+| `storagenode.deviceModel`    | NVMe SSD model to use for device selection. Must be set together with `storagenode.sizeRange`. | `<empty>` |
+| `storagenode.sizeRange`      | NVMe SSD device size range expressed as `min-max` (for example `500G-1T`). Used together with `storagenode.deviceModel` to filter eligible devices. | `<empty>` |
+| `storagenode.deviceNames` | Comma separated list of NVMe namespace names to be used by the storage node (for example `nvme0n1`, `nvme1n1`). Do **not** include the `/dev/` prefix. | `<empty>` |
+| `storagenode.format4k`    | If set to `true`, the specified devices will be formatted with a 4K sector size. Recommended for modern NVMe drives when supported. | `false` |
+| `storagenode.multiCluster.enable`                      | Enable multi-cluster storage node support. When enabled, a single Kubernetes cluster can host storage nodes connected to multiple simplyblock clusters. | `false`   |
+| `storagenode.multiCluster.clusters[].cluster_id`       | UUID of the simplyblock cluster this storage node should connect to.                                          | `<empty>` |
+| `storagenode.multiCluster.clusters[].secret`           | Secret used to authenticate against the specified simplyblock cluster.                                       | `<empty>` |
+| `storagenode.multiCluster.clusters[].workers`          | List of Kubernetes worker node names assigned to this simplyblock cluster. Storage nodes will only be scheduled on these workers. | `<empty>` |
+
+
+### Multi-Cluster Storage Node Support 
+
+```yaml title="Multi-Cluster definition"
+storagenode:
+  multiCluster:
+    enable: true
+    clusters:
+      - cluster_id: cluster-uuid-1
+        secret: cluster-secret-id-1
+        workers:
+          - worker-a-1
+          - worker-a-2
+      - cluster_id: cluster-uuid-2
+        secret: cluster-secret-id-2
+        workers:
+          - worker-b-1
+          - worker-b-2
+```
 
 !!! warning
     The resources consumed by simplyblock are exclusively used and have to be aligned with resources required by other