README
¶
Kube Workspaces API
REST API service for managing Kubernetes workspaces, built with the Goa framework.
Overview
The API provides:
- Workspaces - CRUD, start/stop/reset/reboot, logs, events, pod details
- Volumes - PVC management (create, list, delete)
- Images - List available workspace images with proxy configuration
- SshKeys - CRUD of user SSH public keys (used to seed VM guest access)
- Namespaces - List available Kubernetes namespaces (supports
_allfor cross-namespace listing) - Proxy - Reverse proxy to workspace web UIs with WebSocket support
- Console/exec bridges - WebSocket bridges to workspace terminals, VM serial consoles, VM noVNC displays, and web SSH sessions (single-session with take-over)
- Admin - Raw CRD browsing endpoints
- Health - Health check endpoint
- OpenAPI - Auto-generated OpenAPI 3.0 spec (JSON and YAML)
VM access
For spec.type: vm workspaces the API bridges WebSockets to KubeVirt
subresources (and guest sshd), using a session registry so each bridge is
single-session with an idle TTL and take-over consent:
GET /v1/workspaces/{name}/console— serial console (.../virtualmachineinstances/{name}/console)GET /v1/workspaces/{name}/vnc— noVNC display (.../virtualmachineinstances/{name}/vnc)GET /v1/workspaces/{name}/ssh— web SSH into the guest (dials the workspace Service; the browser supplies the private key transiently)GET/POST .../console/status,.../console/takeover,.../ssh/status,.../ssh/takeover— session status + take-overPOST /v1/workspaces/{name}/reboot— delete the VMI (persistent root disk preserved)
Design
The API is defined using Goa DSL in design/design.go. Running goa gen generates:
- HTTP server and client code
- OpenAPI 2.0 and 3.0 specifications
- Type definitions and encoders/decoders
Additional endpoints (logs, events, pod, proxy, admin) are implemented directly in cmd/kube_workspaces/http.go, along with the WebSocket bridges (exec/console/vnc/ssh) and their session registry.
Development
# Regenerate code from design
go run goa.design/goa/v3/cmd/goa gen github.com/kube-workspaces/api/design
# Build
go build -o bin/kube-workspaces-api ./cmd/kube_workspaces/
# Run locally (uses current kubeconfig)
go run ./cmd/kube_workspaces/ --http-port=8090
Docker
docker build -t kube-workspaces-api:latest -f Dockerfile .
Requires Go 1.26+ (for k8s.io/client-go@v0.36.2 compatibility).
Workspace Proxy
The API includes a built-in reverse proxy at /proxy/{namespace}/{name}/{path...}:
- Full WebSocket passthrough
- Location header rewriting for redirects
- Referer-based catch for escaped absolute-path requests
- No-op ServiceWorker at
/sw.js - Per-image proxy configuration (see
internal/proxy/proxy.go)
Image Defaults
When creating workspaces, the API auto-injects default settings for known images:
codercom/code-server:latest- Adds--bind-addr 0.0.0.0:8080 --auth noneargs
Key Files
| File | Description |
|---|---|
design/design.go |
Goa API design DSL |
cmd/kube_workspaces/http.go |
HTTP server setup, proxy, admin, WebSocket bridge routes |
cmd/kube_workspaces/main.go |
Entry point, client initialization |
internal/k8s/client.go |
CoreClient for pods, logs, events |
internal/k8s/workspace.go |
Workspace CR dynamic client |
internal/k8s/sshkey.go |
SshKey CR client |
internal/k8s/image.go |
Image CR client (workspace types, defaults) |
internal/exec/session.go |
Session registry (single-session, TTL, take-over) |
internal/exec/vmconsole.go |
VM serial console WebSocket bridge |
internal/exec/vmvnc.go |
VM noVNC display WebSocket bridge |
internal/exec/ssh.go |
Web SSH console WebSocket bridge |
internal/proxy/proxy.go |
Reverse proxy handler |
workspaces.go |
Workspace service implementation |
volumes.go |
Volume service implementation |
images.go |
Images service (static registry) |
sshkeys.go |
SshKeys service |
Configuration
The API uses the current kubeconfig or in-cluster service account for Kubernetes access.
| Env Var | Description | Default |
|---|---|---|
KUBECONFIG |
Path to kubeconfig file | ~/.kube/config |
HTTP_HOST |
Listen address | localhost:8080 |
Related Repositories
| Repository | Description |
|---|---|
| kube-workspaces/controller | Kubernetes controller (CRD reconciliation) |
| kube-workspaces/proxy | Workspace reverse proxy |
| kube-workspaces/frontend | Next.js web UI |
| kube-workspaces/deploy | Deployment manifests and documentation |
License
Apache License 2.0
Documentation
¶
Overview ¶
Package kubeworkspaces implements the kube-workspaces REST API service layer. It provides HTTP endpoints for managing workspaces, volumes, images, and namespaces within a Kubernetes cluster. The API is designed using the Goa framework and supports both authenticated and unauthenticated operation modes.
Index ¶
- func NewHealth() health.Service
- func NewImages(imageClient *k8s.ImageClient) images.Service
- func NewNamespaces(authProvider *auth.ConfigProvider) namespaces.Service
- func NewSSHKeys(authProvider *auth.ConfigProvider) sshkeys.Service
- func NewVolumes(authProvider *auth.ConfigProvider) volumes.Service
- func NewWorkspaces(client *k8s.WorkspaceClient, imageClient *k8s.ImageClient, ...) workspaces.Service
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewImages ¶
func NewImages(imageClient *k8s.ImageClient) images.Service
NewImages returns the images service implementation.
func NewNamespaces ¶
func NewNamespaces(authProvider *auth.ConfigProvider) namespaces.Service
NewNamespaces returns the namespaces service implementation.
func NewSSHKeys ¶ added in v0.4.0
func NewSSHKeys(authProvider *auth.ConfigProvider) sshkeys.Service
NewSSHKeys returns the sshkeys service implementation.
func NewVolumes ¶
func NewVolumes(authProvider *auth.ConfigProvider) volumes.Service
NewVolumes returns the volumes service implementation.
func NewWorkspaces ¶
func NewWorkspaces(client *k8s.WorkspaceClient, imageClient *k8s.ImageClient, coreClient *k8s.CoreClient, authProvider *auth.ConfigProvider, podDefaultClient *k8s.PodDefaultClient) workspaces.Service
NewWorkspaces returns the workspaces service implementation.
Types ¶
This section is empty.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
kube_workspaces
command
|
|
|
kube_workspaces-cli
command
|
|
|
gen
|
|
|
internal
|
|
|
auth
Package auth provides authentication and authorization middleware for the kube-workspaces API.
|
Package auth provides authentication and authorization middleware for the kube-workspaces API. |
|
exec
Package exec provides WebSocket-based remote command execution in workspace pods.
|
Package exec provides WebSocket-based remote command execution in workspace pods. |
|
k8s
Package k8s provides Kubernetes client wrappers for the kube-workspaces API server.
|
Package k8s provides Kubernetes client wrappers for the kube-workspaces API server. |
|
proxy
Package proxy implements HTTP reverse proxying to workspace pods.
|
Package proxy implements HTTP reverse proxying to workspace pods. |