add more comments to mirror-3dc cluster description

2 files changed, 51 insertions, 39 deletions

diff --git a/ydb/deploy/yaml_config_examples/block-4-2.yaml b/ydb/deploy/yaml_config_examples/block-4-2.yaml
index 0ba54036b3..2982a718f6 100644
--- a/ydb/deploy/yaml_config_examples/block-4-2.yaml
+++ b/ydb/deploy/yaml_config_examples/block-4-2.yaml
@@ -2,16 +2,16 @@
 # are described in documentaion https://ydb.tech/en/docs/deploy/configuration/config
 
 # static erasure is the parameter that
-# desribes the fault tolerance mode of the
+# describes the fault tolerance mode of the
 # cluster. See docs for more details https://ydb.tech/en/docs/deploy/configuration/config#domains-blob
 static_erasure: block-4-2
 host_configs: # the list of available host configurations in the cluster.
 - drive:
   - path: /dev/disk/by-partlabel/ydb_disk_ssd_01   # path of the first disk in the host configration.
-    type: SSD   # kind of the disk: available kinds are SSD, NVME, HDD
+    type: SSD                                      # kind of the disk: available kinds are SSD, NVME or HDD
   - path: /dev/disk/by-partlabel/ydb_disk_ssd_02
     type: SSD
-  host_config_id: 1  # the unique id of the host config
+  host_config_id: 1                                # the unique id of the host config
 hosts:
 - host: ydb-node-zone-a-1.local   # storage node DNS name
   host_config_id: 1           # numeric host configuration template identifier.
@@ -72,7 +72,7 @@ domains_config:
   domain:
   # There can be only one root domain in a cluster. Domain name prefixes all scheme objects names, e.g. full name of a table table1 in database db1 
   # in a cluster with domains_config.domain.name parameter set to Root would be equal to /Root/db1/table1
-  - name: Root 
+  - name: Root
     storage_pool_types:
     - kind: ssd
       pool_config:
@@ -92,21 +92,18 @@ domains_config:
     ssid: 1
 table_service_config:
   sql_version: 1
-actor_system_config:                 # the configuration of the actor system which descibes how cores of the instance are distributed
-  executor:                          # accross different types of workloads in the instance.
+actor_system_config:    # the configuration of the actor system which descibes how cores of the instance are distributed
+  executor:             # accross different types of workloads in the instance.
   - name: System        # system executor of the actor system. in this executor YDB launches system type of workloads, like system tablets
                         # and reads from storage.
-    spin_threshold: 0
     threads: 2          # the number of threads allocated to system executor.
     type: BASIC
   - name: User          # user executor of the actor system. In this executor YDB launches user workloads, like datashard activities,
                         # queries and rpc calls.
-    spin_threshold: 0
     threads: 3          # the number of threads allocated to user executor.
     type: BASIC
   - name: Batch         # user executor of the actor system. In this executor YDB launches batch operations, like scan queries, table
                         # compactions, background compactions.
-    spin_threshold: 0
     threads: 2          # the number of threads allocated to the batch executor.
     type: BASIC
   - name: IO            # the io executor. In this executor launches sync operations and writes logs.
diff --git a/ydb/deploy/yaml_config_examples/mirror-3dc-3-nodes.yaml b/ydb/deploy/yaml_config_examples/mirror-3dc-3-nodes.yaml
index 5ec956f747..77d493ad48 100644
--- a/ydb/deploy/yaml_config_examples/mirror-3dc-3-nodes.yaml
+++ b/ydb/deploy/yaml_config_examples/mirror-3dc-3-nodes.yaml
@@ -1,20 +1,30 @@
+# YDB configuration options and their values
+# are described in documentaion https://ydb.tech/en/docs/deploy/configuration/config
+
+# static erasure is the parameter that
+# describes the fault tolerance mode of the
+# cluster. See docs for more details https://ydb.tech/en/docs/deploy/configuration/config#domains-blob
 static_erasure: mirror-3-dc
-host_configs:
+host_configs: # the list of available host configurations in the cluster.
 - drive:
-  - path: /dev/disk/by-partlabel/ydb_disk_ssd_01
-    type: SSD
+  - path: /dev/disk/by-partlabel/ydb_disk_ssd_01    # path of the first disk in the host configration.
+    type: SSD                                       # kind of the disk: available kinds are SSD, NVME, HDD
   - path: /dev/disk/by-partlabel/ydb_disk_ssd_02
     type: SSD
   - path: /dev/disk/by-partlabel/ydb_disk_ssd_03
     type: SSD
   host_config_id: 1
 hosts:
-- host: ydb-node-zone-a.local
-  host_config_id: 1
-  walle_location:
-    body: 1
-    data_center: 'zone-a'
-    rack: '1'
+- host: ydb-node-zone-a.local       # storage node DNS name
+  host_config_id: 1                 # numeric host configuration template identifier
+  walle_location:                   # this parameter describes where host is located.
+    body: 1                         # string representing a host serial number.
+    data_center: 'zone-a'           # string representing the datacenter / availability zone where the host is located.
+                                    # if cluster is deployed using mirror-3-dc fault tolerance mode, all hosts must be distributed
+                                    # across 3 datacenters.
+    rack: '1'                       # string representing a rack identifier where the host is located.
+                                    # if cluster is deployed using block-4-2 erasure, all hosts should be distrubited
+                                    # accross at least 8 racks.
 - host: ydb-node-zone-b.local
   host_config_id: 1
   walle_location:
@@ -28,12 +38,16 @@ hosts:
     data_center: 'zone-c'
     rack: '3'
 domains_config:
+  # There can be only one root domain in a cluster. Domain name prefixes all scheme objects names, e.g. full name of a table table1 in database db1.
+  # in a cluster with domains_config.domain.name parameter set to Root would be equal to /Root/db1/table1
   domain:
   - name: Root
     storage_pool_types:
     - kind: ssd
       pool_config:
         box_id: 1
+        # fault tolerance mode name - none, block-4-2, or mirror-3-dc..
+        # See docs for more details https://ydb.tech/en/docs/deploy/configuration/config#domains-blob
         erasure_species: mirror-3-dc
         kind: ssd
         geometry:
@@ -43,7 +57,7 @@ domains_config:
           domain_level_end: 256
         pdisk_filter:
         - property:
-          - type: SSD
+          - type: SSD  # device type to match host_configs.drive.type
         vdisk_kind: Default
   state_storage:
   - ring:
@@ -52,39 +66,40 @@ domains_config:
     ssid: 1
 table_service_config:
   sql_version: 1
-actor_system_config:
-  executor:
-  - name: System
-    spin_threshold: 0
-    threads: 2
+actor_system_config:          # the configuration of the actor system which descibes how cores of the instance are distributed
+  executor:                   # accross different types of workloads in the instance.
+  - name: System              # system executor of the actor system. in this executor YDB launches system type of workloads, like system tablets
+                              # and reads from storage.
+    threads: 2                # the number of threads allocated to system executor.
     type: BASIC
-  - name: User
-    spin_threshold: 0
-    threads: 3
+  - name: User                # user executor of the actor system. In this executor YDB launches user workloads, like datashard activities,
+                              # queries and rpc calls.
+    threads: 3                # the number of threads allocated to user executor.
     type: BASIC
-  - name: Batch
-    spin_threshold: 0
-    threads: 2
+  - name: Batch               # user executor of the actor system. In this executor YDB launches batch operations, like scan queries, table
+                              # compactions, background compactions.
+    threads: 2                # the number of threads allocated to the batch executor.
     type: BASIC
-  - name: IO
+  - name: IO                  # the io executor. In this executor launches sync operations and writes logs.
     threads: 1
     time_per_mailbox_micro_secs: 100
     type: IO
-  - name: IC
+  - name: IC                  # the interconnect executor which YDB uses for network communications accross different nodes of the cluster.
     spin_threshold: 10
-    threads: 1
+    threads: 1                # the number of threads allocated to the interconnect executor.
     time_per_mailbox_micro_secs: 100
     type: BASIC
   scheduler:
     progress_threshold: 10000
     resolution: 256
     spin_threshold: 0
-blob_storage_config:
+blob_storage_config:         # configuration of static blobstorage group.
+                             # YDB uses this group to store system tablets' data, like SchemeShard
   service_set:
     groups:
-    - erasure_species: mirror-3-dc
-      rings:
-      - fail_domains:
+    - erasure_species: mirror-3-dc # fault tolerance mode name for the static group
+      rings:          # in mirror-3-dc must have exactly 3 rings or availability zones
+      - fail_domains:  # first record: fail domains of the static group describe where each vdisk of the static group should be located.
         - vdisk_locations:
           - node_id: ydb-node-zone-a.local
             pdisk_category: SSD
@@ -97,7 +112,7 @@ blob_storage_config:
           - node_id: ydb-node-zone-a.local
             pdisk_category: SSD
             path: /dev/disk/by-partlabel/ydb_disk_ssd_03
-      - fail_domains:
+      - fail_domains: # second ring: fail domains of the static group describe where each vdisk of the static group should be located.
         - vdisk_locations:
           - node_id: ydb-node-zone-b.local
             pdisk_category: SSD
@@ -110,7 +125,7 @@ blob_storage_config:
           - node_id: ydb-node-zone-b.local
             pdisk_category: SSD
             path: /dev/disk/by-partlabel/ydb_disk_ssd_03
-      - fail_domains:
+      - fail_domains: # third ring: fail domains of the static group describe where each vdisk of the static group should be located.
         - vdisk_locations:
           - node_id: ydb-node-zone-c.local
             pdisk_category: SSD