OSAC-1610: NetBox Inventory Backend for Bare Metal as a Service

[mennyaboush]

PRD: NetBox Inventory Backend for Bare Metal as a Service

Jira: https://redhat.atlassian.net/browse/OSAC-1610

Summary

This PRD introduces NetBox as a configurable inventory backend for OSAC's bare-metal-fulfillment-operator. Cloud Infrastructure Admins can configure NetBox as a source of truth for host discovery and allocation, enabling tenants to provision bare-metal instances transparently from their existing NetBox infrastructure without maintaining a separate inventory system.

Requesting Review On

• Requirements completeness and accuracy
• Scope boundaries (what's in vs. out)
• Acceptance criteria clarity and testability
• User story grounding and persona alignment
• Any assumptions that need validation before design begins

How to Review

Comment inline on specific sections. Key areas:

• Problem Statement: Does it accurately reflect the operator's pain?
• In Scope / Out of Scope: Are the boundaries clear and correct?
• User Stories: Do they capture the Cloud Infrastructure Admin's and Tenant User's needs without design details?
• Dependencies: Are critical dependencies identified?
• Assumptions: Are there preconditions we should verify before design?

Related Documents

• Clarifications log: See clarifications.md in this PR for the requirements clarification Q&A (5 locked decisions, D1–D5).
• Research: Background and design context at https://github.com/mennyaboush/osac-workspace/tree/main/osac-1610

🤖 Generated with Claude Code

[openshift-ci-robot]

@mennyaboush: This pull request references OSAC-1610 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the feature to target the "5.1.0" version, but no target version was set.

Details

In response to this:

PRD: NetBox Inventory Backend for Bare Metal as a Service

Jira: https://redhat.atlassian.net/browse/OSAC-1610

Summary

This PRD introduces NetBox as a configurable inventory backend for OSAC's bare-metal-fulfillment-operator. Cloud Infrastructure Admins can configure NetBox as a source of truth for host discovery and allocation, enabling tenants to provision bare-metal instances transparently from their existing NetBox infrastructure without maintaining a separate inventory system.

Requesting Review On

• Requirements completeness and accuracy
• Scope boundaries (what's in vs. out)
• Acceptance criteria clarity and testability
• User story grounding and persona alignment
• Any assumptions that need validation before design begins

How to Review

Comment inline on specific sections. Key areas:

• Problem Statement: Does it accurately reflect the operator's pain?
• In Scope / Out of Scope: Are the boundaries clear and correct?
• User Stories: Do they capture the Cloud Infrastructure Admin's and Tenant User's needs without design details?
• Dependencies: Are critical dependencies identified?
• Assumptions: Are there preconditions we should verify before design?

Related Documents

• Clarifications log: See clarifications.md in this PR for the requirements clarification Q&A (5 locked decisions, D1–D5).
• Research: Background and design context at https://github.com/mennyaboush/osac-workspace/tree/main/osac-1610

🤖 Generated with Claude Code

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: mennyaboush
Once this PR has been reviewed and has the lgtm label, please assign masayag for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

AI EP Review: EP-260

Score: 9/10 | Verdict: PASS
Feature: OSAC-4346

Criterion	Score	Notes
WHAT (clear need)	2/2	Clear user-facing capability: NetBox as an inventory backend for BMaaS allocation/deallocation. Three canonical personas covered with user stories (Cloud Infrastructure Admin: 3 stories, Cloud Provider Admin: 1 story, Tenant User: 3 stories). Tenant Admin is mentioned in AC #9 ('Tenant Users and Tenant Admins see no difference') but lacks a user story — since the experience is identical to Tenant User, a combined 'Tenant Admin / Tenant User' heading would satisfy coverage. BMaaS service clearly identified. Installation dimension addressed via Helm configuration.
WHY (justification)	2/2	Strong Problem Statement names concrete pain: sovereign-cloud operators forced to maintain a separate inventory system as a second source of truth, causing data inconsistency, operational burden during host lifecycle changes, and risk of misalignment. Ties directly to a real deployment scenario with specific consequences.
User-Facing Focus	1/2	Mostly user-focused but design leakage in Dependencies section: 'the NetBox backend registers against the existing inventory interface' and 'Pluggable backend interface (OSAC-1032)' prescribe internal architecture. In Scope includes 'E2E tests validate the full BareMetalInstance lifecycle with NetBox as the inventory source' — an engineering verification concern, not a user-observable capability. The remainder of the PRD describes user-observable outcomes appropriately.
Right-Sized	2/2	Coherent single capability — configure NetBox backend, allocate hosts, monitor lifecycle, deallocate — all interdependent. No bundling of independent capabilities. Minor restatement: NFR 'Tenant isolation' restates AC #8-9; NFR 'Inventory independence' restates Out of Scope boundaries. Risks section is outside the standard PRD template sections.
Testability	2/2	Acceptance criteria are verifiable by using the product: configure backend and verify connection, provision by label selector, observe lifecycle state transitions, verify error messages on connectivity failure, confirm host release on deletion. AC #3 'shows a clear message indicating the host is being readied' is slightly vague on what constitutes 'clear.' AC #10 (E2E tests pass in CI) is engineering verification rather than product-level testability.

Verdict: Solid PRD with a clear capability, strong justification, and verifiable acceptance criteria; held back from a perfect score by design leakage in the Dependencies section and a missing Tenant Admin user story heading.

Feedback: Fix the design leakage: rewrite the Dependencies to describe what the feature depends on from a user/product perspective rather than naming internal interfaces (e.g., 'Depends on the existing inventory backend selection mechanism' instead of 'registers against the existing inventory interface'). Move the E2E test bullet from In Scope to the design document. Add Tenant Admin to the Tenant User story heading as a combined 'Tenant Admin / Tenant User' section since the experience is identical, or explain why Tenant Admin is unaffected.

Critical (0)

None.

Important (4)

1. Design leakage in Dependencies: 'Pluggable backend interface (OSAC-1032) — the NetBox backend registers against the existing inventory interface' prescribes internal architecture. Rewrite to describe the product-level dependency without naming the internal interface.
2. Tenant Admin is referenced in AC Virtual machines as a service #9 ('Tenant Users and Tenant Admins see no difference') but has no user story. Since the capability is identical to Tenant User, consolidate under a combined 'Tenant Admin / Tenant User' heading per the PRD guide's persona consolidation rule.
3. Risks section (lines 210-213 of prd.md) is outside the standard PRD template sections. Move the known-limitation content to the design document or fold it into Out of Scope as a boundary statement.
4. NFR 'Tenant isolation' restates AC Add enhancement proposal for quota management #8-9 and In Scope transparency; NFR 'Inventory independence' restates Out of Scope boundaries. This restatement adds length without new information — consider trimming the NFRs to content not already covered elsewhere.

Suggestions (3)

1. AC adds Apache 2.0 LICENSE file #3 'shows a clear message indicating the host is being readied' — specify what the message should convey (e.g., host identifier, preparation stage) to make it concretely verifiable.
2. In Scope bullet 'E2E tests validate the full BareMetalInstance lifecycle' and AC Add Baremetal Observability Enhancement #10 are engineering verification concerns. Move to the design document; In Scope should describe user-observable capabilities.
3. Clarifications header says 'OSAC-1610' but the feature is OSAC-4346 — minor inconsistency to correct.

Structural notes (0)

None.

---

Review cost

Model: claude-opus-4-6
Cost: $0.2709
Tokens: 4.8k in / 4.7k out
Cache: 82.0k read
Active time: 1m 34s
API calls: 0

[mennyaboush]

Closing — resubmitting with correct issue key OSAC-4346