Jupyter Notebook Validator Operator¶

Catch notebook regressions and broken model endpoints before they reach production. Run notebooks in the same environment as production, compare outputs against golden baselines, and validate live ML models.

Who is this for?¶

Data Scientists and Notebook Authors. Your notebook works on your laptop. Will it work in production? Validate notebooks locally with Podman or Docker before submitting to a cluster. Catch cell-output regressions, confirm model endpoint predictions, and stop silent failures before they reach your team.

• Start on your laptop: Validate a notebook locally (no cluster needed)
• Submit to a cluster: Quick Start and config/samples/

Platform Engineers and Operator Contributors. CI scripts check whether a notebook executed. They do not check whether outputs are correct, model predictions are valid, or cell outputs regressed from last week. This operator adds a declarative validation gate to your MLOps pipeline with Prometheus metrics, RBAC, and multi-tenant safety.

• Architecture: Architecture and DESIGN_DOC.md
• Development: CONTRIBUTING.md

Full workflow: Laptop → Cluster. Validate locally first, then promote the same notebook to OpenShift with a single oc apply. Same notebook, same result, production-grade guardrails.

Why this operator?¶

For data scientists¶

• Same-environment validation. Notebooks run in the same cluster, with the same GPU, memory, and model endpoints as production. No more "works on my laptop" failures.
• Golden notebook comparison. Cell-by-cell output diff with configurable numeric tolerances. Catches silent regressions that nbconvert --execute misses.
• Model endpoint validation. Auto-detect 9 model serving platforms and confirm predictions are correct, not just that the notebook ran.

For platform engineers¶

• Declarative validation gate. One CR defines the notebook, the golden baseline, and the model endpoint. Queryable with kubectl, Prometheus metrics included.
• Multi-tenant security. RBAC, Pod Security Standards, credential sanitization. Data scientists get validation results without cluster-admin.
• Pluggable build and serve. S2I, Tekton, KServe, OpenShift AI, vLLM, and 6 more platforms. Add new backends without changing the controller.

How is this different from nbval, Papermill, or Deepchecks? Those tools run on your laptop or in CI. They cannot test whether your notebook works with production GPU, secrets, and model endpoints. This operator runs validation inside Kubernetes, in the same environment as production. See Architecture Overview for details.

Architecture¶

flowchart LR
    User["User / CI"] -->|"kubectl apply"| CR["NotebookValidationJob CR"]
    CR --> Controller["Operator Controller"]
    Controller -->|"clone"| Git["Git Repository"]
    Controller -->|"create"| Pod["Validation Pod"]
    Pod -->|"execute via Papermill"| Notebook["Jupyter Notebook"]
    Controller -->|"compare"| Golden["Golden Notebook"]
    Controller -->|"validate"| Model["ML Model Endpoint"]
    Controller -->|"update"| Status["Job Status"]

Quick Start¶

Prerequisites¶

• OpenShift 4.20 - 4.22 or Kubernetes 1.31 - 1.35
• kubectl or oc CLI
• Optional: External Secrets Operator, KServe / OpenShift AI, Tekton Pipelines

Option A: OperatorHub (OpenShift)¶

Install from the built-in OperatorHub catalog:

oc apply -f - <<EOF
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: jupyter-notebook-validator-operator
  namespace: openshift-operators
spec:
  channel: stable
  name: jupyter-notebook-validator-operator
  source: community-operators
  sourceNamespace: openshift-marketplace
EOF

Option B: Helm (any Kubernetes)¶

helm repo add jupyter-validator \
  https://tosin2013.github.io/jupyter-notebook-validator-operator/charts/
helm install jupyter-validator jupyter-validator/jupyter-notebook-validator-operator \
  --namespace jupyter-validator-system --create-namespace

Option C: Kustomize¶

kubectl apply -k \
  https://github.com/tosin2013/jupyter-notebook-validator-operator/config/default?ref=v1.0.10

Option D: Build from source¶

make install
make docker-build docker-push IMG=quay.io/takinosh/jupyter-notebook-validator-operator:latest
make deploy IMG=quay.io/takinosh/jupyter-notebook-validator-operator:latest

Verify¶

kubectl get pods -n jupyter-notebook-validator-operator-system
kubectl get crd notebookvalidationjobs.mlops.mlops.dev

Usage¶

Apply a NotebookValidationJob to run and validate a notebook:

apiVersion: mlops.mlops.dev/v1alpha1
kind: NotebookValidationJob
metadata:
  name: simple-validation
spec:
  notebook:
    git:
      url: https://github.com/tosin2013/jupyter-notebook-validator-test-notebooks.git
      ref: main
    path: notebooks/tier1-simple/01-hello-world.ipynb
  podConfig:
    containerImage: quay.io/jupyter/scipy-notebook:latest

More examples in config/samples/, including GPU scheduling, golden notebook comparison, model validation, credential injection, and Tekton builds.

Key Features¶

Documentation¶

See docs/ for the full index, organized by Diataxis quadrant:

• Tutorials -- step-by-step lessons (local validation, quick start, ML workflows)
• How-to guides -- task recipes (credentials, model discovery, releases, CI setup)
• Reference -- technical descriptions (testing, platform compatibility, observability)
• Explanation -- architecture, build strategies, deployment patterns
• Design Document -- arc42 software design document
• ADRs -- architectural decision records

Contributing¶

Contributions are welcome from both data scientists (validate notebooks, report issues, improve docs) and operator developers (Go, controller-runtime, Kubernetes). See CONTRIBUTING.md for the path that matches your role.

Code of Conduct¶

This project follows the Contributor Covenant.

Community¶

• GitHub Issues -- bugs and feature requests
• GitHub Discussions -- Q&A and usage patterns
• OperatorHub.io -- OLM distribution
• Artifact Hub (OLM) -- OLM listing on Artifact Hub
• Artifact Hub (Helm) -- Helm chart distribution

License¶

Copyright 2025 Tosin Akinosho. Licensed under the Apache License, Version 2.0.