[CN-1113]: Improve scaling and upgrading doc (#150)

docs/modules/ROOT/examples/hazelcast-ipv6.yaml

@@ -3,8 +3,10 @@ kind: Hazelcast
 metadata:
   name: hazelcast-ipv6
 spec:
+  properties:
+    - "hazelcast.prefer.ipv4.stack": "false"
   jvm:
     args:
       - "-Djava.net.preferIPv4Stack=false"
       - "-Djava.net.preferIPv6Addresses=true"
-      - "-Dhazelcast.prefer.ipv4.stack=false"
+

docs/modules/ROOT/examples/properties.yaml

@@ -0,0 +1,7 @@
+apiVersion: hazelcast.com/v1alpha1
+kind: Hazelcast
+metadata:
+  name: hazelcast-sample
+spec:
+  properties:
+    "hazelcast.graceful.shutdown.max.wait": "300"

docs/modules/ROOT/nav.adoc

@@ -5,6 +5,7 @@
 * xref:connect-outside-kubernetes.adoc[]
 * xref:scheduling-configuration.adoc[Scheduling Hazelcast Pods]
 * xref:serialization-configuration.adoc[Serialization]
+* xref:scaling-upgrading.adoc[Scaling & Upgrading]
 * Configuring Data Structures
 ** xref:map-configuration.adoc[Map]
 ** xref:multimap-configuration.adoc[MultiMap]
@@ -18,6 +19,7 @@
 * xref:high-availability-mode.adoc[High Availability Mode]
 * xref:native-memory.adoc[Native Memory]
 * xref:jvm-parameters.adoc[Configuring JVM Parameters]
+* xref:hazelcast-parameters.adoc[Configuring System Properties]
 * xref:advanced-networking.adoc[Advanced Networking]
 * xref:tls.adoc[Configuring TLS]
 * Data Pipelines
@@ -34,6 +36,5 @@
 
 .Reference
 // Configuration options/spec files/any other reference docs
-* xref:scaling-upgrading.adoc[Scaling & Upgrading]
 * xref:phone-homes.adoc[Phone Homes]
 * xref:api-ref.adoc[API References]

docs/modules/ROOT/pages/hazelcast-parameters.adoc

@@ -0,0 +1,20 @@
+= Configuring System Properties
+
+You can configure Hazelcast parameters using the `properties` field in the CRD spec. You can find all properties in link:https://docs.hazelcast.com/hazelcast/5.3/system-properties[System Properties] document.
+
+It is worth highlighting the following system properties:
+
+- During a rolling upgrade, the cluster is shutdown gracefully to prevent data loss. You can configure this using the link:https://docs.hazelcast.com/hazelcast/5.3/system-properties#hazelcast.graceful.shutdown.max.wait[hazelcast.graceful.shutdown.max.wait system property].
++
+Example Configuration:
++
+[source,yaml,subs="attributes+"]
+----
+include::ROOT:example$/properties.yaml[]
+----
+
+Hazelcast Platform Operator sets the following system properties to the default values, which cannot be changed:
+
+- The final step in the link:https://docs.hazelcast.com/hazelcast/5.3/maintain-cluster/rolling-upgrades#rolling-upgrade-procedure[rolling upgrade procedure] is to trigger a rolling upgrade on the cluster. Hazelcast Platform Operator triggers it automatically by setting `hazelcast.cluster.version.auto.upgrade.enabled` to `true` by default.
+
+- `hazelcast.persistence.auto.cluster.state` set to `true` by default and `hazelcast.persistence.auto.cluster.state.strategy` is set to `NO_MIGRATION` by default.

docs/modules/ROOT/pages/scaling-upgrading.adoc

@@ -1,21 +1,51 @@
 = Scaling and Upgrading a Hazelcast Deployment
 
-To scale an existing Hazelcast deployment, use the following command:
+To scale an existing Hazelcast deployment, there are two options:
 
+- Modify the yaml definition you used to deploy Hazelcast cluster by updating `clusterSize` field and re-apply it again:
++
+Assuming the following is the existing configuration:
++
+[source,yaml]
+----
+apiVersion: hazelcast.com/v1alpha1
+kind: Hazelcast
+metadata:
+  name: hazelcast-sample
+spec:
+  clusterSize: 3
+----
++
+and you want to scale your deployment to five replicas, you need to apply the following:
++
+[source,yaml]
+----
+apiVersion: hazelcast.com/v1alpha1
+kind: Hazelcast
+metadata:
+  name: hazelcast-sample
+spec:
+  clusterSize: 5
+----
++
+- To scale an existing Hazelcast deployment, use the following command:
++
 [source,shell]
 ----
 kubectl scale hazelcast <name> --replicas <replica-count>
 ----
-
++
 Example:
-
++
 [source,shell]
 ----
 kubectl scale hazelcast hazelcast-sample --replicas 5
 ----
 
 == Upgrading
 
+Before upgrading, we recommend that you to read xref:hazelcast:maintain-cluster:rolling-upgrades.adoc#hazelcast-members-compatibility-guarantees[Rolling Upgrades] information.
+
 To upgrade your existing deployment to a newer version, you need to update `spec.version` field and re-apply. For example:
 
 Assuming the following is the existing configuration:
@@ -25,10 +55,7 @@ Assuming the following is the existing configuration:
 include::ROOT:example$/hazelcast-5.2.4.yaml[]
 ----
 
-and you want to upgrade your hazelcast version to {page-latest-supported-hazelcast}, you need to apply the following:
-
-
-Assuming the following is the existing configuration:
+and you want to upgrade your Hazelcast version to {page-latest-supported-hazelcast}, you need to apply the following:
 
 [source,yaml,subs="attributes+"]
 ----