feat(ws): Notebooks 2.0 // Backend // API that allows frontend to upload a YAML file containing a full new WorkspaceKind definition

asaadbalum · asaadbalum · commit 14ce8d16d940 · 2025-06-23T10:19:13.000+03:00
Signed-off-by: Asaad Balum &lt;asaad.balum@gmail.com&gt;
diff --git a/workspaces/backend/api/app.go b/workspaces/backend/api/app.go
@@ -56,6 +56,9 @@ const (
 	// swagger
 	SwaggerPath    = PathPrefix + "/swagger/*any"
 	SwaggerDocPath = PathPrefix + "/swagger/doc.json"
+
+	// YAML manifest content type
+	ContentTypeYAMLManifest = "application/vnd.kubeflow-notebooks.manifest+yaml"
 )
 
 type App struct {
@@ -106,6 +109,7 @@ func (a *App) Routes() http.Handler {
 	// workspacekinds
 	router.GET(AllWorkspaceKindsPath, a.GetWorkspaceKindsHandler)
 	router.GET(WorkspaceKindsByNamePath, a.GetWorkspaceKindHandler)
+	router.POST(AllWorkspaceKindsPath, a.CreateWorkspaceKindHandler)
 
 	// swagger
 	router.GET(SwaggerPath, a.GetSwaggerHandler)
diff --git a/workspaces/backend/api/helpers.go b/workspaces/backend/api/helpers.go
@@ -19,9 +19,12 @@ package api
 import (
 	"encoding/json"
 	"fmt"
+	"io"
 	"mime"
 	"net/http"
 	"strings"
+
+	"sigs.k8s.io/yaml"
 )
 
 // Envelope is the body of all requests and responses that contain data.
@@ -94,3 +97,25 @@ func (a *App) LocationGetWorkspace(namespace, name string) string {
 	path = strings.Replace(path, ":"+ResourceNamePathParam, name, 1)
 	return path
 }
+
+// ParseYAMLBody decodes the YAML request body into the given destination value.
+// It returns false and handles writing the HTTP error response if parsing fails.
+func (a *App) ParseYAMLBody(w http.ResponseWriter, r *http.Request, dst interface{}) bool {
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		a.badRequestResponse(w, r, err)
+		return false
+	}
+	defer func() {
+		if err := r.Body.Close(); err != nil {
+			fmt.Printf("warning: failed to close body: %v\n", err)
+		}
+	}()
+
+	if err := yaml.Unmarshal(body, dst); err != nil {
+		a.badRequestResponse(w, r, fmt.Errorf("failed to parse YAML manifest: %w", err))
+		return false
+	}
+
+	return true
+}
diff --git a/workspaces/backend/api/workspacekinds_handler.go b/workspaces/backend/api/workspacekinds_handler.go
@@ -125,3 +125,66 @@ func (a *App) GetWorkspaceKindsHandler(w http.ResponseWriter, r *http.Request, _
 	responseEnvelope := &WorkspaceKindListEnvelope{Data: workspaceKinds}
 	a.dataResponse(w, r, responseEnvelope)
 }
+
+// CreateWorkspaceKindHandler creates a new workspace kind from a YAML manifest.
+
+// @Summary		Create workspace kind
+// @Description	Creates a new workspace kind from a raw YAML manifest.
+// @Tags			workspacekinds
+// @Accept			application/vnd.kubeflow-notebooks.manifest+yaml
+// @Produce		json
+// @Param			body	body		string					true	"Raw YAML manifest of the WorkspaceKind"
+// @Success		201		{object}	WorkspaceKindEnvelope	"Successful creation. Returns the newly created workspace kind details."
+// @Failure		400		{object}	ErrorEnvelope			"Bad Request. The YAML is invalid or a required field is missing."
+// @Failure		401		{object}	ErrorEnvelope			"Unauthorized. Authentication is required."
+// @Failure		403		{object}	ErrorEnvelope			"Forbidden. User does not have permission to create the workspace kind."
+// @Failure		415		{object}	ErrorEnvelope			"Unsupported Media Type. Content-Type header is not correct."
+// @Failure		500		{object}	ErrorEnvelope			"Internal server error."
+// @Router			/workspacekinds [post]
+func (a *App) CreateWorkspaceKindHandler(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
+	// === Content-Type check ===
+	if ok := a.ValidateContentType(w, r, ContentTypeYAMLManifest); !ok {
+		return
+	}
+
+	// === Read body and parse YAML ===
+	var newWsk kubefloworgv1beta1.WorkspaceKind
+	if ok := a.ParseYAMLBody(w, r, &newWsk); !ok {
+		return
+	}
+
+	// === Validate name exists in YAML ===
+	if newWsk.Name == "" {
+		a.failedValidationResponse(w, r, "'.metadata.name' is a required field", field.ErrorList{
+			field.Required(field.NewPath("metadata").Child("name"), "must not be empty"),
+		}, nil)
+		return
+	}
+
+	// === AUTH ===
+	authPolicies := []*auth.ResourcePolicy{
+		auth.NewResourcePolicy(
+			auth.ResourceVerbCreate,
+			&kubefloworgv1beta1.WorkspaceKind{
+				ObjectMeta: metav1.ObjectMeta{Name: newWsk.Name},
+			},
+		),
+	}
+	if success := a.requireAuth(w, r, authPolicies); !success {
+		return
+	}
+
+	// === Create ===
+	createdModel, err := a.repositories.WorkspaceKind.Create(r.Context(), &newWsk)
+	if err != nil {
+		a.serverErrorResponse(w, r, err)
+		return
+	}
+
+	// === Return created object in envelope ===
+	responseEnvelope := &WorkspaceKindEnvelope{Data: createdModel}
+	err = a.WriteJSON(w, http.StatusCreated, responseEnvelope, nil)
+	if err != nil {
+		a.logger.Error("failed to write success response", "error", err)
+	}
+}
diff --git a/workspaces/backend/api/workspacekinds_handler_test.go b/workspaces/backend/api/workspacekinds_handler_test.go
@@ -17,6 +17,7 @@ limitations under the License.
 package api
 
 import (
+	"bytes"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -254,4 +255,124 @@ var _ = Describe("WorkspaceKinds Handler", func() {
 			Expect(rs.StatusCode).To(Equal(http.StatusNotFound), descUnexpectedHTTPStatus, rr.Body.String())
 		})
 	})
+
+	// NOTE: these tests create and delete resources on the cluster, so cannot be run in parallel.
+	//       therefore, we run them using the `Serial` Ginkgo decorator.
+	Context("when creating a WorkspaceKind", Serial, func() {
+
+		var newWorkspaceKindName = "wsk-create-test"
+
+		AfterEach(func() {
+			By("cleaning up the created WorkspaceKind")
+			wsk := &kubefloworgv1beta1.WorkspaceKind{
+				ObjectMeta: metav1.ObjectMeta{
+					Name: newWorkspaceKindName,
+				},
+			}
+			_ = k8sClient.Delete(ctx, wsk)
+		})
+
+		It("should succeed when creating a new WorkspaceKind with valid YAML", func() {
+			By("defining the final, complete, and valid YAML payload")
+			// This YAML now includes the icon and logo fields required by the API server.
+			validYAML := []byte(fmt.Sprintf(`
+apiVersion: workspaces.kubeflow.org/v1beta1
+kind: WorkspaceKind
+metadata:
+  name: %s
+spec:
+  spawner:
+    displayName: "Test Jupyter Environment"
+    description: "A valid description for testing."
+    icon:
+      url: "https://example.com/icon.png"
+    logo:
+      url: "https://example.com/logo.svg"
+  podTemplate:
+    options:
+      imageConfig:
+        spawner:
+          default: "default-image"
+        values:
+        - id: "default-image"
+          name: "Jupyter Scipy"
+          path: "kubeflownotebooks/jupyter-scipy:v1.9.0"
+          spawner:
+            displayName: "Jupyter with SciPy v1.9.0"
+          spec:
+            image: "kubeflownotebooks/jupyter-scipy:v1.9.0"
+            ports:
+            - id: "notebook-port"
+              displayName: "Notebook Port"
+              port: 8888
+              protocol: "HTTP"
+      podConfig:
+        spawner:
+          default: "default-pod-config"
+        values:
+        - id: "default-pod-config"
+          name: "Default Resources"
+          spawner:
+            displayName: "Small CPU/RAM"
+          resources:
+            requests:
+              cpu: "500m"
+              memory: "1Gi"
+            limits:
+              cpu: "1"
+              memory: "2Gi"
+    volumeMounts:
+      home: "/home/jovyan"
+`, newWorkspaceKindName))
+
+			By("creating the HTTP request")
+			req, err := http.NewRequest(http.MethodPost, AllWorkspaceKindsPath, bytes.NewReader(validYAML))
+			Expect(err).NotTo(HaveOccurred())
+			req.Header.Set("Content-Type", "application/vnd.kubeflow-notebooks.manifest+yaml")
+			req.Header.Set(userIdHeader, adminUser)
+
+			By("executing the CreateWorkspaceKindHandler")
+			rr := httptest.NewRecorder()
+			a.CreateWorkspaceKindHandler(rr, req, httprouter.Params{})
+			rs := rr.Result()
+			defer rs.Body.Close()
+
+			By("verifying the HTTP response status code is 201 Created")
+			Expect(rs.StatusCode).To(Equal(http.StatusCreated), "Body: %s", rr.Body.String())
+
+			By("verifying the resource was created in the cluster")
+			createdWsk := &kubefloworgv1beta1.WorkspaceKind{}
+			err = k8sClient.Get(ctx, types.NamespacedName{Name: newWorkspaceKindName}, createdWsk)
+			Expect(err).NotTo(HaveOccurred())
+		})
+		It("should fail if the YAML is syntactically invalid", func() {
+			By("defining a string that is not valid YAML")
+			// This text has incorrect indentation and structure.
+			invalidYAML := []byte(`
+apiVersion: v1
+kind: WorkspaceKind
+metadata
+  name: broken-yaml
+`)
+
+			By("creating the HTTP request")
+			req, err := http.NewRequest(http.MethodPost, AllWorkspaceKindsPath, bytes.NewReader(invalidYAML))
+			Expect(err).NotTo(HaveOccurred())
+			req.Header.Set("Content-Type", "application/vnd.kubeflow-notebooks.manifest+yaml")
+			req.Header.Set(userIdHeader, adminUser)
+
+			By("executing the CreateWorkspaceKindHandler")
+			rr := httptest.NewRecorder()
+			a.CreateWorkspaceKindHandler(rr, req, httprouter.Params{})
+			rs := rr.Result()
+			defer rs.Body.Close()
+
+			By("verifying the handler returns a 400 Bad Request with a valid error envelope")
+			Expect(rs.StatusCode).To(Equal(http.StatusBadRequest))
+			var response ErrorEnvelope
+			err = json.Unmarshal(rr.Body.Bytes(), &response)
+			Expect(err).NotTo(HaveOccurred(), "The error response should be valid JSON")
+			Expect(response.Error.Message).To(ContainSubstring("failed to parse YAML manifest"))
+		})
+	})
 })
diff --git a/workspaces/backend/internal/repositories/workspacekinds/repo.go b/workspaces/backend/internal/repositories/workspacekinds/repo.go
@@ -28,6 +28,7 @@ import (
 )
 
 var ErrWorkspaceKindNotFound = errors.New("workspace kind not found")
+var ErrWorkspaceKindAlreadyExists = errors.New("workspacekind already exists")
 
 type WorkspaceKindRepository struct {
 	client client.Client
@@ -68,3 +69,21 @@ func (r *WorkspaceKindRepository) GetWorkspaceKinds(ctx context.Context) ([]mode
 
 	return workspaceKindsModels, nil
 }
+
+func (r *WorkspaceKindRepository) Create(ctx context.Context, wk *kubefloworgv1beta1.WorkspaceKind) (models.WorkspaceKind, error) {
+	if err := r.client.Create(ctx, wk); err != nil {
+		if apierrors.IsAlreadyExists(err) {
+			return models.WorkspaceKind{}, ErrWorkspaceKindAlreadyExists
+		}
+		if apierrors.IsInvalid(err) {
+			// NOTE: we don't wrap this error so we can unpack it in the caller
+			return models.WorkspaceKind{}, err
+		}
+		return models.WorkspaceKind{}, err
+	}
+
+	// Convert the created k8s object to our backend model before returning
+	createdModel := models.NewWorkspaceKindModelFromWorkspaceKind(wk)
+
+	return createdModel, nil
+}
diff --git a/workspaces/backend/openapi/docs.go b/workspaces/backend/openapi/docs.go
@@ -127,6 +127,68 @@ const docTemplate = `{
                         }
                     }
                 }
+            },
+            "post": {
+                "description": "Creates a new workspace kind from a raw YAML manifest.",
+                "consumes": [
+                    "application/vnd.kubeflow-notebooks.manifest+yaml"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "workspacekinds"
+                ],
+                "summary": "Create workspace kind",
+                "parameters": [
+                    {
+                        "description": "Raw YAML manifest of the WorkspaceKind",
+                        "name": "body",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Successful creation. Returns the newly created workspace kind details.",
+                        "schema": {
+                            "$ref": "#/definitions/api.WorkspaceKindEnvelope"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request. The YAML is invalid or a required field is missing.",
+                        "schema": {
+                            "$ref": "#/definitions/api.ErrorEnvelope"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized. Authentication is required.",
+                        "schema": {
+                            "$ref": "#/definitions/api.ErrorEnvelope"
+                        }
+                    },
+                    "403": {
+                        "description": "Forbidden. User does not have permission to create the workspace kind.",
+                        "schema": {
+                            "$ref": "#/definitions/api.ErrorEnvelope"
+                        }
+                    },
+                    "415": {
+                        "description": "Unsupported Media Type. Content-Type header is not correct.",
+                        "schema": {
+                            "$ref": "#/definitions/api.ErrorEnvelope"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal server error.",
+                        "schema": {
+                            "$ref": "#/definitions/api.ErrorEnvelope"
+                        }
+                    }
+                }
             }
         },
         "/workspacekinds/{name}": {
diff --git a/workspaces/backend/openapi/swagger.json b/workspaces/backend/openapi/swagger.json
diff --git a/workspaces/backend/openapi/swagger.yaml b/workspaces/backend/openapi/swagger.yaml
