From 7e1cf66c55062564d635c24f022e99956a2e8e63 Mon Sep 17 00:00:00 2001
From: Surya Murugaian <surya.murugaian@aiven.io>
Date: Wed, 13 Sep 2023 03:38:16 +0000
Subject: [PATCH] updating more info on how to add or remove DDS wihtout any
 confilicts to the service

---
 docs/platform/howto/add-storage-space.rst | 20 ++++++++++++++++++--
 docs/platform/howto/scale-services.rst    |  3 ++-
 2 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/docs/platform/howto/add-storage-space.rst b/docs/platform/howto/add-storage-space.rst
index 0cfd167da0..1d32de8090 100644
--- a/docs/platform/howto/add-storage-space.rst
+++ b/docs/platform/howto/add-storage-space.rst
@@ -1,7 +1,7 @@
 Add or remove storage 
 =======================
 
-With :doc:`dynamic disk sizing <../concepts/dynamic-disk-sizing>`, you can add or remove disk storage both when you create a service and later for a running service. 
+With :doc:`dynamic disk sizing <../concepts/dynamic-disk-sizing>`, you can add or remove disk storage (by factor of 10 GBs only) both when you create a service and later for a running service. But, it is not possible to add or remove storage when the service nodes are rebalancing.(i.e, during maintenance update, service upgrade, etc.)
 
 .. note::
    This feature is not available for all service plans.
@@ -11,6 +11,7 @@ Add storage during new service creation
 
 You can add disk storage when :doc:`creating a new service <../howto/create_new_service>`. 
 
+
 Add storage to a running service
 ---------------------------------
 
@@ -24,7 +25,7 @@ You can add storage to your running service in `Aiven Console <https://console.a
 
 #. In the **Upgrade service storage** window, use the slider to add disk storage.
 
-   ..note::
+.. note::
       
       The price shown for the additional storage includes backup costs.
 
@@ -68,3 +69,18 @@ Remove added storage
 .. topic:: Result
 
    Your additional disk space has been removed. The service is in the **Rebalancing** state while the nodes are being recycled. 
+
+Using Aiven CLI
+---------------
+
+It is possible to use :doc:`Aiven CLI </docs/tools/cli>` ro add or remove additional storage by :ref:`updating the service configuration <avn-cli-service-update>` using the flag ``--disk-space-gib``. The value here is the total disk space that your service would like to have.
+For example, if you are using a ``Startup-4`` plan which has 80GB disk space by default and you would like to add extra 10GB disk. The value to be given for the flag ``--disk-space-gib`` is 90 GB.
+::
+
+      avn service update --disk-space-gib 90 --project <PROJECT_NAME> <SERVICE_NAME>
+
+.. note::
+
+   - When you perform a service upgrade or downgrade horizontally, it is required to include any additional disk existing on the service. For example, ``Startup-4`` to ``Business-4`` or ``Business-4`` to ``Startup-4``.
+   - Similarly, when you fork an existing service, it is required to include any additional disk on the source service.
+
diff --git a/docs/platform/howto/scale-services.rst b/docs/platform/howto/scale-services.rst
index a0079579bf..916c3c2b61 100644
--- a/docs/platform/howto/scale-services.rst
+++ b/docs/platform/howto/scale-services.rst
@@ -16,4 +16,5 @@ When creating a new Aiven service, you are not tied to a plan. Your services can
 
 .. note::
 
-    You can also use the :ref:`dedicated service update function <avn-cli-service-update>` to scale your service plan via the :doc:`Aiven CLI </docs/tools/cli>`.
+    - You can also use the :ref:`dedicated service update function <avn-cli-service-update>` to scale your service plan via the :doc:`Aiven CLI </docs/tools/cli>`.
+    - When you perform a service upgrade or downgrade horizontally, it is required to include any additional disk existing on the service. For example, ``Startup-4`` to ``Business-4`` or ``Business-4`` to ``Startup-4``.