From 25cd4a612b1802c17ad2916e36529969a5fe3570 Mon Sep 17 00:00:00 2001 From: lucferbux Date: Thu, 7 Nov 2024 22:27:02 +0100 Subject: [PATCH] Revamp docs Signed-off-by: lucferbux --- README.md | 1 + clients/ui/Makefile | 34 ++++ clients/ui/README.md | 48 +++++ clients/ui/api/openapi/mod-arch.yaml | 172 +++++++++++++++--- clients/ui/docker-compose.yaml | 3 +- clients/ui/frontend/Dockerfile | 2 +- clients/ui/frontend/README.md | 2 +- clients/ui/frontend/docs/dev-setup.md | 4 - clients/ui/manifests/base/kustomization.yaml | 1 + .../base/model-registry-bff-deployment.yaml | 1 + .../base/model-registry-bff-role.yaml | 2 +- .../base/model-registry-service-account.yaml | 4 + .../base/model-registry-ui-deployment.yaml | 3 + clients/ui/scripts/deploy_kind_cluster.sh | 46 +++++ 14 files changed, 292 insertions(+), 31 deletions(-) create mode 100644 clients/ui/Makefile create mode 100644 clients/ui/README.md create mode 100644 clients/ui/manifests/base/model-registry-service-account.yaml create mode 100755 clients/ui/scripts/deploy_kind_cluster.sh diff --git a/README.md b/README.md index ef8f66a11..37ae95883 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,7 @@ Model registry provides a central repository for model developers to store and m - [playground](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/kubeflow/model-registry/main/api/openapi/model-registry.yaml) - [license scanning](https://github.com/kubeflow/model-registry/issues/323) - [monitoring image quality](https://github.com/kubeflow/model-registry/issues/327) +8. [UI](.clients/ui/README.md) ## Pre-requisites: - go >= 1.21 diff --git a/clients/ui/Makefile b/clients/ui/Makefile new file mode 100644 index 000000000..9e5c66bfb --- /dev/null +++ b/clients/ui/Makefile @@ -0,0 +1,34 @@ +CONTAINER_TOOL ?= docker +IMG ?= model-registry-bff:latest +PORT ?= 4000 +MOCK_K8S_CLIENT ?= false +MOCK_MR_CLIENT ?= false +# ENVTEST_K8S_VERSION refers to the version of kubebuilder assets to be downloaded by envtest binary. +ENVTEST_K8S_VERSION = 1.29.0 + +.PHONY: all +all: build + +.PHONY: help +help: ## Display this help. + @awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n make \033[36m\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf " \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST) + +.PHONY: dev-bff +dev-bff: + cd bff && make run PORT=4000 MOCK_K8S_CLIENT=true MOCK_MR_CLIENT=true + +.PHONY: dev-frontend +dev-frontend: + cd frontend && npm run start:dev + +.PHONY: dev-start +dev-start: + make -j 2 dev-bff dev-frontend + +.PHONY: docker-compose +docker-compose: + $(CONTAINER_TOOL) compose -f docker-compose.yaml up + +.PHONY: kind-deployment +kind-deployment: + ./scripts/deploy_kind_cluster.sh diff --git a/clients/ui/README.md b/clients/ui/README.md new file mode 100644 index 000000000..53f4cbef9 --- /dev/null +++ b/clients/ui/README.md @@ -0,0 +1,48 @@ +[frontend requirements]: ./frontend/docs/dev-setup.md#requirements +[BFF requirements]: ./bff/README.md#pre-requisites +[frontend dev setup]: ./frontend/docs/dev-setup.md#development +[BFF dev setup]: ./bff/README.md#development + +# Model Registry UI + +## Overview + +The Model Registry UI is a standalone web app for Kubeflow Model Registry. In this repository, you will find the frontend and backend for the Model Registry UI. + +## Prerequisites + +* [Frontend requirements] +* [BFF requirements] + +## Set Up + +### Development + +To run the a mocked dev environment you can either: + +* Use the makefile command: `make dev-start`. + +* Or follow the [frontend dev setup] and [BFF dev setup]. + +### Contenerization + +To build the Model Registry UI container, run the following command: + +```shell +make docker-compose +``` + +### Orquestration + +For a in-depth guide on how to deploy the Model Registry UI, please refer to the [local kubernetes deployment](./bff/docs/dev-guide.md) documentation. + +To quickly enable the Model Registry UI in your Kind cluster, you can use the following command: + +```shell +make kind-deployment +``` + +## OpenAPI Specification + +You can find the OpenAPI specification for the Model Registry UI in the [openapi](./api/openapi) directory. +A live version of the OpenAPI specification can be found [here](https://editor.swagger.io/?url=https://raw.githubusercontent.com/kubeflow/model-registry/main/clients/ui/api/openapi/mod-arch.yaml). diff --git a/clients/ui/api/openapi/mod-arch.yaml b/clients/ui/api/openapi/mod-arch.yaml index 3479de762..d17494682 100644 --- a/clients/ui/api/openapi/mod-arch.yaml +++ b/clients/ui/api/openapi/mod-arch.yaml @@ -86,7 +86,13 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ModelVersionUpdate" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/ModelVersionUpdate" required: true tags: - ModelRegistryService @@ -141,7 +147,13 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/RegisteredModelCreate" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/RegisteredModelCreate" required: true tags: - ModelRegistryService @@ -186,7 +198,13 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/RegisteredModelUpdate" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/RegisteredModelUpdate" required: true tags: - ModelRegistryService @@ -244,7 +262,13 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/Artifact" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/Artifact" required: true tags: - ModelRegistryService @@ -305,7 +329,13 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ModelVersion" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/ModelVersion" required: true tags: - ModelRegistryService @@ -972,99 +1002,195 @@ components: content: application/json: schema: - $ref: "#/components/schemas/Config" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/Config" description: A response containing a list of ModelArtifact entities. ModelRegistryRespone: content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/ModelRegistry" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + type: array + items: + $ref: "#/components/schemas/ModelRegistry" description: A response containing a list of ModelArtifact entities. ModelArtifactListResponse: content: application/json: schema: - $ref: "#/components/schemas/ModelArtifactList" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/ModelArtifactList" description: A response containing a list of ModelArtifact entities. ModelArtifactResponse: content: application/json: schema: - $ref: "#/components/schemas/ModelArtifact" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/ModelArtifact" description: A response containing a `ModelArtifact` entity. ModelVersionListResponse: content: application/json: schema: - $ref: "#/components/schemas/ModelVersionList" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/ModelVersionList" description: A response containing a list of `ModelVersion` entities. ModelVersionResponse: content: application/json: schema: - $ref: "#/components/schemas/ModelVersion" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/ModelVersion" description: A response containing a `ModelVersion` entity. RegisteredModelListResponse: content: application/json: schema: - $ref: "#/components/schemas/RegisteredModelList" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/RegisteredModelList" description: A response containing a list of `RegisteredModel` entities. RegisteredModelResponse: content: application/json: schema: - $ref: "#/components/schemas/RegisteredModel" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/RegisteredModel" description: A response containing a `RegisteredModel` entity. ArtifactResponse: content: application/json: schema: - $ref: "#/components/schemas/Artifact" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/Artifact" description: A response containing an `Artifact` entity. ArtifactListResponse: content: application/json: schema: - $ref: "#/components/schemas/ArtifactList" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/ArtifactList" description: A response containing a list of `Artifact` entities. ServingEnvironmentListResponse: content: application/json: schema: - $ref: "#/components/schemas/ServingEnvironmentList" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/ServingEnvironmentList" description: A response containing a list of `ServingEnvironment` entities. ServingEnvironmentResponse: content: application/json: schema: - $ref: "#/components/schemas/ServingEnvironment" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/ServingEnvironment" description: A response containing a `ServingEnvironment` entity. InferenceServiceListResponse: content: application/json: schema: - $ref: "#/components/schemas/InferenceServiceList" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/InferenceServiceList" description: A response containing a list of `InferenceService` entities. InferenceServiceResponse: content: application/json: schema: - $ref: "#/components/schemas/InferenceService" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/InferenceService" description: A response containing a `InferenceService` entity. ServeModelListResponse: content: application/json: schema: - $ref: "#/components/schemas/ServeModelList" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/ServeModelList" description: A response containing a list of `ServeModel` entities. ServeModelResponse: content: application/json: schema: - $ref: "#/components/schemas/ServeModel" + type: object + properties: + metadata: + type: object + description: Metadata about the response + data: + $ref: "#/components/schemas/ServeModel" description: A response containing a `ServeModel` entity. parameters: modelRegistryName: diff --git a/clients/ui/docker-compose.yaml b/clients/ui/docker-compose.yaml index 6c5f4bd74..7fbc2c8ca 100644 --- a/clients/ui/docker-compose.yaml +++ b/clients/ui/docker-compose.yaml @@ -5,7 +5,7 @@ services: ports: - 8080:8080 environment: - API_URL: http://model-registry-bff:4001 + API_URL: http://model-registry-bff:4000 networks: - model_registry depends_on: @@ -15,6 +15,7 @@ services: container_name: model-registry-bff command: - "--mock-k8s-client=true" + - "--mock-mr-client=true" networks: - model_registry diff --git a/clients/ui/frontend/Dockerfile b/clients/ui/frontend/Dockerfile index 0e787fdee..c25a2b1c6 100644 --- a/clients/ui/frontend/Dockerfile +++ b/clients/ui/frontend/Dockerfile @@ -10,7 +10,7 @@ RUN npm run build FROM nginxinc/nginx-unprivileged -ENV API_URL="http://localhost:4001" +ENV API_URL="http://localhost:4000" ENV NGINX_ENVSUBST_FILTER="API_URL" COPY --from=build-stage /usr/src/app/dist/ "/usr/share/nginx/html" diff --git a/clients/ui/frontend/README.md b/clients/ui/frontend/README.md index c8f062d7d..63ca41ba7 100644 --- a/clients/ui/frontend/README.md +++ b/clients/ui/frontend/README.md @@ -7,7 +7,7 @@ The Kubeflow Model Registry UI is a standalone web app for Kubeflow Model Registry. -## Contributing: +## Contributing Individual bug fixes are welcome, it is recommended that you create a bug [issue] at the same time to describe the fix you're applying. If you are unsure how best to solve it, start with the issue and note your desire to contribute. diff --git a/clients/ui/frontend/docs/dev-setup.md b/clients/ui/frontend/docs/dev-setup.md index 327a40577..2fe6e9653 100644 --- a/clients/ui/frontend/docs/dev-setup.md +++ b/clients/ui/frontend/docs/dev-setup.md @@ -8,10 +8,6 @@ This project requires the following tools to be installed on your system: - Node recommended version -> `20.17.0` - NPM recommended version -> `10.8.2` -### Additional tooling - -[TBD] - ## Development 1. Clone the repository diff --git a/clients/ui/manifests/base/kustomization.yaml b/clients/ui/manifests/base/kustomization.yaml index 4c9472a1d..939b4d754 100644 --- a/clients/ui/manifests/base/kustomization.yaml +++ b/clients/ui/manifests/base/kustomization.yaml @@ -7,6 +7,7 @@ resources: - model-registry-bff-deployment.yaml - model-registry-ui-service.yaml - model-registry-ui-deployment.yaml + - model-registry-service-account.yaml images: - name: model-registry-ui-image diff --git a/clients/ui/manifests/base/model-registry-bff-deployment.yaml b/clients/ui/manifests/base/model-registry-bff-deployment.yaml index 311aaebd5..27a2b5998 100644 --- a/clients/ui/manifests/base/model-registry-bff-deployment.yaml +++ b/clients/ui/manifests/base/model-registry-bff-deployment.yaml @@ -14,6 +14,7 @@ spec: labels: app: model-registry-bff spec: + serviceAccountName: model-registry-bff containers: - name: model-registry-bff image: model-registry-bff-image diff --git a/clients/ui/manifests/base/model-registry-bff-role.yaml b/clients/ui/manifests/base/model-registry-bff-role.yaml index 6b5ea1954..82a210855 100644 --- a/clients/ui/manifests/base/model-registry-bff-role.yaml +++ b/clients/ui/manifests/base/model-registry-bff-role.yaml @@ -15,7 +15,7 @@ metadata: name: bff-read-services subjects: - kind: ServiceAccount - name: default + name: model-registry-bff namespace: kubeflow roleRef: kind: ClusterRole diff --git a/clients/ui/manifests/base/model-registry-service-account.yaml b/clients/ui/manifests/base/model-registry-service-account.yaml new file mode 100644 index 000000000..86cbfc9b6 --- /dev/null +++ b/clients/ui/manifests/base/model-registry-service-account.yaml @@ -0,0 +1,4 @@ +kind: ServiceAccount +apiVersion: v1 +metadata: + name: model-registry-bff \ No newline at end of file diff --git a/clients/ui/manifests/base/model-registry-ui-deployment.yaml b/clients/ui/manifests/base/model-registry-ui-deployment.yaml index 3e0e9a055..23c55eb07 100644 --- a/clients/ui/manifests/base/model-registry-ui-deployment.yaml +++ b/clients/ui/manifests/base/model-registry-ui-deployment.yaml @@ -26,3 +26,6 @@ spec: memory: 2Gi ports: - containerPort: 8080 + env: + - name: API_URL + value: "http://model-registry-bff-service:4000" diff --git a/clients/ui/scripts/deploy_kind_cluster.sh b/clients/ui/scripts/deploy_kind_cluster.sh new file mode 100755 index 000000000..a3500aa1b --- /dev/null +++ b/clients/ui/scripts/deploy_kind_cluster.sh @@ -0,0 +1,46 @@ +#!/bin/bash + +# Check for required tools +command -v docker >/dev/null 2>&1 || { echo >&2 "Docker is required but it's not installed. Aborting."; exit 1; } +command -v kubectl >/dev/null 2>&1 || { echo >&2 "kubectl is required but it's not installed. Aborting."; exit 1; } +command -v kind >/dev/null 2>&1 || { echo >&2 "kind is required but it's not installed. Aborting."; exit 1; } + +if kubectl get deployment model-registry-deployment -n kubeflow >/dev/null 2>&1; then + echo "Model Registry deployment already exists. Skipping to step 4." +else + # Step 1: Create a kind cluster + echo "Creating kind cluster..." + kind create cluster + + # Verify cluster creation + echo "Verifying cluster..." + kubectl cluster-info + + # Step 2: Create kubeflow namespace + echo "Creating kubeflow namespace..." + kubectl create namespace kubeflow + + # Step 3: Deploy Model Registry to cluster + echo "Deploying Model Registry to cluster..." + kubectl apply -k "https://github.com/alexcreasy/model-registry/manifests/kustomize/overlays/db?ref=kind" + + # Wait for deployment to be available + echo "Waiting for Model Registry deployment to be available..." + kubectl wait --for=condition=available -n kubeflow deployment/model-registry-deployment --timeout=1m + + # Verify deployment + echo "Verifying deployment..." + kubectl get pods -n kubeflow +fi + +# Step 4: Deploy model registry UI +echo "Deploying Model Registry UI..." +kubectl apply -n kubeflow -k ./manifests/base + +# Wait for deployment to be available +echo "Waiting Model Registry UI to be available..." +kubectl wait --for=condition=available -n kubeflow deployment/model-registry-ui --timeout=1m + +# Step 5: Port-forward the service +echo "Model Registry should be available in localhost:8080" +kubectl port-forward svc/model-registry-ui-service -n kubeflow 8080:8080