Install Provider Datalab
Run these commands from a repository checkout with access to the target cluster. For a shared installation, manage manifests and Secrets through your platform's GitOps and Secret tools.
Prerequisites
The cluster needs Crossplane, the Educates session runtime, an ingress controller, Keycloak, and an S3-compatible object store. The CNI must enforce Kubernetes NetworkPolicy. Use Crossplane from the supported range in the package's metadata.
Install the session runtime with its CRDs and controller RBAC before creating Datalabs. Follow the runtime installation guide. The runtime ingress class, domain, and TLS Secret must match the settings below.
Install the operators for the managed stores you plan to offer. Provider Datalab integration tests use these versions:
| Datalab field | Operator | Test version | Required resource API |
|---|---|---|---|
spec.databases |
Crunchy PostgreSQL Operator (PGO) | 6.0.2 |
PostgresCluster in postgres-operator.crunchydata.com/v1 |
spec.documentStores |
MongoDB Kubernetes Operator | 1.14.0 |
MongoDBCommunity in mongodbcommunity.mongodb.com/v1 |
spec.cacheStores |
Opstree Redis Operator | 0.27.0 (Helm chart 0.27.0) |
Redis in redis.redis.opstreelabs.in/v1beta2 |
These are fixed test pins. Other versions need validation before use.
Install each operator's CRDs before its controller. The
integration harness shows the tested
installation settings. Backup volumes need a StorageClass that supports
ReadWriteOnce; see backup settings.
Gateway exposure also needs a Gateway API controller. Data uses HTTPRoute
with HTTP and TLS-terminating HTTPS listeners. External PostgreSQL access uses
TLSRoute in gateway.networking.k8s.io/v1 and direct TLS with SNI.
For spec.vclusters, apply the supplied provider RBAC and configure an HTTPS
issuer, allowed StorageClasses, and an HTTPS Gateway listener. The host needs
ValidatingAdmissionPolicy and BackendTLSPolicy support. See
virtual cluster setup.
1. Choose the claim namespace
This guide uses workspace for Datalab resources and their namespaced
ProviderConfigs:
kubectl create namespace workspace
kubectl create namespace datalab
Input storage Secrets live in datalab, as set by storage.secretNamespace
in the environment examples. Each Datalab also has a separate namespace for
its runtime and shared services.
2. Install provider dependencies
Apply the files in
dependencies/
in this order:
| File | Purpose |
|---|---|
00-mrap.yaml |
Activate the managed resource kinds used by the composition. |
01-deploymentRuntimeConfigs.yaml |
Set provider and function Pod security. |
02-providers.yaml |
Install the Kubernetes, Helm, and Keycloak providers. |
03-providerConfigs.yaml |
Configure those providers in the claim namespace. |
functions.yaml |
Install the composition functions. |
rbac.yaml |
Grant provider-kubernetes access to the resources it manages. |
Apply 03-providerConfigs.yaml with kubectl apply -n workspace -f ....
Create its referenced Keycloak credential Secret in that namespace through
your platform's Secret tools. The Keycloak account needs permission to manage
clients, client scopes, service-account roles, groups, memberships, role
mappings, and client policies in the target realm.
Use Keycloak 26.2 or later. Configure identity scopes, client policies, and
browser sign-in as described in Authentication.
The realm must permit the built-in offline_access scope and user role for
CLI device login.
Use the package pins in the dependency manifests. Wait for the provider and function revisions to report healthy before installing the configuration package. The provider-kubernetes RBAC includes access to Pods for readiness checks and PVCs for session storage.
3. Install the configuration package
Save this resource as configuration.yaml. Replace 0.12.0 with the
release tag you want to install.
apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
name: datalab
spec:
package: ghcr.io/versioneer-tech/provider-datalab:0.12.0
skipDependencyResolution: true
Apply it and check the package conditions:
kubectl apply -f configuration.yaml
kubectl get configurations.pkg.crossplane.io
kubectl get configurationrevisions.pkg.crossplane.io
The package installs the Datalab resource definition and composition. Its providers and functions are managed separately by the platform.
For a source installation, apply xrd.yaml before composition.yaml so
Kubernetes retains the OAuth2 discovery
fields.
The manifest build guide explains how to change the pipeline response TTL before building a package.
4. Set the shared environment
Create an EnvironmentConfig named datalab with values for your cluster.
This example uses NGINX Ingress for Data and the registry:
apiVersion: apiextensions.crossplane.io/v1beta1
kind: EnvironmentConfig
metadata:
name: datalab
data:
iam:
realm: acme
issuerURL: https://identity.acme.com/realms/acme
internalURL: http://keycloak.keycloak:8080/realms/acme
ingress:
enabled: true
class: nginx
domain: lab.acme.com
secret: wildcard-tls
annotations:
nginx.ingress.kubernetes.io/proxy-body-size: "0"
nginx.ingress.kubernetes.io/proxy-request-buffering: "off"
nginx.ingress.kubernetes.io/proxy-buffering: "off"
nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
oauth2Proxy:
upstreamTimeout: 3600s
storage:
endpoint: https://s3.acme.com
provider: Other
region: us-east-1
forcePathStyle: "true"
secretNamespace: datalab
type: s3
storageClasses:
allowed:
- sbs-default
- sbs-default-retain
network:
externalEgressCIDRs:
- 0.0.0.0/0
- ::/0
serviceCIDR: "10.43.0.0/16"
podCIDRs:
- 10.42.0.0/16
blacklistIPs:
- 169.254.169.254/32
- fd00:ec2::254/128
- 169.254.42.42/32
- fd00:42::42/128
excludePolicies: []
defaults:
vcluster:
enabled: true
registry:
enabled: true
data:
enabled: true
readOnlyMount: false
overallQuota:
storage: 100Gi
security:
externalEgress: true
Replace the example storage classes, network ranges, and DNS names before applying it. Configure authentication before users start sessions.
Service addresses
Enable either ingress.enabled or httpRoute.enabled for public service
access. Using both stops reconciliation. On each Datalab's
hostname, /v2/ serves the registry and other paths serve Data. Virtual API
routes use their instance path, such as /.vc0. With httpRoute.enableS3,
requests signed by S3 clients use the read-only S3 service on the same host.
With neither exposure method enabled, Data is available through a session's authenticated ingress. The registry is available only inside the cluster.
For Gateway API exposure, replace the example's ingress.enabled: true with
false and add:
data:
httpRoute:
enabled: true
parentName: default
parentNamespace: contour
sectionName: workspaces-https
httpSectionName: workspaces-http
timeouts:
request: 3600s
backendRequest: 3600s
The Gateway needs HTTP and TLS-terminating HTTPS listeners and must accept routes from runtime namespaces. It manages the service certificate. Keep the ingress class and TLS Secret set for the session runtime. For the optional read-only S3 endpoint, see S3 client access.
Large file transfers
ingress.annotations applies to both Data and registry Ingress objects. The
example permits any upload size, streams requests and responses, and allows
one hour between read or write operations. These annotations require the
community ingress-nginx controller. Use your controller's settings if you
use another implementation. The composition does not add controller-specific
annotations.
httpRoute.timeouts applies to Data, read-only S3, and registry backend rules.
Both timeouts default to one hour. If only request is set, backendRequest
uses that value. A nonzero backend timeout must not exceed a nonzero request
timeout. Use 0s for both to disable these deadlines.
Gateway API has no standard body-size or buffering setting. Configure the Gateway controller and any upstream load balancer to allow the required body size, stream transfers, and permit long connections. The controller must support HTTPRoute timeouts.
oauth2Proxy.upstreamTimeout defaults to one hour. It limits the wait for
packageR response headers after the request body is sent. It does not limit
the time to transfer the request or response body. Use 0s to disable this
wait limit.
packageR permits all browser origins (*) for public catalog access.
To restrict origins, configure the Gateway to replace or remove backend CORS
headers and handle preflight requests. Adding a header does not restrict the
wildcard. Cookie-based cross-origin access needs a separate policy.
EnvironmentConfig values and defaults
All paths below are relative to EnvironmentConfig.data. Defaults apply
when a setting is omitted; example values such as cluster CIDRs, endpoints,
and StorageClass names are not built-in defaults.
Select a specific EnvironmentConfig with the
datalabs.pkg.internal/environment annotation or label to use its settings
without per-Datalab overrides, as shown in the
datalab-custom example.
The annotation takes priority over the label; the default selection is datalab.
Runtime settings come from the EnvironmentConfig. The XRD retains unknown
fields, but extra fields in spec do not override these settings.
Runtime and service defaults
| Setting | Default | Use |
|---|---|---|
defaults.vcluster.enabled |
true |
Virtual Kubernetes API for each started session. |
defaults.registry.enabled |
true |
Shared OCI registry backed by the Datalab S3 bucket. |
defaults.data.enabled |
true |
Shared packageR service and its configured endpoint. |
defaults.data.readOnlyMount |
false |
Read-only application permissions when enabled; storage IAM still applies. |
defaults.quota.memory |
2Gi |
Session memory request. |
defaults.quota.storage |
1Gi |
Workspace PVC size. |
defaults.quota.budget |
medium |
Session namespace budget. |
defaults.overallQuota.storage |
100Gi |
Aggregate PVC request limit in the environment namespace. |
defaults.security.policy |
baseline |
Pod security level: restricted, baseline, or privileged. |
defaults.security.kubernetesAccess |
true |
Session Kubernetes service account token. |
defaults.security.kubernetesRole |
edit |
Session role: view, edit, or admin. |
defaults.security.externalEgress |
true |
Broad egress to the configured external CIDRs. |
defaults.persistence.storageClassName |
First allowed class, or cluster default | Workspace StorageClass; a value outside the allowlist falls back to its first entry. |
defaults.files |
[] |
Workshop file bundles. |
packages |
[] |
Session extension packages. |
Session PVC names and namespaces are listed in status.sessions[].pvcRef.
status.sessions[].pvcSize reports the requested size.
File bundles and extension packages are passed to the session runtime unchanged. Set Data enablement before creating Datalabs because the runtime saves each environment's Workshop specification. See file sources for a file bundle example.
Service images
Set these image references under data.images in the EnvironmentConfig.
Use a full image reference with a tag or digest. Omitted settings use the
defaults below.
| Setting | Default image tag | Use |
|---|---|---|
images.packageR |
ghcr.io/versioneer-tech/package-r:vnext.1.1.0 |
Data server and its database init container. |
images.registry |
registry:3.1.2 |
CNCF Distribution registry. |
images.rclone |
rclone/rclone:1.71.0 |
Data S3 service. Session extension packages are configured separately. |
images.mongo |
quay.io/mongodb/mongodb-community-server:8.0.12-ubi8 |
MongoDB server. The default database version is 8.0.12. |
images.mongoBackup |
mongo:8.0.12 |
MongoDB backup tools. If omitted, its tag follows the database version. |
images.redis |
quay.io/opstree/redis:v7.0.15 |
Redis server and its init container. |
images.redisBackup |
redis:7.0.15 |
Redis backup tools. |
images.oauth2Proxy |
quay.io/oauth2-proxy/oauth2-proxy:v7.15.4 |
OAuth2 Proxy for Data and S3. |
The default OAuth2 Proxy image is also pinned by digest in the composition.
A MongoDB image tag that starts with major.minor.patch sets the database
version. For a digest without a version tag, set
documentStore.version to the image's MongoDB version. Use compatible server
and backup images.
Identity and endpoints
| Setting | Default | Use |
|---|---|---|
iam.realm |
default |
Keycloak realm; users must already exist here. |
iam.namespace |
keycloak |
Namespace selected by IAM egress rules. |
iam.issuerURL |
Not set | Public OIDC issuer for Data and virtual cluster access. |
iam.internalURL |
Not set | Token and signing-key URL; required for permanent Data exposure. |
iam.extraAudiences |
[] |
Additional audiences for tokens issued by the Datalab client. The Datalab audience is always included. |
ingress.enabled |
false |
Public Data and registry Ingress. |
ingress.class |
Empty | Ingress class for sessions and services. |
ingress.domain |
default for sessions |
Public host suffix for sessions and services. |
ingress.secret |
wildcard-tls for sessions |
TLS Secret; must be set for Data Ingress. |
ingress.annotations |
{} |
Annotations on service Ingress objects. |
httpRoute.enabled |
false |
Public Data and registry Gateway routes. |
httpRoute.enableS3 |
false |
Read-only S3 endpoint; requires httpRoute.enabled. |
httpRoute.parentName |
Not set | Gateway name; required when Gateway exposure is enabled. |
httpRoute.parentNamespace |
Not set | Gateway namespace; required when Gateway exposure is enabled. |
httpRoute.sectionName |
Not set | HTTPS listener; required when Gateway exposure is enabled. |
httpRoute.httpSectionName |
Not set | HTTP redirect listener; required when Data uses Gateway exposure. |
httpRoute.timeouts.request |
3600s |
Request deadline for Data, S3, and registry routes; 0s disables it. |
httpRoute.timeouts.backendRequest |
Request timeout | Deadline for each backend request, including its response body. |
oauth2Proxy.upstreamTimeout |
3600s |
Wait for packageR response headers after sending the request body. |
Storage and managed stores
| Setting | Default | Use |
|---|---|---|
storage.endpoint |
Empty | Endpoint reachable by runtime Pods; the input Secret's AWS_ENDPOINT_URL takes priority. |
storage.region |
Empty | Object-store region; the input Secret's AWS_REGION takes priority. |
storage.type |
Empty | rclone backend type, usually s3. |
storage.provider |
Empty for rclone; Other for the S3 proxy |
Object-store provider. |
storage.forcePathStyle |
true |
Path-style S3 requests. |
storage.secretNamespace |
Datalab namespace, or default |
Input storage Secret namespace. |
storageClasses.allowed |
[] |
Allowed workspace StorageClasses; an empty list permits any configured class. |
vcluster.resources.requests |
CPU 200m, memory 1Gi, ephemeral storage 1Gi |
Control-plane requests; supplied fields override these defaults. |
vcluster.resources.limits |
CPU 4, memory 4Gi, ephemeral storage 10Gi |
Control-plane limits; supplied fields override these defaults. |
vcluster.backingStore.database.embedded |
enabled: false, extraArgs: [] |
Native embedded database options, including enabled, dataSource, and extraArgs. |
vcluster.storage |
5Gi |
Default control-plane PVC size for named virtual clusters. |
vcluster.storageClasses.allowed |
Required when virtual clusters are declared | Host classes exposed to virtual workloads. |
vcluster.storageClasses.default |
First allowed class | Virtual workload default class. |
vcluster.storageClassName |
Virtual default class | Control-plane StorageClass; must be allowed. |
vcluster.issuerCA |
System trust | PEM CA for the HTTPS issuer. |
vcluster.discoveryURL |
Issuer discovery | Optional HTTPS discovery address. |
vcluster.backendTLS.apiVersion |
gateway.networking.k8s.io/v1 |
BackendTLSPolicy API served by the Gateway. |
ingress.certificateAuthority |
System trust | PEM Gateway CA embedded in profile kubeconfigs. |
database.storageClassName |
Cluster default | PostgreSQL data StorageClass. |
database.backupStorageClassName |
Cluster default | PostgreSQL backup StorageClass. |
database.tlsRoute.parentName |
Not set | PostgreSQL Gateway name. |
database.tlsRoute.parentNamespace |
Not set | PostgreSQL Gateway namespace. |
database.tlsRoute.sectionName |
Not set | PostgreSQL TLS listener. |
documentStore.version |
8.0.12, or version from images.mongo |
Database version; set it for an image without a version tag. |
documentStore.storageClassName |
Cluster default | MongoDB data StorageClass. |
documentStore.backupStorageClassName |
Cluster default | MongoDB backup StorageClass. |
cacheStore.storageClassName |
Cluster default | Redis data StorageClass. |
cacheStore.backupStorageClassName |
Cluster default | Redis backup StorageClass. |
PostgreSQL TLSRoutes are created only when all three
database.tlsRoute settings are present.
Network rules
| Setting | Default | Use |
|---|---|---|
network.externalEgressCIDRs |
[] |
External destination ranges; empty means no broad external allow rule. |
network.blacklistIPs |
[] |
CIDRs excluded from external egress. |
network.podCIDRs |
[] |
Host Pod ranges excluded from external egress. |
network.serviceCIDR |
Not set | Host Service range excluded from external egress. |
network.excludePolicies |
[] |
Generated policies to omit. |
network.internalEgress |
[] |
Explicit cross-namespace destinations. |
network.internalIngress |
[] |
Explicit cross-namespace sources. |
network.internalEgress[].namespace, network.internalIngress[].namespace |
Required for each entry | Peer namespace. |
network.internalEgress[].podSelector, network.internalIngress[].podSelector |
{} |
Peer Pod selector; omitted means all Pods in the peer namespace. |
network.internalEgress[].ports, network.internalIngress[].ports |
[] |
Ports; omitted means all ports. |
network.internalEgress[].ports[].port, network.internalIngress[].ports[].port |
Required for each port entry | Named or numbered port. |
network.internalEgress[].ports[].protocol, network.internalIngress[].ports[].protocol |
Kubernetes default (TCP) |
Port protocol. |
network.internalEgress[].ports[].endPort, network.internalIngress[].ports[].endPort |
Not set | End of a numeric port range. |
network.internalIngress[].targetPodSelector |
{} |
Runtime Pods selected by the ingress policy; omitted means all runtime Pods. |
Network access
Set network.podCIDRs and network.serviceCIDR to the host cluster's network
ranges. They are excluded from broad external egress so that it does not also
allow access to other Datalab namespaces. Use the cluster configuration for
the Service CIDR. A DNS Service IP alone does not identify the full range.
Pod CIDRs can be listed with:
kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{" "}{.spec.podCIDR}{" "}{.spec.podCIDRs}{"\n"}{end}'
Use 0.0.0.0/0 and ::/0 for all external IPv4 and IPv6 destinations,
or list narrower ranges in network.externalEgressCIDRs.
For a backend Pod in another namespace, add an internalEgress entry:
network:
internalEgress:
- namespace: minio
podSelector:
matchLabels:
v1.min.io/tenant: default
ports:
- protocol: TCP
port: 443
- protocol: TCP
port: 9000
Use network.internalIngress for inbound traffic. It uses the same fields as
internalEgress, with namespace and podSelector selecting the source:
network:
internalIngress:
- namespace: operations
podSelector:
matchLabels:
app.kubernetes.io/name: prometheus
targetPodSelector:
matchLabels:
app.kubernetes.io/name: package-r
ports:
- protocol: TCP
port: 8888
These rules apply to existing runtime namespaces too. See Network policies for how policies combine, Data access, and policy exclusions.
5. Supply storage credentials
Create the object-storage bucket and credentials through your platform's storage process or Provider Storage. Provider Datalab reads an existing input Secret with the same name as the Datalab.
The Secret must exist in storage.secretNamespace and contain
AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. The storage identity must
permit bucket listing with s3:ListAllMyBuckets. The endpoint must support
path-style S3 requests.
The registry needs a bucket with the same name as the Datalab and permission
to read, write, list, delete, and use multipart uploads. Distribution uses its
standard object layout without an extra prefix or PVC. Disabling the registry
retains its S3 objects. Set defaults.registry.enabled: false when the
platform does not provide this storage.
For a manual setup, create the Secret with your credential values:
kubectl -n datalab create secret generic s-joe \
--from-literal=AWS_ACCESS_KEY_ID='<KEY_ID>' \
--from-literal=AWS_SECRET_ACCESS_KEY='<SECRET>'
Use the platform's Secret tools for shared installations. Keep live credentials out of Git.
6. Create a Datalab
Save this resource as datalab.yaml. The user joe must already exist in
Keycloak. This uses the Joe example
with an explicit claim namespace.
apiVersion: pkg.internal/v1beta2
kind: Datalab
metadata:
name: s-joe
namespace: workspace
spec:
users:
- joe
Apply it and check its conditions:
kubectl apply -f datalab.yaml
kubectl get datalabs -n workspace
kubectl describe datalab s-joe -n workspace
See Use a Datalab for session state, managed services, workshop files, and sharing.
7. Check the installation
Check that provider and function revisions are healthy and that the
Datalab reports Synced=True and Ready=True:
kubectl get providers.pkg.crossplane.io
kubectl get providerrevisions.pkg.crossplane.io
kubectl get functions.pkg.crossplane.io
kubectl get functionrevisions.pkg.crossplane.io
kubectl get configurations.pkg.crossplane.io
kubectl get configurationrevisions.pkg.crossplane.io
kubectl get datalabs -n workspace
If reconciliation fails, read the Datalab conditions and events. Check that the required APIs are served. The provider APIs used here are namespaced:
kubectl api-resources --api-group=kubernetes.m.crossplane.io
kubectl api-resources --api-group=helm.m.crossplane.io
kubectl api-resources --api-group=keycloak.m.crossplane.io
kubectl api-resources --api-group=gateway.networking.k8s.io
For a managed store, also check its API group from the prerequisite table. Verify the Data address, storage access, and each requested service. If you declared a session, also check its browser login before giving users access.