From 693d88d697752e17ee0927211245e0c795fe9336 Mon Sep 17 00:00:00 2001
From: Alex Creasy <alex@creasy.dev>
Date: Mon, 19 Aug 2024 13:22:08 +0100
Subject: [PATCH] Document deploying MR locally on a kind cluster for
 development

Signed-off-by: Alex Creasy <alex@creasy.dev>
---
 clients/ui/bff/docs/dev-guide.md | 82 ++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 clients/ui/bff/docs/dev-guide.md

diff --git a/clients/ui/bff/docs/dev-guide.md b/clients/ui/bff/docs/dev-guide.md
new file mode 100644
index 000000000..b8e488962
--- /dev/null
+++ b/clients/ui/bff/docs/dev-guide.md
@@ -0,0 +1,82 @@
+# Development Guide
+
+## Local kubernetes deployment of Model Registry
+To test the BFF locally without mocking the k8s calls the Model Regsitry backend can be deployed locally using kind.
+
+### Prerequisites 
+The following tools need to be installed in your local environment:
+* Podman (Docker should also work) - [Podman Desktop Instructions](https://podman-desktop.io)
+* kubectl - [Instructions](https://kubernetes.io/docs/tasks/tools/#kubectl)
+* kind - [Instructions](https://kind.sigs.k8s.io/docs/user/quick-start/#installation)
+
+Note: all of the above tools can be installed using your OS package manager, this is the preferred method.
+
+### Setup
+#### 1. Create a kind cluster
+Create a local cluster for running the MR backend using the following command:
+```shell
+kind create cluster --name model-registry
+```
+
+Kind will start creating a new local cluster for you to deploy, once it has completed verify you can access the cluster 
+using kubectl by running:
+```shell
+kubectl cluster-info --context kind-model-registry
+```
+
+If everything is working correctly you should see output similar to:
+```
+Kubernetes control plane is running at https://127.0.0.1:58635
+CoreDNS is running at https://127.0.0.1:58635/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
+```
+
+#### 2. Create kubeflow namespace
+Create a namespace for model registry to run in, by default this is kubeflow, run:
+```shell
+kubectl --context kind-model-registry create namespace kubeflow
+```
+
+#### 3. Deploy Model Registry to cluster
+You can now deploy the MR backend to your newly created cluster using the kustomize configs in the MR repository by
+running:
+```shell
+kubectl --context kind-model-registry apply -k "https://github.com/kubeflow/model-registry/manifests/kustomize/overlays/db?ref=v0.2.4-alpha"
+```
+
+Wait for the model registry deployment to spin up, alternatively run:
+```shell
+kubectl --context kind-model-registry wait --for=condition=available -n kubeflow deployment/model-registry-deployment --timeout=1m
+```
+This command will return when the cluster is ready. To verify this now run:
+```shell
+kubectl --context kind-model-registry get pods -n kubeflow
+```
+Two pods should be listed, `model-registry-db-xxx` and `model-registry-deployment-yyy` both should have a status of `Running`.
+
+##### NOTE: Issues running on arm64 architecture
+There is currently an issue deploying to an arm64 device such as a Mac with an M-series chip. This is because the MySql 
+image tag deployed by the manifests does not have an arm64 compatible image. To work around this you can use a modified
+manifest deployed in a fork of the repo - you can use this by running the below command instead of the first command in
+section 3 of this guide.
+```shell
+kubectl --context kind-model-registry apply -k "https://github.com/alexcreasy/model-registry/manifests/kustomize/overlays/db?ref=kind"
+```
+Note: an issue has been filed regarding this ticket here: 
+* [#266 Cannot deploy to k8s on AArch64 nodes using manifests in repo](https://github.com/kubeflow/model-registry/issues/266)
+
+#### 4. Setup a port forward to the service
+In order to access the MR REST API locally you need to forward a local port to 8080 on the MR service. Run the following
+command:
+```shell
+kubectl --context kind-model-registry port-forward svc/model-registry-service -n kubeflow 8080:8080
+```
+
+Note you can change the local forwarded port by changing the first port value, e.g. `4000:8080` will forward port 4000
+to the MR service.
+
+#### 5. Test the service
+Test the service by querying one of the rest endpoints, for example:
+```shell
+curl localhost:4000/api/v1/model-registry/
+```
+You should receive a 200 response if everything is working correctly.
\ No newline at end of file