ADR-001: Use Datalab as the Public Contract
Written: 02.12.2025. Revised: 03.11.2026.
Status
Accepted
Implementation
Implemented.
Users create a Datalab. Provider Datalab turns it into a working data
workspace and reports session information on the same resource.
Educates is the first implementation of runtime sessions. It provides the browser editor and terminal. Its resources are created and managed internally.
Context
A data workspace needs many things: an editor, a terminal, persistent files, credentials, networking, and optional services. Exposing every resource needed to build that workspace would give users a complicated and fragile API.
We need one stable contract that describes what a user wants, while allowing the implementation behind it to change.
Decision
Make Datalab the only public workspace resource
Users and GitOps tools work with the namespaced Datalab resource. It describes
the desired workspace, including its named sessions and optional capabilities.
The Datalab name, namespace, and UID form its stable identity. Generated Pod, Secret, and runtime-resource names are not part of the public contract.
Keep the runtime implementation internal
The internal runtime provides the editor, terminal, workspace Pod, sessions, and optional applications. Crossplane translates a Datalab into the runtime and Kubernetes resources required to run it.
This translation is an implementation detail:
User or GitOps tool
-> Datalab
-> Provider Datalab reconciliation
-> internal runtime resources
-> working Datalab session
Clients never create, update, discover, or depend on runtime resources directly. Crossplane owns those generated resources. This keeps one source of truth and lets the runtime implementation evolve without changing how users manage a Datalab.
The same rule applies if the internal runtime changes later. Runtime resources remain projections of the Datalab and do not become a second public workspace API.
Keep user choices separate from operator policy
The Datalab spec contains choices that a user is allowed to make. The
operator-owned EnvironmentConfig contains platform settings such as ingress,
Keycloak realm, storage classes, security defaults, and extension packages.
Crossplane combines both sets of input. Users therefore get a small API, while operators keep control of security and infrastructure policy.
Manage sessions through the Datalab
Each session has a unique name and a desired state such as started or
stopped. Provider Datalab creates the internal runtime for started sessions
and reports the observed phase, message, and browser URL in
Datalab.status.sessions. A stopped session keeps its workspace PVC.
Clients read the Datalab status. They do not look up the internal runtime. Diagnostic phase and message text is not a stable machine-readable lifecycle API.
Keep credentials out of the API
Credentials are read from referenced Kubernetes Secrets and copied only where the runtime needs them. Secret values never belong in the Datalab spec, status, logs, or normal client output.
Credentials and security settings currently apply to the whole Datalab. Use separate Datalabs when workloads need different membership or trust boundaries.
Add tools without changing the contract
Operators can add runtime tools through extension packages. This keeps the Datalab API stable and avoids putting every tool in one large base image.
Why This Design
| Design choice | Reason |
|---|---|
| One Datalab API | Users have one clear object to create, review, and manage. |
| Runtime stays internal | Clients are not coupled to runtime-specific resources or names. |
| Crossplane owns generated resources | Reconciliation has one owner and does not compete with user changes. |
| User input and operator policy are separate | Self-service does not bypass platform security or infrastructure rules. |
| Status is copied to the Datalab | Clients do not need broad access to internal resources. |
| Credentials stay in Secrets | The public API does not become a credential-delivery channel. |
Consequences
- Provider Datalab is self-contained: clients need only the Datalab API.
- Changing the internal runtime does not require a second public workspace model.
- Crossplane remains responsible for generated-resource ownership and cleanup.
- Operators must validate user-selectable Secret references and other policy-sensitive options.
- Render tests check generated resources; live tests must also check session transitions and access to services.