From d1fe6a05bf7c1cdbf55e5415b59f78700f19a4f5 Mon Sep 17 00:00:00 2001
From: hlcianfagna <110453267+hlcianfagna@users.noreply.github.com>
Date: Tue, 27 Feb 2024 00:53:08 +0100
Subject: [PATCH] Administration/Clustering: Add section about "expanding
 clusters"

... linking to community forum article "How to add new nodes to an
existing cluster".

-- https://community.cratedb.com/t/how-to-add-new-nodes-to-an-existing-cluster/1546
---
 docs/admin/clustering/scale-up-down.md | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/docs/admin/clustering/scale-up-down.md b/docs/admin/clustering/scale-up-down.md
index 97bb2684..9654441c 100644
--- a/docs/admin/clustering/scale-up-down.md
+++ b/docs/admin/clustering/scale-up-down.md
@@ -1,7 +1,28 @@
 (scaling-clusters)=
-
 # Scaling Clusters Up and Down
 
+A significant feature in CrateDB is that it can scale horizontally, which means
+that instead of adding more RAM, CPU, and disk resources to existing nodes, you
+will add more individual nodes to your CrateDB cluster.
+
+By running your database cluster on multiple nodes, you will gain two benefits.
+
+- Store data volumes larger than being able to be handled on a single machine.
+- Add resiliency to your distributed database cluster, by increasing the number
+  of replica nodes.
+
+
+(scaling-expand)=
+## Expand Cluster
+
+The article about [how to add new nodes to an existing cluster] walks you
+through the process of scaling up your database cluster, and educates you
+about the corresponding details to consider.
+
+
+(scaling-ondemand)=
+## On-Demand Scaling
+
 The article about [scaling CrateDB clusters up and down to cope with peaks in
 demand] shares knowledge about the [shard allocation filtering] feature of
 CrateDB.
@@ -36,5 +57,6 @@ ALTER CLUSTER DECOMMISSION 'nodename';
 ```
 
 
+[how to add new nodes to an existing cluster]: https://community.cratedb.com/t/how-to-add-new-nodes-to-an-existing-cluster/1546
 [scaling CrateDB clusters up and down to cope with peaks in demand]: https://community.cratedb.com/t/scaling-cratedb-clusters-up-and-down-to-cope-with-peaks-in-demand/1314
 [shard allocation filtering]: inv:crate-reference#ddl_shard_allocation