From 0eb4147d875f716ddac5056ae58e8189acd0c3ed Mon Sep 17 00:00:00 2001 From: Kutluhan Metin Date: Thu, 18 Jan 2024 12:48:00 +0300 Subject: [PATCH] [CN-1113]: Improve scaling and upgrading doc (#150) --- .../modules/ROOT/examples/hazelcast-ipv6.yaml | 4 +- docs/modules/ROOT/examples/properties.yaml | 7 ++++ docs/modules/ROOT/nav.adoc | 3 +- .../ROOT/pages/hazelcast-parameters.adoc | 20 +++++++++ .../modules/ROOT/pages/scaling-upgrading.adoc | 41 +++++++++++++++---- 5 files changed, 66 insertions(+), 9 deletions(-) create mode 100644 docs/modules/ROOT/examples/properties.yaml create mode 100644 docs/modules/ROOT/pages/hazelcast-parameters.adoc diff --git a/docs/modules/ROOT/examples/hazelcast-ipv6.yaml b/docs/modules/ROOT/examples/hazelcast-ipv6.yaml index f319ce18..f2373aae 100644 --- a/docs/modules/ROOT/examples/hazelcast-ipv6.yaml +++ b/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" + diff --git a/docs/modules/ROOT/examples/properties.yaml b/docs/modules/ROOT/examples/properties.yaml new file mode 100644 index 00000000..4760de02 --- /dev/null +++ b/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" \ No newline at end of file diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index cd745526..d374895b 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/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] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/hazelcast-parameters.adoc b/docs/modules/ROOT/pages/hazelcast-parameters.adoc new file mode 100644 index 00000000..a14a7ec0 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/scaling-upgrading.adoc b/docs/modules/ROOT/pages/scaling-upgrading.adoc index 6aef6fa6..9ddb3e2f 100644 --- a/docs/modules/ROOT/pages/scaling-upgrading.adoc +++ b/docs/modules/ROOT/pages/scaling-upgrading.adoc @@ -1,14 +1,42 @@ = 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 --replicas ---- - ++ Example: - ++ [source,shell] ---- kubectl scale hazelcast hazelcast-sample --replicas 5 @@ -16,6 +44,8 @@ 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+"] ----