feat(ws): add workspace pause actions backend API

[andyatmiami]

related: #298

• Added PauseActionWorkspaceHandler to handle pausing or unpausing a given workspace
• Introduced single new route for starting and pausing workspaces in the API.
  • api/v1/workspaces/{namespace}/{name}/actions/pause
    - pausing or unpausing operation is specified in the request payload
• Created a new WorkspaceActionPauseEnvelope type for successful responses.
• Leveraging JSONPatch / client.RawPatch to ensure Workspace in "valid state" before attempting action
  • for start: spec.paused must be true, and status.state must be Paused
  • for pause: spec.paused must be false
    • note: I would love to have a status.state check here of status.state != Paused, but that type of comparison is not supported in JSONPatch
• Added tests for the new API, including success and error cases.
• Updated README/OpenAPI documentation to include the new endpoints.

---

As an interesting "edge case" worth calling out, the following payload is currently honored by the API:

{
  "data": {}
}

Given the WorkspaceActionPause struct is simply {"paused": true|false}, the "empty" Envelope presented above deserializes the JSON using the zero value of bool (which is false).

Our validation today is always performed against the deserialized object, and as such impossible to distinguish the following cases w.r.t actual JSON request payload:

{
  "data": {}
}

vs

{
  "data": {
    "paused": false
  }
}

The effort and (relative) complexity to prevent this and return a 422 in this scenario was not deemed "worth it" for the time being. As a result, a test case has been added for this specific scenario to at minimum document this "strange" behavior.

• Clients, however, should NOT rely on this behavior and always provide a fully defined WorkspaceActionPause JSON object to ensure future compatibility.

Rendered Swagger doc:

[ederign]

/ok-to-test

[harshad16]

Great work 💯
Tested with cli:

[ederign]

Some questions inline.

[harshad16]

The new changes looks great, with return payload
Tested it with running system:

Works as intended.

great work 💯

/lgtm

[google-oss-prow]

@harshad16: changing LGTM is restricted to collaborators

In response to this:

The new changes looks great, with return payload
Tested it with running system:

Works as intended.

great work 💯

/lgtm

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[thesuperzapper]

I left a few comments (we were on a call during the review so @andyatmiami should be aware of what to do and we were in agreement on the changes).

[andyatmiami]

Verifying behavior

Check existing state

➜ backend/ git:(feat/workspace-start-api) $ kubectl get workspaces -A
NAMESPACE   NAME                         STATE
default     jupyterlab-scipy-workspace   Running
default     jupyterlab-workspace         Running

Pause running jupyterlab-workspace workspace

➜ backend/ git:(feat/workspace-start-api) $ curl -X 'POST' \
  'http://localhost:4000/api/v1/workspaces/default/jupyterlab-workspace/actions/pause' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "data": {
    "paused": true
  }
}'

{
	"data": {
		"paused": true
	}
}

Verify jupyterlab-workspace now paused

➜ backend/ git:(feat/workspace-start-api) $ kubectl get workspaces -A
NAMESPACE   NAME                         STATE
default     jupyterlab-scipy-workspace   Running
default     jupyterlab-workspace         Paused

Start (unpause) paused jupyterlab-workspace workspace

➜ backend/ git:(feat/workspace-start-api) $ curl -X 'POST' \
  'http://localhost:4000/api/v1/workspaces/default/jupyterlab-workspace/actions/pause' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "data": {
    "paused": false
  }
}'

{
	"data": {
		"paused": false
	}
}

Verify jupyterlab-workspace now running (unpaused)

➜ backend/ git:(feat/workspace-start-api) $ kubectl get workspaces -A
NAMESPACE   NAME                         STATE
default     jupyterlab-scipy-workspace   Running
default     jupyterlab-workspace         Running

Attempt to start (unpause) running jupyterlab-workspace workspace

➜ backend/ git:(feat/workspace-start-api) $ curl -X 'POST' \
  'http://localhost:4000/api/v1/workspaces/default/jupyterlab-workspace/actions/pause' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "data": {
    "paused": false
  }
}'
{
	"error": {
		"code": "422",
		"message": "workspace is in an invalid state for this operation",
		"cause": {}
	}
}

Attempt to start (unpause) running jupyterlab-workspace workspace exercising "empty" Envelope edge case

➜ backend/ git:(feat/workspace-start-api) $ curl -X 'POST' \
  'http://localhost:4000/api/v1/workspaces/default/jupyterlab-workspace/actions/pause' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "data": {}
}'               
{
	"error": {
		"code": "422",
		"message": "workspace is in an invalid state for this operation",
		"cause": {}
	}
}

Verify state

➜ backend/ git:(feat/workspace-start-api) $ kubectl get workspaces -A
NAMESPACE   NAME                         STATE
default     jupyterlab-scipy-workspace   Running
default     jupyterlab-workspace         Running

[thesuperzapper]

@andyatmiami thanks, it took a while but we got there.

/approve

[google-oss-prow]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: thesuperzapper

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [thesuperzapper]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[thesuperzapper]

/lgtm