Architectural Decision Records (ADRs)¶

This directory contains Architectural Decision Records (ADRs) for the Jupyter Notebook Validator Operator project.

What are ADRs?¶

Architectural Decision Records document important architectural decisions made during the project lifecycle. Each ADR captures: - The context and problem being addressed - The decision made and alternatives considered - The consequences of the decision - Implementation notes and references

ADR Index¶

Critical / High-Priority ADRs¶

ADR	Title	Status	Date
001	Operator Framework and SDK Version	Accepted	2025-11-07
002	Platform Version Support Strategy	Superseded	2025-11-07
056	OpenShift Support Window 4.20–4.22	Accepted	2026-09-12
003	CRD Schema Design and Versioning	Accepted	2025-11-07
004	Deployment and Packaging Strategy	Accepted	2025-11-07
005	RBAC and Service Account Model	Accepted	2025-11-07
006	Version Support Roadmap and Testing Strategy	Accepted	2025-11-07
007	Distribution and Catalog Strategy	Accepted	2025-11-07
008	Notebook Testing Strategy and Complexity Levels	Accepted	2025-11-07
009	Secret Management and Git Credentials	Accepted	2025-11-07
010	Observability and Monitoring Strategy	Accepted	2025-11-07
011	Error Handling and Retry Strategy	Accepted	2025-11-07
012	Release and CI/CD Strategy	Accepted	2025-11-07
013	Output Comparison and Diffing Strategy	Accepted	2025-11-08

Security & Credential Management ADRs (NEW - 2025-11-08)¶

ADR	Title	Status	Date
014	Notebook Credential Injection Strategy	Accepted	2025-11-08
015	Environment-Variable Pattern for Notebook Credentials	Accepted	2025-11-08
016	External Secrets Operator (ESO) Integration	Accepted	2025-11-08
017	Vault Dynamic-Secrets Injection Pattern	Accepted	2025-11-08
018	Secret Rotation & Lifecycle Management	Accepted	2025-11-08
019	RBAC & Pod Security Policies for Notebook Secret Access	Accepted	2025-11-08

Model-Aware Validation ADRs (NEW - 2025-11-08)¶

ADR	Title	Status	Date
020	Model-Aware Validation Strategy	Accepted	2025-11-08

Observability Enhancement ADRs (NEW - 2025-11-08)¶

ADR	Title	Status	Date
021	OpenShift-Native Dashboard Strategy	Accepted	2025-11-08
022	Community Observability Contributions	Accepted	2025-11-08

Build Integration ADRs (NEW - 2025-11-09)¶

ADR	Title	Status	Date
023	S2I Build Integration for OpenShift	Superseded	2025-11-08
024	Fallback Strategy for Missing Requirements	Accepted	2025-11-08
025	Community Build Methods Extension Framework	Accepted	2025-11-08
026	Smart Validation Pod Recovery and Build Strategy Selection	Accepted	2025-11-09
027	S2I Build Strategy for Git Integration	Superseded	2025-11-09
028	Tekton Task Strategy - Custom vs Cluster Tasks	Accepted	2025-11-09
029	Platform Version Dependency Review Process	Accepted	2025-11-09
030	Smart Error Messages and User Feedback	Accepted	2025-11-09
031	Tekton Build Strategy - Dockerfile vs Base Image	Accepted	2025-11-09
037	Build-Validation Sequencing and State Machine	Accepted	2025-11-10
038	Requirements Auto-Detection and Dockerfile Generation	Accepted	2025-11-20
039	Automatic SCC Management for Tekton Builds	Accepted	2025-11-21
040	Unique Build PVCs for Concurrent Tekton Builds	Accepted	2025-11-24
041	Exit Code Validation and Developer Safety Framework	Accepted	2025-11-20
042	Automatic Tekton Git Credentials Conversion	Accepted	2025-11-21
043	Separate Build Status Monitoring by Strategy	Accepted	2025-11-24
044	S2I Strategy Enhancements - Parity with Tekton	Accepted	2025-11-24
050	Fix S2I Build Status Monitoring	Accepted	2025-11-24
051	Git Init Container Image Compatibility	Accepted	2025-11-21
052	Resource Conflict Error Handling	Accepted	2025-11-24
053	Volume and PVC Support for Validation Pods	Accepted	2025-11-29
054	Pod Scheduling Support (Tolerations, NodeSelector, Affinity)	Accepted	2026-01-28

Testing & Validation ADRs (NEW - 2025-11-12)¶

ADR	Title	Status	Date
032	GitHub Actions CI Testing Against Kubernetes 1.31.10	Accepted	2025-11-09
033	End-to-End Testing Against Live OpenShift Cluster	Accepted	2025-11-09
034	Dual Testing Strategy with Kind and OpenShift	Accepted	2025-11-11
035	Test Tier Organization and Scope	Accepted	2025-11-11
036	Private Test Repository Strategy	Accepted	2025-11-11
048	Pre-Submission Validation Test Rig Strategy	Accepted	2025-11-12

ArgoCD Integration ADRs (NEW - 2026-01-24)¶

ADR	Title	Status	Date
049	ArgoCD Integration Strategy for GitOps Workflows	Accepted	2026-01-24

Deployment & Bundle Strategy ADRs¶

ADR	Title	Status	Date
045	Long-Term Strategic Deployment Plan	Accepted	2025-12-03
046	Multi-Version Bundle Strategy and Upgrade Chain	Accepted	2025-12-03
047	Fix Bundle Versioning for Consecutive Upgrade Chain	Superseded	2025-12-03
055	OperatorHub Submission Lessons Learned (v1.0.8)	Accepted	2026-04-22
056	OpenShift Support Window 4.20–4.22	Accepted	2026-09-12
057	Upgrade from Published v1.0.3-ocp4.19	Accepted	2026-01-25
058	OpenShift E2E Optional CI Strategy	Accepted	2026-09-13
059	k8s.io Client Library Upgrade to v0.35.x for OCP 4.22	Proposed	2026-09-16

ADR Status Definitions¶

Proposed: ADR is under discussion and review
Accepted: ADR has been approved and guides implementation
Deprecated: ADR is no longer recommended but kept for historical reference
Superseded: ADR has been replaced by a newer decision (link to new ADR)

ADR Template¶

When creating new ADRs, use the following structure:

# ADR XXX: [Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Context
[Describe the problem, constraints, and requirements]

## Decision
[Describe the decision and rationale]

## Consequences
[Describe positive, negative, and neutral consequences]

## Implementation Notes
[Technical details, code examples, configuration]

## References
[Links to relevant documentation, standards, or resources]

## Related ADRs
[Links to related ADRs]

## Revision History
| Date | Author | Description |
|------|--------|-------------|
| YYYY-MM-DD | Name | Initial decision |

Key Architectural Decisions Summary¶

Technology Stack¶

Language: Go 1.21+
Framework: Operator SDK v1.32.0+
Controller Runtime: v0.16+
Dependency Management: Go Modules

Platform Support¶

Primary: OpenShift 4.18, 4.19, 4.20
Secondary: Kubernetes 1.25+
Support Model: Tier 1 (OpenShift) and Tier 2 (Kubernetes)

API Design¶

CRD Group: mlops.dev
Initial Version: v1alpha1
Versioning Strategy: Multi-version with conversion webhooks
Schema: OpenAPI v3 with structural schema

Deployment¶

Primary: OLM Bundle for OpenShift OperatorHub
Secondary: Helm Chart for Kubernetes
Tertiary: Raw Manifests for GitOps/CI/CD

Security¶

RBAC Model: Hybrid (cluster-wide and namespace-scoped)
Service Accounts: Separate for operator and validation pods
Permissions: Least privilege principle
Pod Security: Non-root, dropped capabilities, read-only root filesystem

Changing ADRs¶

Accepted decisions are architecture. Editing an Accepted ADR in place to change the decision makes the ledger fiction.

Before changing any ADR:

Identify the GitHub issue and run python3 .cursor/skills/repo-governor/engine/completion.py <issue-number> from the operator repository root (not from the skill directory). Proceed only on CONTINUE.
If the natural change collides with an Accepted ADR, treat it as an architecture review candidate. Do not implement around the decision and do not rewrite the Accepted file.
Capture a new decision as a Proposed ADR (next unused number). Proposed is not architecture anyone may rely on.
Accepted and Superseded are human ratification. An agent must not flip those statuses unless the assignee explicitly directed that ratification in the authorized issue.
The ADR MCP server (mcp-adr-analysis-server, project .cursor/mcp.json, ADR_DIRECTORY=docs/adrs) may analyze drift and suggest text. It does not ratify. Repo Governor’s architecture provider remains adapters/adr over this directory.

First window candidate: issue #44 (Proposed ADR-056 superseding ADR-002). Related drift not rewritten in that issue: ADR-006’s 4.18-first phases; ADR-046’s 4.18/4.19/4.20 bundle table.

New ADRs still follow the steps below.

Contributing to ADRs¶

When proposing a new ADR:

Create a draft: Copy the template and fill in the sections
Assign a number: Use the next available ADR number
Set status to "Proposed": Mark the ADR as under review
Open a PR: Submit for team review and discussion
Update status: Change to "Accepted" after approval
Update index: Add the ADR to this README

Questions?¶

For questions about ADRs or architectural decisions, please: - Open an issue in the GitHub repository - Discuss in team meetings - Contact the platform team

ADR Renumbering History¶

2026-01-24: Resolved Duplicate Numbering Conflicts¶

The following ADRs were renumbered to resolve duplicate numbering:

Original	New	Description
042-fix-s2i-build-status-monitoring	050-fix-s2i-build-status-monitoring	Fix S2I Build Status Monitoring
042-git-init-image-compatibility	051-git-init-image-compatibility	Git Init Container Image Compatibility
042-resource-conflict-error-handling	052-resource-conflict-error-handling	Resource Conflict Error Handling
045-volume-and-pvc-support	053-volume-and-pvc-support	Volume and PVC Support for Validation Pods

Note: ADR-042 (Automatic Tekton Git Credentials Conversion) remains the canonical ADR-042. ADR-045 (Long-Term Strategic Deployment Plan) remains the canonical ADR-045.

2026-09-12: Resolved Duplicate ADR-048¶

Original	New	Description
048-upgrade-from-published-v1.0.3-ocp4.19	057-upgrade-from-published-v1.0.3-ocp4.19	Upgrade from Published v1.0.3-ocp4.19

Note: ADR-048 (Pre-Submission Validation Test Rig Strategy) remains the canonical ADR-048.