Kubernetes Workspaces

Getting started

Deploy the operator once, then request workspace environments from your main Paseo daemon.

Requirements

Build your images

Clone the repository. Replace your-registry with a registry your cluster can pull from.

git clone https://github.com/lerenn/paseo-kubernetes-workspaces.git
cd paseo-kubernetes-workspaces

docker build -t your-registry/paseo-workspaces-operator:0.1.0 .
docker build -t your-registry/paseo-workspace:0.16.2 images/workspace
docker push your-registry/paseo-workspaces-operator:0.1.0
docker push your-registry/paseo-workspace:0.16.2

The base workspace image contains Paseo and basic development utilities. Install your agent provider executables in a derived image and inject their credentials through a Kubernetes Secret.

Deploy the operator

Set the operator image in config/operator.yaml to the image you just pushed, then apply the manifests.

kubectl apply -f config/crd.yaml
kubectl apply -f config/operator.yaml
# Optional: cap aggregate workspace resources.
kubectl apply -f config/quota.yaml

Configure the main daemon

Set these variables in the environment of the main daemon, then restart it. Shell exports in a separate terminal do not change an already running daemon.

PASEO_WORKSPACE_IMAGE=your-registry/paseo-workspace:0.16.2
PASEO_WORKSPACE_NAMESPACE=paseo-workspaces
PASEO_WORKSPACE_CLUSTER_ID=my-cluster
# Optional: reverse registration for messages back to the main daemon.
PASEO_MAIN_CONNECTION=main-daemon.paseo-workspaces.svc:6767
# Optional: inject credentials into workspace pods.
PASEO_WORKSPACE_SECRET=workspace-credentials

Apply config/plugin-rbac.yaml and bind its Role to the main daemon’s ServiceAccount. Alternatively, grant equivalent access through its kubeconfig. The main daemon needs permission to get, list, create, patch and delete PaseoWorkspace resources.

Enable plugins in Paseo settings and install the companion from the cloned checkout:

cd plugin
npm ci
npm run typecheck
paseo plugin install "$PWD"

Start your first workspace

  1. Open a new agent session so it receives the companion’s tools.
  2. Call kubernetes_workspace_create({ "name": "demo" }).
  3. Poll kubernetes_workspace_list({}) until the environment’s hostStatus is online.
  4. Use the returned serverId with Paseo’s cross-host tools. Create a Paseo workspace at /workspace on that daemon, then start agents there.
  5. Export results, then call kubernetes_workspace_release({ "name": "demo" }).
Release deletes the pod and PVC. Use a StorageClass with reclaim policy Delete if physical storage should also be removed.

Check an environment

kubectl -n paseo-workspaces get pw
kubectl -n paseo-workspaces describe pod pw-demo
kubectl -n paseo-workspaces logs pw-demo

A Ready pod is not necessarily a connected host. Check the companion’s hostStatus and error fields for registration problems. Configure daemon authentication and network policy for your cluster; an optional policy is provided in config/network-policy.yaml.

See the reference for all configuration options.