Omnia Monorepo Modularization

[i3igpete]

---

Traceability Metadata

Field	Value
Specification Name	Omnia Monorepo Modularization
Spec Number	BR-99001
Category	architecture
Related To
Priority Rationale	Customer request for modular code where individual playbook actions can be executed independently without running the entire provisioning flow. This addresses operational flexibility and reduces coupling between Omnia components.

---

Omnia Monorepo Modularization

---

Summary

Omnia is delivered as a monorepo containing all provisioning, discovery, telemetry, and orchestration playbooks in a single codebase. Customers and Dell Service Delivery Engineers must execute the entire playbook flow to perform individual actions, which creates operational overhead and limits flexibility. This spec describes the high-level plan to modularize Omnia through domain-based code segregation, workflow optimization, and eventual separation into independent service repositories. Individual domain services can be deployed and executed independently while a unified workflow entry point preserves the integrated deployment experience.

---

Problem Statement

Omnia currently operates as a monorepo where all domain services (provisioning, discovery, telemetry, orchestration, image building, build stream) are tightly coupled in a single codebase without clear domain boundaries, I/O contracts, or service interfaces. Customers and Dell Service Delivery Engineers cannot execute individual playbook actions without running the entire provisioning flow, which creates operational inefficiencies. For example, updating a single node's network configuration or reconfiguring storage requires executing the full end-to-end playbook sequence, even when only a subset of actions is needed. This coupling increases deployment time, increases risk of unintended side effects, and limits customers' ability to adopt Omnia components incrementally. The monorepo structure also makes it difficult for customers to contribute to or extend specific domain services without understanding the entire codebase.

---

Value Proposition

Business Value (Internal)

• Operational Efficiency: Dell Service Delivery Engineers can execute targeted actions without running full playbook flows, reducing deployment time and operational overhead.
• Reduced Support Burden: Smaller, focused repositories reduce the surface area for defects and simplify troubleshooting by isolating component issues.
• Ecosystem Growth: Modular repositories enable customers and partners to adopt and extend specific Omnia components without committing to the full stack, expanding the addressable market for partial deployments.
• Faster Iteration: Smaller repositories enable faster release cycles for individual components without coordinating across the entire monorepo.

Customer Value (External)

Customers can deploy and configure individual Omnia components independently, enabling incremental adoption and targeted updates. For example, a customer can update storage configuration without re-provisioning the entire cluster, or deploy only the telemetry stack to an existing Slurm cluster. This modularity reduces deployment risk, provides greater operational flexibility, and allows customers to integrate Omnia components into their existing infrastructure without replacing their entire stack. Customers can also contribute to specific components more easily, fostering a more collaborative development model.

---

User Personas

1. Dell Service Delivery Engineer — Deploys and configures Omnia clusters, needs to execute targeted actions without running full playbook flows.
2. Customer Infrastructure Architect — Designs cluster architecture, needs to adopt Omnia components incrementally without replacing entire infrastructure.
3. Customer Systems Administrator — Manages day-to-day cluster operations, needs to update specific components without triggering full re-provisioning.

---

Use Cases

Use Case 1: Targeted Network Configuration

Actor: Dell Service Delivery Engineer
Context: A customer needs to update network configuration on a subset of nodes without re-provisioning the entire cluster.
Action: Engineer executes the network configuration playbook independently.
Result: Network configuration is updated on target nodes without affecting other components or triggering full cluster re-provisioning.

Use Case 2: Incremental Telemetry Stack Deployment

Actor: Customer Infrastructure Architect
Context: A customer wants to deploy the Omnia telemetry stack to an existing Slurm cluster without replacing their current provisioning layer.
Action: Architect deploys the telemetry repository independently.
Result: Telemetry stack is operational alongside the existing Slurm cluster, with no disruption to running workloads.

Use Case 3: Storage Reconfiguration

Actor: Customer Systems Administrator
Context: A customer needs to reconfigure storage mounts on compute nodes without touching the provisioning or orchestration layers.
Action: Administrator executes the storage configuration playbook independently.
Result: Storage mounts are reconfigured on target nodes without affecting provisioning, orchestration, or other components.

---

Scope Definition

Goals (Execution Outcomes)

• Goal 1: Omnia code is organized by domain with clear boundaries, I/O contracts, and pre-checks that allow each domain service to be invoked independently.
• Goal 2: Each domain service exposes well-defined interfaces (whether API-based, CLI-based, or both), enabling standalone operation while preserving compatibility with integrated deployment.
• Goal 3: A unified workflow entry point preserves the integrated deployment experience, orchestrating domain services for customers who prefer a single-command deployment.
• Goal 4: Documentation and tooling are provided to guide customers on deploying domain services independently versus through the unified workflow.

Non-Goals (Scope Boundaries)

• Non-Goal 1: This spec does not define the exact repository boundaries or component separation strategy — that is deferred to engineering analysis and design.
• Non-Goal 2: This spec does not prescribe specific refactoring approaches or implementation details — those are engineering decisions.
• Non-Goal 3: This spec does not address migration of existing customer deployments to the modular model — that is a separate operational planning effort.
• Non-Goal 4: This spec does not prescribe whether domain services are implemented as containerized microservices with REST APIs, Ansible playbooks with CLI wrappers, or a hybrid — that is an engineering decision informed by the modularization approach.

---

Requirements

Requirement: Domain Service Independence [Req 1]

Each Omnia domain service can be deployed and executed independently without requiring other domain services to be present or executed.

Relates to: UC-1 — Targeted Network Configuration, UC-2 — Incremental Telemetry Stack Deployment, UC-3 — Storage Reconfiguration

Scenario: Standalone Deployment

• When a domain service is deployed independently, it executes successfully without requiring other Omnia domain services.
• The service validates its own dependencies via pre-checks and reports missing dependencies clearly.

Scenario: Integrated Deployment

• When multiple domain services are deployed together through the unified workflow entry point, the services operate as they do in the current monorepo model.
• No behavioral regression occurs compared to the current integrated deployment.

Requirement: Clear Interface Definition [Req 2]

Each domain service defines clear I/O contracts for data input, configuration, and dependencies on other domain services.

Relates to: UC-1 — Targeted Network Configuration, UC-2 — Incremental Telemetry Stack Deployment

Scenario: Interface Documentation

• When a domain service is inspected, the I/O contracts and dependencies are documented in a standard format.
• Documentation includes required data inputs, configuration parameters, and optional dependencies on other domain services.

Scenario: Dependency Validation

• When a domain service is deployed, the system validates that required dependencies are satisfied before execution.
• Missing dependencies are reported with clear error messages and remediation guidance.

Requirement: Unified Workflow Entry Point [Req 3]

A unified workflow entry point orchestrates all domain services for customers who prefer integrated deployment, preserving the current single-command deployment experience.

Relates to: UC-1 — Targeted Network Configuration, UC-2 — Incremental Telemetry Stack Deployment, UC-3 — Storage Reconfiguration

Scenario: Integrated Deployment via Unified Entry Point

• When the unified workflow entry point is used, the system orchestrates all domain services and behaves identically to the current monorepo deployment.
• No customer-facing changes are required for existing deployments.

Scenario: Modular Deployment

• When individual domain services are deployed independently, the system provides equivalent functionality to the integrated model for the targeted domain.
• Customers can use either the unified entry point or individual domain services without data loss or configuration migration.

Requirement: Programmatic Service Interfaces [Req 4]

Domain services expose well-defined, consistent interfaces — whether REST API endpoints, CLI commands, or both — to enable programmatic interaction, inter-service communication, and third-party integration. The interface model may follow a CLI-orchestrator pattern (analogous to kubectl orchestrating underlying services) or a direct API pattern, depending on the domain.

Relates to: UC-2 — Incremental Telemetry Stack Deployment, UC-3 — Storage Reconfiguration

Scenario: Programmatic Service Interaction

• When a domain service is deployed, it exposes a consistent interface (API, CLI, or both) that allows programmatic interaction with the service.
• Interfaces follow a consistent specification and contract model.

Scenario: Inter-Service Communication

• When multiple domain services are deployed, they communicate through defined interfaces rather than implicit shared state.
• Service boundaries are enforced through documented contracts, regardless of the underlying interface mechanism.

---

Usability

Dell Service Delivery Engineers and customers need clear documentation on when to use integrated versus modular deployment, how to identify component dependencies, and how to troubleshoot issues in a modular environment. The documentation must provide decision trees and examples for common deployment scenarios.

---

Reliability

Failure Mode	System Behavior
Missing dependency in modular deployment	Component reports missing dependency with clear error message and remediation guidance
Interface incompatibility between components	System validates interface compatibility before deployment and reports incompatibility with specific guidance
Partial deployment failure	System reports which components succeeded and which failed, enabling targeted retry without re-deploying successful components

Availability: Component repositories maintain the same availability targets as the current monorepo (99.5% for provisioning services)
Recovery: Failed component deployments can be retried independently without affecting other components

---

Supportability

• Documentation for component interfaces, dependencies, and deployment patterns
• Troubleshooting guides for common issues in modular deployments
• Knowledge base articles comparing integrated versus modular deployment approaches
• Engineering knowledge transfer for Dell Service Delivery Engineers on modular deployment workflows

---

Security

• Component repositories maintain the same security model as the current monorepo (RBAC, Step-CA, Vault integration)
• No new security surfaces are introduced by repository modularization
• Component interfaces do not expose sensitive data or credentials beyond what is already exposed in the monorepo

---

Performance

Metric	Target
Component deployment time	No measurable degradation compared to monorepo deployment for equivalent actions
Dependency validation time	< 5 seconds for typical component dependency checks
Interface documentation completeness	100% of component interfaces documented before GA

---

Telemetry

Telemetry tracks component deployment success rates, dependency validation failures, and adoption of modular versus integrated deployment models. Omnia Engineering consumes this data to identify patterns in component usage and inform future repository boundary decisions.

---

APIs

Domain services expose well-defined programmatic interfaces to enable interaction, inter-service communication, and third-party integration. The interface model — REST APIs (e.g., OpenAPI), CLI wrappers (analogous to kubectl orchestrating underlying services), or a hybrid — is an engineering decision. The requirement is that service boundaries are enforced through well-defined, documented contracts regardless of mechanism.

---

Documentation

• Internal: Component repository design document (Owner: Omnia Engineering)
• Internal: Interface definition standard (Owner: Omnia Engineering)
• External: Modular deployment guide for customers (Owner: Omnia Engineering)
• External: Component reference documentation (Owner: Omnia Engineering)

---

Dependencies

• Engineering analysis to define repository boundaries and component separation strategy
• Documentation and tooling to support modular deployment workflows
• Testing infrastructure to validate component independence and interface compatibility
• OpenCHAMI project as a reference example for proven multi-repo modularization in the HPC/provisioning domain (image building, boot script service, state management database)

---

Risks

Risk	Category	Impact	Likelihood	Mitigation
Repository boundary misalignment	Technical	High	Medium	Engineering analysis with customer input to validate boundaries before implementation
Interface incompatibility between components	Technical	Medium	Medium	Interface validation tooling and comprehensive integration testing
Customer confusion on deployment model	Operational	Medium	Medium	Clear documentation, decision trees, and examples for common scenarios
Increased maintenance overhead	Operational	Medium	Low	Automated dependency validation and standard interface definitions to reduce manual coordination

---

Opportunity Cost

If this work is deferred, customers continue to face operational inefficiencies from monolithic deployments, and Dell Service Delivery Engineers cannot execute targeted actions without running full playbook flows. This limits Omnia's appeal to customers who prefer incremental adoption or modular infrastructure. Competitors with more modular architectures may gain advantage in markets where operational flexibility is valued.

---

Acceptance Criteria

• AC-001: Domain services can be deployed and executed independently without requiring other domain services. [Req 1]
• AC-002: Each domain service defines clear I/O contracts for data input, configuration, and dependencies. [Req 2]
• AC-003: The unified workflow entry point orchestrates all domain services with no behavioral regression compared to the current monorepo. [Req 3]
• AC-004: Documentation provides clear guidance on when to use integrated versus modular deployment. [Req 2]
• AC-005: Dependency validation reports missing dependencies with clear error messages and remediation guidance. [Req 1]
• AC-006: Domain services expose consistent programmatic interfaces (API, CLI, or both) for interaction and inter-service communication. [Req 4]

---

Scope & Sequencing

Phased Approach: The modularization follows a phased transition that runs concurrently with ongoing feature development.

Phase 1 — Domain-Wise Code Segregation:

• Organize existing monorepo into per-domain folders with clear boundaries
• Define I/O contracts and pre-checks for each domain service
• Users can run playbooks from domain folders independently

Phase 2 — Workflow Optimization:

• Optimize input data flow across all identified domain services
• Standardize interfaces and dependency validation between domains

Phase 3 — Multi-Repo Split:

• Each domain becomes an independent repository
• Domain services expose consistent programmatic interfaces (REST APIs, CLI wrappers, or both)
• Unified workflow entry point orchestrates all domain services for integrated deployment

Excluded Scope (Deferred):

• Migration of existing customer deployments to the modular model
• Whether domain services are containerized microservices, CLI-wrapped playbooks, or a hybrid (engineering decision)

Broader Initiative Context: This is a foundational architectural change that enables domain-specific release cycles, customer contribution workflows, and incremental adoption patterns. The transition is designed to be non-disruptive, with each phase delivering incremental value while preserving the integrated deployment experience.

---

Artifacts

Artifact	Owner	Location
Repository boundary analysis document	Omnia Engineering	TBD
Interface definition standard	Omnia Engineering	TBD
Modular deployment guide	Omnia Engineering	TBD

---

Assumptions / Open Questions

Assumptions

• A1: Engineering analysis will identify clear, logical repository boundaries that align with customer usage patterns. OpenCHAMI's proven modularization pattern (image building, boot script service, state management database) demonstrates that such boundaries exist in the HPC/provisioning domain.
• A2: Domain service I/O contracts can be defined incrementally through domain-wise code segregation without requiring a full rewrite.
• A3: A unified workflow entry point can preserve the integrated deployment experience alongside the modular model without significant overhead.
• A4: The modularization transition can proceed concurrently with ongoing feature development without blocking delivery.

Open Questions

• Q1: What are the final domain service boundaries? Engineering has identified candidate domains; final boundaries will be validated through the phased transition. OpenCHAMI's modularization pattern serves as an external reference point.
• Q2: How will domain service versioning and compatibility be managed across repositories? (Deferred to engineering analysis)
• Q3: What is the migration path for existing customers who want to adopt the modular model? (Deferred to operational planning)
• Q4: What interface model will domain services use — REST APIs, CLI wrappers (kubectl-style orchestration), containerized microservices, or a hybrid? (Engineering decision, Phase 3)

---

[abhishek-sa1]

Changes for this issue will be part of the branch https://github.com/dell/omnia/tree/issue-4849-omnia-modernization