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

Signed-off-by: Asaad Balum <[email protected]>

Author: asaadbalum

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)

workspaces/backend/api/helpers.go

@@ -18,10 +18,14 @@ package api
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
+	"io"
 	"mime"
 	"net/http"
 	"strings"
+
+	"sigs.k8s.io/yaml"
 )
 
 // Envelope is the body of all requests and responses that contain data.
@@ -94,3 +98,44 @@ func (a *App) LocationGetWorkspace(namespace, name string) string {
 	path = strings.Replace(path, ":"+ResourceNamePathParam, name, 1)
 	return path
 }
+
+// ParseYAMLBody reads and decodes a YAML request body into a given destination value,
+// after first verifying the 'kind' field in the YAML matches the expectedKind.
+// It returns false and handles writing the HTTP error response on any failure.
+func (a *App) ParseYAMLBody(w http.ResponseWriter, r *http.Request, dst interface{}, expectedKind string) bool {
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		a.badRequestResponse(w, r, errors.New("failed to read request body"))
+		return false
+	}
+	defer func() {
+		if err := r.Body.Close(); err != nil {
+			a.LogWarn(r, fmt.Sprintf("failed to close request body: %v", err))
+		}
+	}()
+
+	// First, check the 'kind' field without parsing the whole object.
+	type kindCheck struct {
+		Kind string `yaml:"kind"`
+	}
+	var kc kindCheck
+	if err := yaml.Unmarshal(body, &kc); err != nil {
+		// This handles files that are not valid YAML at all.
+		a.badRequestResponse(w, r, errors.New("request body is not a valid YAML manifest"))
+		return false
+	}
+
+	// Now, validate the 'kind'.
+	if kc.Kind != expectedKind {
+		a.badRequestResponse(w, r, fmt.Errorf("invalid kind in YAML: expected '%s', got '%s'", expectedKind, kc.Kind))
+		return false
+	}
+
+	// If kind is correct, parse the full object into the destination struct.
+	if err := yaml.Unmarshal(body, dst); err != nil {
+		a.badRequestResponse(w, r, fmt.Errorf("request body is not a valid YAML manifest for a %s", expectedKind))
+		return false
+	}
+
+	return true
+}

workspaces/backend/api/workspacekinds_handler.go

@@ -18,6 +18,7 @@ package api
 
 import (
 	"errors"
+	"fmt"
 	"net/http"
 
 	"github.com/julienschmidt/httprouter"
@@ -125,3 +126,70 @@ 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		409		{object}	ErrorEnvelope			"Conflict. A WorkspaceKind with the same name already exists."
+// @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, check kind, and parse YAML all in one step ===
+	var newWsk kubefloworgv1beta1.WorkspaceKind
+	if ok := a.ParseYAMLBody(w, r, &newWsk, "WorkspaceKind"); !ok {
+		return
+	}
+
+	// === Validate name exists in YAML ===
+	if newWsk.Name == "" {
+		a.badRequestResponse(w, r, errors.New("'.metadata.name' is a required field in the YAML manifest"))
+		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 {
+		if errors.Is(err, repository.ErrWorkspaceKindAlreadyExists) {
+			a.conflictResponse(w, r, err)
+			return
+		}
+		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 {
+		err = fmt.Errorf("failed to write success response: %w", err)
+		a.LogError(r, err)
+	}
+}

workspaces/backend/api/workspacekinds_handler_test.go

@@ -17,6 +17,7 @@ limitations under the License.
 package api
 
 import (
+	"bytes"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -195,8 +196,6 @@ var _ = Describe("WorkspaceKinds Handler", func() {
 		})
 	})
 
-	// NOTE: these tests assume a specific state of the cluster, so cannot be run in parallel with other tests.
-	//       therefore, we run them using the `Serial` Ginkgo decorators.
 	Context("with no existing WorkspaceKinds", Serial, func() {
 
 		It("should return an empty list of WorkspaceKinds", func() {
@@ -254,4 +253,192 @@ 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"
+		var validYAML []byte
+
+		BeforeEach(func() {
+			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))
+		})
+
+		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() {
+			req, err := http.NewRequest(http.MethodPost, AllWorkspaceKindsPath, bytes.NewReader(validYAML))
+			Expect(err).NotTo(HaveOccurred())
+			req.Header.Set("Content-Type", ContentTypeYAMLManifest)
+			req.Header.Set(userIdHeader, adminUser)
+
+			rr := httptest.NewRecorder()
+			a.CreateWorkspaceKindHandler(rr, req, httprouter.Params{})
+			rs := rr.Result()
+			defer rs.Body.Close()
+
+			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 with 400 Bad Request if the YAML is missing a required name", func() {
+			missingNameYAML := []byte(`
+apiVersion: workspaces.kubeflow.org/v1beta1
+kind: WorkspaceKind
+metadata: {}
+spec:
+  spawner:
+    displayName: "This will fail"`)
+			req, _ := http.NewRequest(http.MethodPost, AllWorkspaceKindsPath, bytes.NewReader(missingNameYAML))
+			req.Header.Set("Content-Type", ContentTypeYAMLManifest)
+			req.Header.Set(userIdHeader, adminUser)
+
+			rr := httptest.NewRecorder()
+			a.CreateWorkspaceKindHandler(rr, req, httprouter.Params{})
+
+			Expect(rr.Code).To(Equal(http.StatusBadRequest))
+			Expect(rr.Body.String()).To(ContainSubstring("'.metadata.name' is a required field"))
+		})
+
+		It("should return a 409 Conflict when creating a WorkspaceKind that already exists", func() {
+			By("creating the resource once successfully")
+			req1, _ := http.NewRequest(http.MethodPost, AllWorkspaceKindsPath, bytes.NewReader(validYAML))
+			req1.Header.Set("Content-Type", ContentTypeYAMLManifest)
+			req1.Header.Set(userIdHeader, adminUser)
+			rr1 := httptest.NewRecorder()
+			a.CreateWorkspaceKindHandler(rr1, req1, httprouter.Params{})
+			Expect(rr1.Code).To(Equal(http.StatusCreated))
+
+			By("attempting to create the exact same resource a second time")
+			req2, _ := http.NewRequest(http.MethodPost, AllWorkspaceKindsPath, bytes.NewReader(validYAML))
+			req2.Header.Set("Content-Type", ContentTypeYAMLManifest)
+			req2.Header.Set(userIdHeader, adminUser)
+			rr2 := httptest.NewRecorder()
+			a.CreateWorkspaceKindHandler(rr2, req2, httprouter.Params{})
+
+			Expect(rr2.Code).To(Equal(http.StatusConflict))
+		})
+
+		It("should fail with 400 Bad Request when the YAML has the wrong kind", func() {
+			wrongKindYAML := []byte(`apiVersion: v1
+kind: Pod
+metadata:
+  name: i-am-the-wrong-kind`)
+			req, _ := http.NewRequest(http.MethodPost, AllWorkspaceKindsPath, bytes.NewReader(wrongKindYAML))
+			req.Header.Set("Content-Type", ContentTypeYAMLManifest)
+			req.Header.Set(userIdHeader, adminUser)
+
+			rr := httptest.NewRecorder()
+			a.CreateWorkspaceKindHandler(rr, req, httprouter.Params{})
+
+			Expect(rr.Code).To(Equal(http.StatusBadRequest))
+			Expect(rr.Body.String()).To(ContainSubstring("invalid kind in YAML: expected 'WorkspaceKind', got 'Pod'"))
+		})
+
+		It("should fail when the body is not valid YAML", func() {
+			notYAML := []byte(`this is not yaml {`)
+			req, _ := http.NewRequest(http.MethodPost, AllWorkspaceKindsPath, bytes.NewReader(notYAML))
+			req.Header.Set("Content-Type", ContentTypeYAMLManifest)
+			req.Header.Set(userIdHeader, adminUser)
+
+			rr := httptest.NewRecorder()
+			a.CreateWorkspaceKindHandler(rr, req, httprouter.Params{})
+
+			By("verifying the handler returns a 400 Bad Request with a valid error envelope")
+			Expect(rr.Code).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(Equal("request body is not a valid YAML manifest"))
+		})
+		It("should fail with 400 Bad Request for an empty YAML object", func() {
+			By("defining an empty YAML object as the payload")
+			invalidYAML := []byte("{}")
+
+			By("creating the HTTP request")
+			req, err := http.NewRequest(http.MethodPost, AllWorkspaceKindsPath, bytes.NewReader(invalidYAML))
+			Expect(err).NotTo(HaveOccurred())
+			req.Header.Set("Content-Type", ContentTypeYAMLManifest)
+			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")
+			// First, check the status code
+			Expect(rs.StatusCode).To(Equal(http.StatusBadRequest))
+
+			By("verifying the error message in the response body")
+			// Second, read the body from the response stream
+			body, err := io.ReadAll(rs.Body)
+			Expect(err).NotTo(HaveOccurred()) // Ensure reading the body didn't cause an error
+
+			// Finally, assert on the content of the body
+			Expect(string(body)).To(ContainSubstring("invalid kind in YAML: expected 'WorkspaceKind', got ''"))
+		})
+	})
 })

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
+}