[TASK] WorkspaceKind `POST`/`PUT` APIs allow frontend to validate YAML payload without persisting changes

[andyatmiami]

🛑 Blocked by:

• [TASK] API that allows frontend to upload a YAML file containing a full new WorkspaceKind definition #278
• [TASK] API that allows frontend to update a WorkspaceKind by uploading a YAML file containing a full WorkspaceKind definition #416

Description

Initially, the frontend will have the user submit raw YAML WorkspaceKind manifests for the POST (create) and PUT (update) endpoints of the /workspacekinds API suite. As that YAML can be quite large (particularly as the number of options for podConfig and imageConfig grows) - we want users to have a sense of confidence prior to them submitting the payload to apply to the cluster.

Inspired by k8s, we want to add support for a ?dry_run=true|false query parameter to the following endpoints:

• POST api/v1/workspacekinds
• PUT api/v1/workspacekinds/{name}

The default value for dry_run (in the event it is not specified) is false. When dry_run=false, it is essentially a no-op and the "normal" behavior to create/update the WorkspaceKind proceeds as usual.

When dry_run=true, the following constraints apply:

• under no circumstances are changes introduced to k8s as a result of the API call
• a dry_run is performed at the kubernetes layer (see: CreateOptions , UpdateOptions )
  • if no error(s) occur as a result of the dry_run:
    • for POST, the application/json data representation of the WorkspaceKind defined in the YAML is returned
      • Content-Type: application/json header returned on response
    • for PUT, the application/json data representation of the WorkspaceKind persistend on the cluster is returned
      • Content-Type: application/json header returned on response
      • ℹ while this behavior is at face value misaligned with POST behavior, we believe returning the currently persisted object in this case has more future upside to potentially allow UI to emphasize detected changes
  • if error(s) occur as a result of the dry_run, those errors are returned in the response payload using the standard Error API schema

?dry_run query parameter should only be honored if Content-Type: application/yaml provided on the request. In the event dry_run query parameter is provided, and a valid Content-Type that is not equal to Content-Type: application/yamlis on the request - a400` HTTP response code should be returned.

• This likely is irrelevant at this point as Content-Type: application/yaml is the only supported Content-Type (and a request providing any other header value would/should/could first fail with a 415)

💡 Given the obvious overlap in functionality across POST and PUT, the decision was made to raise this issue under a single ticket. We can certainly split this work into issues for each endpoint - but then need to be mindful that they are consistent and leveraging shared code upon. merging.

Acceptance Criteria

• Calling POST api/v1/workspacekinds?dry_run=false behaves identically to POST api/v1/workspacekinds
  • i.e. the WorkspaceKind is created (if valid) or returns error from attempting to apply to cluster
• Calling PUT api/v1/workspacekinds/{name}?dry_run=false behaves identically to PUT api/v1/workspacekinds
  • i.e. the WorkspaceKind is updated (if valid) or returns error from attempting to apply to cluster
• Calling POST api/v1/workspacekinds?dry_run=true on a valid manifest payload returns an application/json response following same schema as GET api/v1/workspacekinds/{name} when Content-Type: application/json header present
  • the application/json response is a representation of the WorkspaceKind as defined in the request payload
• Calling PUT api/v1/workspacekinds/{name}?dry_run=true on a valid manifest payload returns an application/json response following same schema as GET api/v1/workspacekinds/{name} when Content-Type: application/json header present
  • the application/json response is a representation of the WorkspaceKind as its currently persisted on the cluster
• Calling POST api/v1/workspacekinds?dry_run=true on an invalid manifest payload returns an application/json response following Error schema used in Notebooks 2.0
  • all errors returned from attempting to dry_run via the controller-runtime client should be encoded in response
• Calling POST api/v1/workspacekinds?dry_run=true on an invalid manifest payload returns an application/json response following Error schema used in Notebooks 2.0
  • all errors returned from attempting to dry_run via the controller-runtime client should be encoded in response
• Providing any value to the dry_run query parameter argument that is not equal to one of (true, false) should return a 400 error

[andyatmiami]

/area v2
/area backend

[bhaktinarvekar]

/assign