Updates to the apiserver swagger-ui (#1410)

Updates to the apiserver swagger-ui

.gitignore

@@ -43,4 +43,7 @@
 # Dependency directories (remove the comment below to include it)
 **/vendor/
 
-.ipynb_checkpoints
+.ipynb_checkpoints
+
+# Any file with a .backup extension
+**/*.backup

apiserver/DEVELOPMENT.md

@@ -25,6 +25,7 @@ Typing `make dev-tools` will download and install all of them. The `make clean-d
 | kustomize     | v3.8.7   | [install](https://kubectl.docs.kubernetes.io/installation/kustomize/)   |
 | gofumpt       | v0.3.1   | To install `go install mvdan.cc/[email protected]`                         |
 | goimports     | latest   | To install `go install golang.org/x/tools/cmd/goimports@latest`         |
+| go-bindata    | v4.0.2   | To install `github.com/kevinburke/go-bindata/v4/[email protected]`             |
 
 ## Purpose
 
@@ -60,6 +61,52 @@ make build
 make test
 ```
 
+#### Swagger UI updates
+
+To update the swagger ui files deployed with the Kuberay API server, you'll need to:
+
+* Manually run the [hack/update-swagger-ui.bash](hack/update-swagger-ui.bash) script. The script downloads the swagger ui release and copies the downloaded files
+to the [../third_party/swagger-ui](../third_party/swagger-ui/) directory. It copies the [swagger-initializer.js](../third_party/swagger-ui/swagger-initializer.js)
+to [swagger-initializer.js.backup](../third_party/swagger-ui/swagger-initializer.js.backup).
+* Update the contents of the [swagger-initializer.js](../third_party/swagger-ui/swagger-initializer.js) to set the URLs for for the individual swagger docs. The content of the file is show below:
+
+    ```javascript
+    window.onload = function() {
+    //<editor-fold desc="Changeable Configuration Block">
+
+    // the following lines will be replaced by docker/configurator, when it runs in a docker-container
+    window.ui = SwaggerUIBundle({
+        spec: location.host,
+        urls:  [{"url":"http://"+location.host+"/swagger/serve.swagger.json","name":"RayServe Service"},
+                {"url":"http://"+location.host+"/swagger/error.swagger.json","name":"Errors API"},
+                {"url":"http://"+location.host+"/swagger/job.swagger.json","name":"RayJob Service"},
+                {"url":"http://"+location.host+"/swagger/config.swagger.json","name":"ComputeTemplate Service"},
+                {"url":"http://"+location.host+"/swagger/cluster.swagger.json","name":"Cluster Service"}],
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+        SwaggerUIBundle.presets.apis,
+        SwaggerUIStandalonePreset
+        ],
+        plugins: [
+        SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: "StandaloneLayout"
+    });
+
+    //</editor-fold>
+    };
+    ```
+
+* Execute `make build-swagger` target to update the contents of the [datafile.go](pkg/swagger/datafile.go) file. This will package the content of the [swagger-ui](../third_party/swagger-ui/) directory for serving by the api server (see [func serveSwaggerUI(mux *http.ServeMux)](https://github.com/ray-project/kuberay/blob/f1067378bc99987f3eba1e5b12b4cc797465336d/apiserver/cmd/main.go#L149) in [main.go](cmd/main.go))
+
+The swagger ui is available at the following URLs:
+
+* [local service -- http://localhost:8888/swagger-ui/](http://localhost:8888/swagger-ui/)
+* [kind cluster -- http://localhost:31888/swagger-ui/](http://localhost:31888/swagger-ui/)
+
+Please note that for the local service the directory containing the `*.swagger.files` is specified using the `-localSwaggerPath` command line argument. The `make run` command sets the value correctly.
+
 #### Start Local Service
 
 This will start the api server on your development machine. The golang race detector is turned on when starting the api server this way. It will use Kubernetes configuration file located at `~/.kube/config`. The service will not start if you do not have a connection to a Kubernetes cluster.
@@ -110,7 +157,7 @@ make uninstall
 
 As a convenience for local development the following `make` targets are provided:
 
-* `make cluster` -- creates a local kind cluster, using the configuration from `hack/kind-cluster-config.yaml`. It creates a port mapping allowing for the service running in the kind cluster to be accessed on  `localhost:318888` for HTTP and `localhost:318887` for RPC.
+* `make cluster` -- creates a local kind cluster, using the configuration from `hack/kind-cluster-config.yaml`. It creates a port mapping allowing for the service running in the kind cluster to be accessed on  `localhost:31888` for HTTP and `localhost:31887` for RPC.
 * `make clean-cluster` -- deletes the local kind cluster created with `make cluster`
 * `load-image` -- loads the docker image defined by the `IMG` make variable into the kind cluster. The default value for variable is: `kuberay/apiserver:latest`. The name of the image can be changed by using `make load-image -e IMG=<your image name and tag>`
 * `operator-image` -- Build the operator image to be loaded in your kind cluster. The tag for the operator image is `kuberay/operator:latest`. This step is optional.
@@ -130,4 +177,4 @@ make docker-image operator-image cluster load-image load-operator-image deploy d
 
 #### Access API Server in the Cluster
 
-Access the service at `localhost:318888` for http and `locahost:318887` for the RPC port.
+Access the service at `localhost:31888` for http and `locahost:31887` for the RPC port.

apiserver/Makefile

@@ -1,6 +1,7 @@
 BUILD_TIME      := $(shell date "+%F %T")
 COMMIT_SHA1     := $(shell git rev-parse HEAD )
-REPO_ROOT_BIN	:= $(shell dirname ${PWD})/bin
+REPO_ROOT	    := $(shell dirname ${PWD})
+REPO_ROOT_BIN	:= $(REPO_ROOT)/bin
 
 # Image URL to use all building/pushing image targets
 IMG_TAG ?=latest
@@ -66,14 +67,18 @@ build: fmt vet fumpt imports lint ## Build api server binary.
 	go build  -o ${REPO_ROOT_BIN}/kuberay-apiserver cmd/main.go
 
 run: fmt vet fumpt imports lint ## Run the api server from your host.
-	go run -race cmd/main.go
+	go run -race cmd/main.go -localSwaggerPath ${REPO_ROOT}/proto/swagger
 
 docker-image: test ## Build image with the api server.
 	${ENGINE} build -t ${IMG} -f Dockerfile ..
 
 docker-push: ## Push image with the api server.
 	${ENGINE} push ${IMG}
 
+.PHONY: build-swagger
+build-swagger: go-bindata
+	cd $(REPO_ROOT) && $(GOBINDATA) --nocompress --pkg swagger -o apiserver/pkg/swagger/datafile.go third_party/swagger-ui/...
+
 ##@ Deployment
 .PHONY: install
 install: kustomize ## Install the kuberay api server to the K8s cluster specified in ~/.kube/config.
@@ -107,6 +112,7 @@ GOIMPORTS ?= $(REPO_ROOT_BIN)/goimports
 GOFUMPT ?= $(REPO_ROOT_BIN)/gofumpt
 GOLANGCI_LINT ?= $(REPO_ROOT_BIN)/golangci-lint
 KIND ?= $(REPO_ROOT_BIN)/kind
+GOBINDATA ?= $(REPO_ROOT_BIN)/go-bindata
 
 
 ## Tool Versions
@@ -115,6 +121,7 @@ GOFUMPT_VERSION ?= v0.3.1
 GOIMPORTS_VERSION ?= latest
 GOLANGCI_LINT_VERSION ?= v1.54.1
 KIND_VERSION ?= v0.19.0
+GOBINDATA_VERSION ?= v4.0.2
 
 KUSTOMIZE_INSTALL_SCRIPT ?= "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh"
 .PHONY: kustomize
@@ -142,8 +149,13 @@ kind: $(KIND) ## Download kind locally if necessary.
 $(KIND): $(REPO_ROOT_BIN)	
 	test -s $(KIND) || GOBIN=$(REPO_ROOT_BIN) go install sigs.k8s.io/kind@$(KIND_VERSION)
 
+.PHONY: go-bindata
+go-bindata: $(GOBINDATA) ## Download the go-bindata executable if necessary.
+$(GOBINDATA): $(REPO_ROOT_BIN)
+	test -s $(GOBINDATA) || GOBIN=$(REPO_ROOT_BIN) go install github.com/kevinburke/go-bindata/v4/...@$(GOBINDATA_VERSION)
+
 .PHONY: dev-tools
-dev-tools: kind golangci-lint gofumpt kustomize goimports ## Install all development tools
+dev-tools: kind golangci-lint gofumpt kustomize goimports go-bindata ## Install all development tools
 
 .PHONY: clean-dev-tools
 clean-dev-tools: ## Remove all development tools
@@ -152,6 +164,7 @@ clean-dev-tools: ## Remove all development tools
 	rm -f $(REPO_ROOT_BIN)/kustomize
 	rm -f $(REPO_ROOT_BIN)/goimports
 	rm -f $(REPO_ROOT_BIN)/kind
+	rm -f $(REPO_ROOT_BIN)/go-bindata
 
 
 ##@ Testing Setup and Tools

apiserver/cmd/main.go

@@ -34,6 +34,7 @@ var (
 	httpPortFlag       = flag.String("httpPortFlag", ":8888", "Http Proxy Port")
 	collectMetricsFlag = flag.Bool("collectMetricsFlag", true, "Whether to collect Prometheus metrics in API server.")
 	logFile            = flag.String("logFilePath", "", "Synchronize logs to local file")
+	localSwaggerPath   = flag.String("localSwaggerPath", "", "Specify the root directory for `*.swagger.json` the swagger files.")
 	healthy            int32
 )
 
@@ -159,10 +160,13 @@ func serveSwaggerFile(w http.ResponseWriter, r *http.Request) {
 	}
 
 	p := strings.TrimPrefix(r.URL.Path, "/swagger/")
-	// Currently, we copy swagger.json to system root /workspace/proto/swagger/.
-	// For the development, you can change path to `../proto/swagger`.
-	// TODO(Jeffwan@): fix this later, we should not have dependency on system folder structure.
-	p = path.Join("/workspace/proto/swagger/", p)
+	if strings.TrimSpace(*localSwaggerPath) != "" {
+		// use the specified path,  for development the is  `${REPO_ROOT}/proto/swagger`.
+		p = path.Join(*localSwaggerPath, "/", p)
+	} else {
+		// In docker images the *.swagger.json are copied to `/workspace/proto/swagger/``.
+		p = path.Join("/workspace/proto/swagger/", p)
+	}
 
 	klog.Infof("Serving swagger-file: %s", p)
 	http.ServeFile(w, r, p)

apiserver/hack/update-swagger-ui.bash

@@ -0,0 +1,20 @@
+#!/bin/bash
+set -e
+set -x
+readonly REPO_ROOT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )"/../.. &> /dev/null && pwd)
+readonly TARGET_DIR="${REPO_ROOT_DIR}/third_party/swagger-ui"
+readonly SWAGGER_UI_VERSION=${1:-"5.4.1"}
+readonly SWAGGER_UI_TAR_URL="https://github.com/swagger-api/swagger-ui/archive/refs/tags/v${SWAGGER_UI_VERSION}.tar.gz"
+
+if [ -f ${TARGET_DIR}/swagger-initializer.js ];then
+    cp -v ${TARGET_DIR}/swagger-initializer.js ${TARGET_DIR}/swagger-initializer.js.backup
+fi
+echo "Downloading '${SWAGGER_UI_TAR_URL}' to update ${TARGET_DIR}"
+tmp="$(mktemp -d)"
+#pushd .
+curl --output-dir ${tmp} --fail --silent --location --remote-header-name --remote-name ${SWAGGER_UI_TAR_URL} 
+tar -xzvf ${tmp}/swagger-ui-${SWAGGER_UI_VERSION}.tar.gz -C ${tmp}
+#popd
+cp -rv "$tmp/swagger-ui-${SWAGGER_UI_VERSION}/dist/"* "${TARGET_DIR}"
+rm -rf "$tmp"
+