From cbb67a96709987d29cdb360aba7e5d4d1fe12cd8 Mon Sep 17 00:00:00 2001
From: Max Asnaashari <max.asnaashari@canonical.com>
Date: Tue, 25 Jun 2024 20:53:53 +0000
Subject: [PATCH] doc/how-to: Add service command docs

Signed-off-by: Max Asnaashari <max.asnaashari@canonical.com>
---
 doc/how-to/add_service.rst | 42 ++++++++++++++++++++++++++++++++++++++
 doc/how-to/commands.rst    |  5 ++++-
 doc/how-to/index.rst       |  1 +
 3 files changed, 47 insertions(+), 1 deletion(-)
 create mode 100644 doc/how-to/add_service.rst

diff --git a/doc/how-to/add_service.rst b/doc/how-to/add_service.rst
new file mode 100644
index 000000000..c0a155738
--- /dev/null
+++ b/doc/how-to/add_service.rst
@@ -0,0 +1,42 @@
+.. _howto-add-service:
+
+How to add a new service
+========================
+
+If you set up the MicroCloud without MicroOVN or MicroCeph initially, you can add those services with the command :command:`microcloud service add`::
+
+  sudo microcloud service add
+
+#. Select whether you want to set up distributed storage (if adding MicroCeph to the MicroCloud).
+
+   .. note::
+      To set up distributed storage, you need at least three additional disks on at least three different machines.
+      The disks must not contain any partitions.
+
+   If you choose ``yes``, configure the distributed storage:
+
+   1. Select the disks that you want to use for distributed storage.
+
+      You must select at least three disks.
+   #. Select whether you want to wipe any of the disks.
+      Wiping a disk will destroy all data on it.
+
+   #. You can choose to optionally set up a CephFS distributed file system.
+#. Select either an IPv4 or IPv6 CIDR subnet for the Ceph internal traffic. You can leave it empty to use the default value, which is the MicroCloud internal network (see :ref:`howto-ceph-networking` for how to configure it).
+
+#. Select whether you want to set up distributed networking (if adding MicroOVN to the MicroCloud).
+
+   If you choose ``yes``, configure the distributed networking:
+
+   1. Select the network interfaces that you want to use (see :ref:`microcloud-networking-uplink`).
+
+      You must select one network interface per machine.
+   #. If you want to use IPv4, specify the IPv4 gateway on the uplink network (in CIDR notation) and the first and last IPv4 address in the range that you want to use with LXD.
+   #. If you want to use IPv6, specify the IPv6 gateway on the uplink network (in CIDR notation).
+#. MicroCloud now starts to bootstrap the cluster for only the new services.
+   Monitor the output to see whether all steps complete successfully.
+   See :ref:`bootstrapping-process` for more information.
+
+#. If all installed services are already set up, MicroCloud will exit.
+
+   All services have already been set up
diff --git a/doc/how-to/commands.rst b/doc/how-to/commands.rst
index 39fe53e2a..37596c3a6 100644
--- a/doc/how-to/commands.rst
+++ b/doc/how-to/commands.rst
@@ -259,7 +259,10 @@ See :ref:`lxd:cluster-manage-instance` and :ref:`lxd:cluster-evacuate`.
 .. list-table::
    :widths: 2 3
 
-   * - Inspect the cluster status
+   * - Inspect the cluster status for all services at once
+     - :command:`microcloud service list`
+
+   * - Inspect the cluster status for each service
      - :command:`microcloud cluster list`
 
        :command:`lxc cluster list`
diff --git a/doc/how-to/index.rst b/doc/how-to/index.rst
index 81ff2ae38..92908e86e 100644
--- a/doc/how-to/index.rst
+++ b/doc/how-to/index.rst
@@ -13,6 +13,7 @@ These how-to guides cover key operations and processes in MicroCloud.
    Initialise MicroCloud </how-to/initialise>
    Configure Ceph networking </how-to/ceph_networking>
    Add a machine </how-to/add_machine>
+   Add a service </how-to/add_service>
    Get support </how-to/support>
    Contribute to MicroCloud </how-to/contribute>
    Work with MicroCloud </how-to/commands>