Workspace#

Workspace#

Workspace is the Schema for the workspaces API

Field

Value or Description

apiVersion string

workspace.jupyter.org/v1alpha1

kind string

Workspace

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

spec WorkspaceSpec

spec defines the desired state of Workspace

status WorkspaceStatus

status defines the observed state of Workspace

AccessResourceStatus#

AccessResourceStatus defines the status of a resource created from a template

Appears in:

Field

Description

Default

Validation

kind string

Kind of the Kubernetes resource

apiVersion string

APIVersion of the Kubernetes resource

name string

Name of the resource

namespace string

Namespace of the resource

AccessStrategyRef#

AccessStrategyRef defines a reference to a WorkspaceAccessStrategy

Appears in:

Field

Description

Default

Validation

name string

Name of the WorkspaceAccessStrategy

namespace string

Namespace where the WorkspaceAccessStrategy is located

Optional: {}

ContainerConfig#

ContainerConfig defines container command and args configuration

Appears in:

Field

Description

Default

Validation

command string array

Command specifies the container command

args string array

Args specifies the container arguments

IdleDetectionSpec#

IdleDetectionSpec defines idle detection methods

Appears in:

Field

Description

Default

Validation

httpGet IdleHTTPGetAction

HTTPGet specifies the HTTP request to perform for idle detection

Optional: {}

IdleHTTPGetAction#

IdleHTTPGetAction extends corev1.HTTPGetAction with transport and response parsing options.

Appears in:

Field

Description

Default

Validation

path string

Path to access on the HTTP server.

Optional: {}

port IntOrString

Name or number of the port to access on the container.
Number must be in the range 1 to 65535.
Name must be an IANA_SVC_NAME.

host string

Host name to connect to, defaults to the pod IP. You probably want to set
”Host” in httpHeaders instead.

Optional: {}

scheme URIScheme

Scheme to use for connecting to the host.
Defaults to HTTP.

Optional: {}

httpHeaders HTTPHeader array

Custom headers to set in the request. HTTP allows repeated headers.

Optional: {}

transport string

Transport selects how the operator reaches the endpoint.
”podExec” executes curl inside the workspace container (legacy).
”network” makes a direct HTTP call from the operator to the workspace Service’s ClusterIP.

podExec

Enum: [podExec network]
Optional: {}

lastActivityTimestamp IdleLastActivityTimestampSpec

LastActivityTimestamp describes how to extract and parse the last-activity
timestamp from the JSON response body.

Optional: {}

IdleLastActivityTimestampSpec#

IdleLastActivityTimestampSpec configures extraction and parsing of a last-activity timestamp value from an idle-detection HTTP response body.

Appears in:

Field

Description

Default

Validation

responseBodyPath string

ResponseBodyPath is a dot-separated path to the timestamp value in the
JSON response body (e.g. “last_activity” or “status.lastActive”).
Default: “lastActiveTimestamp”

Optional: {}

format string

Format specifies how to parse the extracted value.
”RFC3339” expects an RFC 3339 timestamp string.
”unix” expects epoch seconds (numeric or string).

RFC3339

Enum: [RFC3339 unix]
Optional: {}

IdleShutdownSpec#

IdleShutdownSpec defines idle shutdown configuration

Appears in:

Field

Description

Default

Validation

enabled boolean

Enabled indicates if idle shutdown is enabled

idleTimeoutInMinutes integer

IdleTimeoutInMinutes specifies idle timeout in minutes

Minimum: 1

detection IdleDetectionSpec

Detection specifies how to detect idle state

StorageSpec#

StorageSpec defines the storage configuration for Workspace

Appears in:

Field

Description

Default

Validation

storageClassName string

StorageClassName specifies the storage class to use for persistent storage

size Quantity

Size specifies the size of the persistent volume
Supports standard Kubernetes resource quantities (e.g., “10Gi”, “500Mi”, “1Ti”)
Integer values without units are interpreted as bytes

mountPath string

MountPath specifies where to mount the persistent volume in the container
Default is /home/jovyan (jovyan is the standard user in Jupyter images)

TemplateRef#

TemplateRef defines a reference to a WorkspaceTemplate

Appears in:

Field

Description

Default

Validation

name string

Name of the WorkspaceTemplate

namespace string

Namespace where the WorkspaceTemplate is located
When omitted, defaults to the workspace’s namespace

Optional: {}

VolumeSpec#

VolumeSpec defines a volume to mount from an existing PVC

Appears in:

Field

Description

Default

Validation

name string

Name is a unique identifier for this volume within the pod (maps to pod.spec.volumes[].name)

persistentVolumeClaimName string

PersistentVolumeClaimName is the name of the existing PVC to mount

mountPath string

MountPath is the path where the volume should be mounted (Unix-style path, e.g. /data)

WorkspaceSpec#

WorkspaceSpec defines the desired state of Workspace

Appears in:

Field

Description

Default

Validation

displayName string

Display Name of the server

image string

Image specifies the container image to use

desiredStatus string

DesiredStatus specifies the desired operational status

Enum: [Running Stopped]

ownershipType string

OwnershipType specifies who can modify the workspace.
Public means anyone with RBAC permissions can update/delete the workspace.
OwnerOnly means only the creator can update/delete the workspace.

Enum: [Public OwnerOnly]
Optional: {}

accessType string

AccessType specifies who can connect to the workspace.
Public means anyone with RBAC permissions can connect to workspace.
OwnerOnly means only the creator can connect to the workspace.

Enum: [Public OwnerOnly]
Optional: {}

resources ResourceRequirements

Resources specifies the resource requirements

storage StorageSpec

Storage specifies the storage configuration

volumes VolumeSpec array

Volumes specifies additional volumes to mount from existing PersistantVolumeClaims

containerConfig ContainerConfig

ContainerConfig specifies container command and args configuration

env EnvVar array

Env specifies environment variables for the workspace container
When a template is used, template’s BaseEnv vars are merged (workspace vars take precedence by name)

Optional: {}

nodeSelector object (keys:string, values:string)

NodeSelector specifies node selection constraints for the workspace pod

affinity Affinity

Affinity specifies node affinity and anti-affinity rules for the workspace pod

tolerations Toleration array

Tolerations specifies tolerations for the workspace pod to schedule on nodes with matching taints

lifecycle Lifecycle

Lifecycle specifies actions that the management system should take
in response to container lifecycle events (for instance, lifecycle hooks)

readinessProbe Probe

ReadinessProbe specifies the readiness probe for the main workspace container.

Optional: {}

accessStrategy AccessStrategyRef

AccessStrategy specifies the WorkspaceAccessStrategy to use

Optional: {}

templateRef TemplateRef

TemplateRef references a WorkspaceTemplate to use as base configuration
When set, template provides defaults and workspace spec fields act as overrides

Optional: {}

idleShutdown IdleShutdownSpec

IdleShutdown specifies idle shutdown configuration

Optional: {}

appType string

AppType specifies the application type for this workspace

Optional: {}

serviceAccountName string

ServiceAccountName specifies the name of the ServiceAccount to use for the workspace pod

Optional: {}

podSecurityContext PodSecurityContext

PodSecurityContext specifies pod-level security context
Overrides template defaults when specified

Optional: {}

containerSecurityContext SecurityContext

ContainerSecurityContext specifies container-level security context for the main workspace container
Takes precedence over PodSecurityContext for the main container
Overrides template defaults when specified

Optional: {}

initContainers Container array

InitContainers specifies init containers to run before the workspace container starts
When a template is used, template’s DefaultInitContainers are applied if workspace has none
Requires AllowCustomInitContainers=true on the template to specify custom init containers

MaxItems: 10
Optional: {}

WorkspaceStatus#

WorkspaceStatus defines the observed state of Workspace.

Appears in:

Field

Description

Default

Validation

deploymentName string

DeploymentName is the name of the deployment managing the Workspace pods

Optional: {}

serviceName string

ServiceName is the name of the service exposing the Workspace

Optional: {}

accessURL string

AccessURL is the URL at which the workspace can be accessed

Optional: {}

applicationBasePath string

ApplicationBasePath is the resolved routing prefix for the workspace application.
Set during access-resources reconciliation; used by idle detection to construct
the full endpoint path.

Optional: {}

accessResourceSelector string

AccessResourceSelector is a label selector that can be used to find all resources
created from the workspace’s AccessStrategy templates

Optional: {}

accessResources AccessResourceStatus array

AccessResources provides status details of individual resources created from
the workspace’s AccessStrategy templates

Optional: {}

observedAccessStrategyVersion string

ObservedAccessStrategyVersion is a token capturing the identity and
version of the AccessStrategy last evaluated during workspace
reconciliation. The controller resets probe state when this value changes.

Optional: {}

accessStartupProbeSucceeded boolean

AccessStartupProbeSucceeded indicates whether the access startup probe
has passed. Set to true when the probe succeeds; reset to false when
the workspace stops.

Optional: {}

accessStartupProbeFailures integer

AccessStartupProbeFailures tracks the number of consecutive failed access
startup probe attempts. Set by the controller during the probing phase;
cleared (nil) on success or when the workspace stops.

Optional: {}

earliestNextProbeTime Time

EarliestNextProbeTime is the earliest wall-clock time at which the next
access startup probe may fire. Set by the controller after each probe
attempt to enforce spacing; survives watch-triggered re-reconciliations.

Optional: {}

conditions Condition array

Conditions represent the current state of the Workspace resource.
Each condition has a unique type and reflects the status of a specific aspect of the resource.
Standard condition types include:
- “Available”: the resource is fully functional and ready to use
- “Progressing”: the resource is being created, updated, or stopped
- “Degraded”: the resource failed to reach or maintain its desired state
- “Stopped”: the workspace has been stopped and resources scaled down
The status of each condition is one of True, False, or Unknown.

Optional: {}