update docs

Author: razvan

CHANGELOG.md

@@ -7,6 +7,7 @@
 - Reduce CRD size from `1.4MB` to `96KB` by accepting arbitrary YAML input instead of the underlying schema for the following fields ([#548]):
   - `podOverrides`
   - `affinity`
+- Optionally move regions to other pods before shutting down a region server ([#570]).
 
 ### Fixed
 
@@ -21,6 +22,7 @@
 [#550]: https://github.com/stackabletech/hbase-operator/pull/550
 [#556]: https://github.com/stackabletech/hbase-operator/pull/556
 [#558]: https://github.com/stackabletech/hbase-operator/pull/558
+[#570]: https://github.com/stackabletech/hbase-operator/pull/570
 
 ## [24.7.0] - 2024-07-24
 

deploy/helm/hbase-operator/crds/crds.yaml

@@ -725,20 +725,25 @@ spec:
                               type: boolean
                           type: object
                         regionMover:
+                          description: Before terminating a region server pod, the RegionMover tool can be invoked to transfer local regions to other servers. This may cause a lot of network traffic in the Kubernetes cluster if the entire HBase stacklet is being restarted. The operator will compute a timeout period for the region move that will not exceed the graceful shutdown timeout.
                           nullable: true
                           properties:
                             ack:
+                              description: If enabled (default), the region mover will confirm that regions are available on the source as well as the target pods before and after the move.
                               type: boolean
                             extraOpts:
                               default: []
+                              description: Additional options to pass to the region mover.
                               items:
                                 type: string
                               type: array
                             maxThreads:
+                              description: Maximum number of threads to use for moving regions.
                               format: uint16
                               minimum: 0.0
                               type: integer
                             runBeforeShutdown:
+                              description: Move local regions to other servers before terminating a region server's pod.
                               type: boolean
                           required:
                             - ack
@@ -969,20 +974,25 @@ spec:
                                     type: boolean
                                 type: object
                               regionMover:
+                                description: Before terminating a region server pod, the RegionMover tool can be invoked to transfer local regions to other servers. This may cause a lot of network traffic in the Kubernetes cluster if the entire HBase stacklet is being restarted. The operator will compute a timeout period for the region move that will not exceed the graceful shutdown timeout.
                                 nullable: true
                                 properties:
                                   ack:
+                                    description: If enabled (default), the region mover will confirm that regions are available on the source as well as the target pods before and after the move.
                                     type: boolean
                                   extraOpts:
                                     default: []
+                                    description: Additional options to pass to the region mover.
                                     items:
                                       type: string
                                     type: array
                                   maxThreads:
+                                    description: Maximum number of threads to use for moving regions.
                                     format: uint16
                                     minimum: 0.0
                                     type: integer
                                   runBeforeShutdown:
+                                    description: Move local regions to other servers before terminating a region server's pod.
                                     type: boolean
                                 required:
                                   - ack

docs/modules/hbase/pages/usage-guide/operations/graceful-shutdown.adoc

@@ -1,6 +1,6 @@
 = Graceful shutdown
 
-You can configure the graceful shutdown as described in xref:concepts:operations/graceful_shutdown.adoc[].
+You can configure the graceful shutdown grace period as described in xref:concepts:operations/graceful_shutdown.adoc[].
 
 == Masters
 
@@ -15,7 +15,7 @@ However, there is no message in the log acknowledging the graceful shutdown.
 
 == RegionServers
 
-As a default, RegionServers have `60 minutes` to shut down gracefully.
+By default, RegionServers have `60 minutes` to shut down gracefully.
 
 They use the same mechanism described above.
 In contrast to the Master servers, they will, however, acknowledge the graceful shutdown with a message in the logs:
@@ -26,6 +26,30 @@ In contrast to the Master servers, they will, however, acknowledge the graceful
 2023-10-11 12:38:05,060 INFO  [shutdown-hook-0] regionserver.HRegionServer: ***** STOPPING region server 'test-hbase-regionserver-default-0.test-hbase-regionserver-default.kuttl-test-topical-parakeet.svc.cluster.local,16020,1697027870348' *****
 ----
 
+The operator allows for finer control over the shutdown process of region servers.
+For each region server pod, the region mover tool may be invoked before terminating the region server's pod.
+The affected regions are transfered to other pods thus ensuring that the data is not lost.
+
+Here is a an example:
+
+[source,yaml]
+----
+spec:
+  regionServers:
+    config:
+      regionMover
+        runBeforeShutdown: true, <1>
+        maxThreads: 5, <2>
+        ack: false, <3>
+        extraOpts: ["--designatedFile", "/path/to/designatedFile"] <4>
+----
+<1>: Run the region mover tool before shutting down the region server. Default is `false`.
+<2>: Maximum number of threads to use for moving regions. Default is 1.
+<3>: Enable or disable region confirmation on the present and target servers. Default is `true`.
+<4>: Extra options to pass to the region mover tool.
+
+NOTE: There is no need to explicitely specify a timeout for the region movement. The operator will compute an appropriate timeout that cannot exceed the `gracefulShutdownTimeout` for region servers.
+
 == RestServers
 
 As a default, RestServers have `5 minutes` to shut down gracefully.

rust/crd/src/lib.rs

@@ -518,9 +518,17 @@ impl Configuration for HbaseConfigFragment {
 #[derive(Clone, Debug, JsonSchema, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct RegionMover {
+    /// Move local regions to other servers before terminating a region server's pod.
     run_before_shutdown: bool,
+
+    /// Maximum number of threads to use for moving regions.
     max_threads: u16,
+
+    /// If enabled (default), the region mover will confirm that regions are available on the
+    /// source as well as the target pods before and after the move.
     ack: bool,
+
+    /// Additional options to pass to the region mover.
     #[serde(default)]
     extra_opts: Vec<String>,
 }
@@ -575,6 +583,12 @@ pub struct RegionServerConfig {
     /// Time period Pods have to gracefully shut down, e.g. `30m`, `1h` or `2d`. Consult the operator documentation for details.
     #[fragment_attrs(serde(default))]
     pub graceful_shutdown_timeout: Option<Duration>,
+
+    /// Before terminating a region server pod, the RegionMover tool can be invoked to transfer
+    /// local regions to other servers.
+    /// This may cause a lot of network traffic in the Kubernetes cluster if the entire HBase stacklet is being
+    /// restarted.
+    /// The operator will compute a timeout period for the region move that will not exceed the graceful shutdown timeout.
     pub region_mover: RegionMover,
 }