fixup! feat(exapp_development): add Kubernetes setup instructions

Signed-off-by: Edward Ly <contact@edward.ly>

Author: edward-ly

developer_manual/exapp_development/scaling/AppAPIEmulation.rst

@@ -43,7 +43,8 @@ Prerequisites
    You can also hit the agent directly on
    ``http://127.0.0.1:8200/...`` for debugging, but that bypasses the
    HAProxy/AppAPI path and may skip shared-key enforcement depending
-   on your routing.
+   on your routing. Moreover, the port is only accessible from within the HaRP container
+   (as it is the internal SPOE control API).
 
 1. Check if ExApp is present (k8s deployment exists)
 ----------------------------------------------------

developer_manual/exapp_development/scaling/KEDASetup.rst

@@ -42,7 +42,7 @@ When the queue reduces in size, KEDA scales back down.
 0. GPU Setup (kind cluster)
 ---------------------------
 
-If your ExApp needs GPU (e.g. llm2), you must set up GPU passthrough in
+If your ExApp requires a GPU (e.g. llm2), you must set up GPU passthrough in
 the kind cluster.
 
 0.1 Configure Docker on the host
@@ -100,7 +100,17 @@ the kind cluster.
 0.5 Install NVIDIA device plugin
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For a single GPU shared across multiple pods, use **time-slicing**.
+By default, if a Deploy daemon is configured with multiple GPUs,
+AppAPI will attach one ExApp container/pod per GPU.
+In order to create multiple pods that share a single GPU,
+**time-slicing** must be configured for the GPU device plugin.
+
+.. note::
+
+	All ExApps registered on the same Deploy daemon will share the same GPU resources.
+	For ExApps that require heavy use of GPUs,
+	it is recommended to have a separate Deploy daemon (host) for each of them.
+
 First create a ConfigMap with the number of replicas (virtual GPUs):
 
 .. code:: bash
@@ -186,7 +196,8 @@ Then deploy the device plugin with the config:
        print(f'{n[\"metadata\"][\"name\"]}: nvidia.com/gpu = {gpu}')
    "
 
-Expected: ``nvidia.com/gpu = 4`` (or your configured replicas count).
+Expected: ``nvidia.com/gpu = 4`` (or your configured replicas count
+multiplied by the number of available physical GPUs).
 
 0.7 Test GPU from a pod
 ~~~~~~~~~~~~~~~~~~~~~~~

developer_manual/exapp_development/scaling/KubernetesSetup.rst

@@ -45,6 +45,24 @@ Architecture overview
 
 --------------
 
+0. Environment variables (optional)
+-----------------------------------
+
+If you have a custom Kubernetes environment, you can specify its configuration here
+(the values below are the current defaults).
+
+.. code:: bash
+
+   # .env
+   HP_K8S_NAMESPACE="nextcloud-exapps"
+   HP_K8S_STORAGE_CLASS=""
+   HP_K8S_DEFAULT_STORAGE_SIZE="10Gi"
+   HP_K8S_BEARER_TOKEN_FILE="/var/run/secrets/kubernetes.io/serviceaccount/token"
+
+.. code:: bash
+
+   source .env
+
 .. _scaling-kubernetes-setup-step-1:
 
 1. Create the kind Cluster
@@ -160,15 +178,16 @@ From the HaRP repository root:
 
 .. code:: bash
 
-   cd ~/nextcloud/HaRP
+   cd path/to/HaRP
    bash development/redeploy_host_k8s.sh
 
 The script will:
 
    1. Auto-detect the k8s API server URL
    2. Generate a fresh bearer token
-   3. Build the HaRP Docker image
-   4. Start HaRP with k8s backend enabled on host network
+   3. Connect the Nextcloud network to the cluster network
+   4. Build the HaRP Docker image
+   5. Start HaRP with k8s backend enabled on host network
 
 Wait for HaRP to become healthy:
 
@@ -204,6 +223,11 @@ your container ID or name, and ``<GATEWAY_IP>`` with the gateway from
      --k8s_expose_type=nodeport \
      --set-default
 
+.. note::
+
+   While the ``--harp_frp_address`` is a required argument for the ``docker`` command,
+   it is not used by Kubernetes at all.
+
 Verify:
 
 .. code:: bash
@@ -397,15 +421,26 @@ Clean up all ExApp resources
 Reset everything
 ~~~~~~~~~~~~~~~~
 
+Remove the deploy daemon config:
+
 .. code:: bash
 
-   # Remove daemon config
    docker exec <NC_CONTAINER> sudo -E -u www-data php occ app_api:daemon:unregister k8s_local
 
-   # Delete kind cluster
+.. note::
+
+   Optionally, add the ``--rm-data`` option to also delete the associated PVC (Persistent Volume Claim).
+
+Delete the ``kind`` cluster:
+
+.. code:: bash
+
    kind delete cluster --name nc-exapps
 
-   # Remove HaRP container
+Remove the HaRP container:
+
+.. code:: bash
+
    docker rm -f appapi-harp
 
 Then start again from :ref:`Step 1<scaling-kubernetes-setup-step-1>`.

developer_manual/exapp_development/scaling/index.rst

@@ -14,16 +14,6 @@ to increase the capacity and performance.
 The rest of this section will explain how to setup and use Kubernetes for automated scaling.
 Additional instructions are also provided if you have a GPU device for GPU scaling.
 
-
-.. note::
-
-	Currently, if a Deploy daemon is configured with GPUs available,
-	AppAPI will by default attach all available GPU devices to each ExApp container on this Deploy daemon.
-	This means that these GPUs are shared between all ExApps on the same Deploy daemon.
-	Therefore, for the ExApps that require heavy use of GPUs,
-	it is recommended to have a separate Deploy daemon (host) for them.
-
-
 .. toctree::
 	:maxdepth: 2