Documentation
¶
Overview ¶
Package notebooksupervisor manages per-workspace Jupyter Server Deployments + Services in Kubernetes. EnsureRunning spawns on first call, returns a cached handle on subsequent calls. Touch refreshes lastActive so idle workspaces get reaped after Config.IdleTTL.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildDeployment ¶
func BuildDeployment(k Key, c Config) (*appsv1.Deployment, error)
BuildDeployment produces a fresh Deployment spec for a notebook pod. Pure function — no I/O. Returns an error if the Key has an invalid workspace id.
func BuildService ¶
BuildService returns a ClusterIP Service that fronts the Deployment.
func ServiceURL ¶
ServiceURL returns the cluster-internal HTTP url for the Service.
Types ¶
type Config ¶
type Config struct {
Image string // e.g. "ghcr.io/agentserver/agentserver-notebook:dev"
ImagePullPolicy string // e.g. "Always" or "IfNotPresent"
CPURequest string // k8s quantity, e.g. "500m"
CPULimit string // e.g. "2"
MemoryRequest string // e.g. "1Gi"
MemoryLimit string // e.g. "4Gi"
EphemeralStorage string // e.g. "5Gi"
WorkspacePVCName string // mounted at /workspace inside the pod
// ExtraEnvVars are injected into the notebook container env. Values
// may contain `{workspace_id}` which BuildDeployment substitutes with
// the Key.WorkspaceID. Keys are passed through as-is.
ExtraEnvVars map[string]string
ReadyTimeout time.Duration // how long EnsureRunning blocks waiting for ReadyReplicas >= 1
IdleTTL time.Duration // idle threshold for reaper
ReapInterval time.Duration // how often the reaper loop ticks
}
Config tunes Supervisor lifetime + per-Deployment template.
func (Config) WithDefaults ¶
WithDefaults returns a copy of c with zero-valued fields replaced by safe defaults. Always returns a Config; never errors.
type Handle ¶
type Handle struct {
ServiceURL string
}
Handle is what callers get back from EnsureRunning. ServiceURL is the cluster-internal HTTP url to reach the Jupyter Server.
type Key ¶
Key identifies one workspace's notebook Deployment. Namespace is the k8s namespace the Deployment + Service live in (typically per-workspace).
func (Key) DeploymentName ¶
DeploymentName returns the Deployment + Service name (they share one). Assumes the workspace id is already k8s-safe; use SafeDeploymentName when you need explicit validation.
func (Key) SafeDeploymentName ¶
SafeDeploymentName validates the workspaceID against k8s DNS-1123 rules AND the 63-char Deployment name limit. Returns the prefixed name on success.
type Supervisor ¶
type Supervisor struct {
// contains filtered or unexported fields
}
Supervisor owns the per-workspace lifecycle map. Concurrent EnsureRunning calls for the same Key are serialised; a single in-memory map is the source of truth for lastActive.
func New ¶
func New(k8s kubernetes.Interface, cfg Config, logger *slog.Logger) *Supervisor
New constructs a Supervisor. logger may be nil (defaults to slog.Default).
func (*Supervisor) EnsureRunning ¶
EnsureRunning creates the Deployment + Service if absent, then blocks up to Config.ReadyTimeout waiting for ReadyReplicas >= 1. Returns a cached Handle on subsequent calls.
func (*Supervisor) LastActive ¶
func (s *Supervisor) LastActive(k Key) time.Time
LastActive returns the last activity timestamp for k, or zero time if the workspace isn't tracked.
func (*Supervisor) StartReaper ¶
func (s *Supervisor) StartReaper(ctx context.Context)
StartReaper runs the idle reap loop. Returns when ctx is cancelled. Each tick: snapshot idle Keys (lastActive + IdleTTL < now), call Stop on each. Errors are logged, never propagated.
func (*Supervisor) Stop ¶
func (s *Supervisor) Stop(ctx context.Context, k Key) error
Stop deletes the Deployment + Service. 404 is treated as success.
func (*Supervisor) Touch ¶
func (s *Supervisor) Touch(k Key)
Touch updates lastActive for k. No-op if the workspace isn't tracked.
Source Files