Skip to content

PRD for base OS management for bare-metal instances #162

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ItzikEzra-rh wants to merge 1 commit into from
Closed

PRD for base OS management for bare-metal instances #162

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions enhancements/OSAC-1270-base-os-management/prd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
---
prd_id: OSAC-1270
title: Base OS Management for Bare-Metal Instances
jira_key: OSAC-1270
status: Draft
Comment on lines +2 to +5

@coderabbitai coderabbitai Bot Jul 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== repo files around prd =="
git ls-files | grep -E '(^|/)prd\.md$|OSAC-1270|base-os-management' || true

echo "== target file excerpt =="
if [ -f enhancements/OSAC-1270-base-os-management/prd.md ]; then
  cat -n enhancements/OSAC-1270-base-os-management/prd.md | sed -n '1,80p'
else
  echo "target file not found"
fi

echo "== Jira target version references for OSAC-1270 across repo =="
rg -n "OSAC-1270|target.?version|target_version|5\.0\.0|version" -S . || true

Repository: osac-project/enhancement-proposals

Length of output: 50390

🌐 Web query:

osac OSAC-1270 Jira target version 5.0.0 base os management bare metal

💡 Result:

A comprehensive search of available technical documentation and public repositories yielded no evidence of an issue or feature identified as OSAC-1270 relating to version 5.0.0, base OS management, or bare-metal configurations [1][2][3][4][5]. The search results for the term OSAC in the context of Jira (often seen in project management systems) returned various unrelated entries, such as Apache projects (LENS-1270, REEF-1270, MRM-1270) [2][4][5] and general hardware identifiers (e.g., Huawei S12700 series switches, Intel Xeon E3-1270, Advantech ECU-1270) [6][7][8][9][10][11][12]. The term "osac-operator" exists as a GitHub project [3], but no specific association with an issue numbered "1270" and the specified version or configuration was found [3]. If OSAC-1270 refers to a proprietary or internal ticketing system, please verify the ticket number, project name, or the specific organization to which the issue belongs, as this information is not available in public technical databases.

Citations:

🌐 Web query:

"osac-project" "target version" "version" "Jira"

💡 Result:

In the context of the osac-project (OpenShift Automation Components), the "target version" in Jira refers to a release version field used by the project's CI/CD automation to track and validate pull requests against specific milestones [1][2][3][4]. When developers submit pull requests to the project's repositories (such as osac-operator or osac-aap), the CI system checks the associated Jira issue [1][3]. If an issue is missing a "target version" (e.g., "5.0.0") or if the provided target version does not match the expected milestone for the branch being targeted by the pull request, the automated system will generate a warning or error message [1][2][3][4]. These Jira issues are typically managed on the Red Hat Jira instance (redhat.atlassian.net) and integrated via tools like the openshift-eng/jira-lifecycle-plugin, which ensures that development work is properly aligned with release versioning and project milestones [1][2][3].

Citations:

Set the Jira target version to 5.0.0.

The PRD contains jira_key: OSAC-1270, but OSAC-1270 needs a Jira target version configured for the target branch. Set it to 5.0.0 before merging.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@enhancements/OSAC-1270-base-os-management/prd.md` around lines 2 - 5, Update
the OSAC-1270 PRD metadata to set the Jira target version to 5.0.0, preserving
the existing prd_id, title, jira_key, and status fields.

---
# Base OS Management for Bare-Metal Instances

| Field | Value |
|-------------|--------------------------------------------------------------|
| Author(s) | Adrien Gentil |
| Jira | [OSAC-1270](https://redhat.atlassian.net/browse/OSAC-1270) |
| Date | 2026-07-26 |

## Problem Statement

This PRD covers the integration of the DiskImage resource (defined in [OSAC-2540](https://redhat.atlassian.net/browse/OSAC-2540)) into BMaaS. It does not change DiskImage behavior — that is fully specified in OSAC-2540.

Bare metal instances can reference a custom OS image today, but only as a raw URL string with no discoverability, metadata, or governance. Tenants must know the exact image URL to use it; there is no curated catalog to browse, no lifecycle management to signal when an image is deprecated or unsupported, and no scoping to control which images are available per tenant. Cloud Provider Admins and Tenant Admins have no structured surface to publish and manage OS images independently. If unaddressed, bare metal provisioning remains opaque and error-prone, with tenants unable to discover what images are available and no guard against use of stale or unsupported images.

## In Scope

- A BaremetalInstance must have an effective DiskImage reference at creation time — either explicitly selected by the user or defaulted from the BaremetalInstanceCatalogItem. Creation is rejected when neither provides a reference. The instance is provisioned with the OS from that image.

@coderabbitai coderabbitai Bot Jul 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Define precedence when both image inputs are supplied.

Specify whether an explicitly selected DiskImage overrides the catalog default or whether conflicting values are rejected. Without this rule, identical provisioning requests can resolve to different OS images depending on implementation.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@enhancements/OSAC-1270-base-os-management/prd.md` at line 23, Update the
BaremetalInstance creation requirement to explicitly define precedence when both
user-selected and catalog-default DiskImage references are present; specify
whether the explicit DiskImage overrides the catalog default or conflicting
values are rejected, and ensure the provisioning behavior follows that rule.

- DiskImage deletion is blocked when any BaremetalInstance (in any non-deleted state) or any BaremetalInstanceCatalogItem references it — applied to both global and tenant-scoped DiskImages.
- UI/API support for selecting and resolving eligible DiskImages during bare-metal instance creation; DiskImage browsing, lifecycle management, and lifecycle UI are defined by OSAC-2540.
- E2E test coverage for DiskImage selection at bare-metal instance provision time, added to the existing bare-metal test suite.
- DiskImages for bare-metal instances reuse the same resource, metadata schema, image source format, and two-tier visibility model (global + tenant-scoped) as defined in OSAC-2540.
Comment on lines +23 to +27

@coderabbitai coderabbitai Bot Jul 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Use the canonical BareMetal resource names.

The upstream API contract uses BareMetalInstance and BareMetalInstanceCatalogItem, but this PRD consistently uses BaremetalInstance and BaremetalInstanceCatalogItem. Align the terminology throughout the document to prevent ambiguity between the PRD and public API resources.

Also applies to: 34-35, 41-42, 50-51, 55-55, 60-60, 64-68

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@enhancements/OSAC-1270-base-os-management/prd.md` around lines 23 - 27,
Update the PRD terminology throughout to use the canonical resource names
BareMetalInstance and BareMetalInstanceCatalogItem, replacing every occurrence
of BaremetalInstance and BaremetalInstanceCatalogItem while preserving the
documented behavior and references.

Comment on lines +25 to +27

@coderabbitai coderabbitai Bot Jul 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Make DiskImage eligibility enforceable in the acceptance criteria.

“Eligible” should explicitly cover the OSAC-2540 visibility and lifecycle rules: global or same-tenant images only, and obsolete images blocked from new provisioning, with deprecated-image behavior matching OSAC-2540. Otherwise an implementation could satisfy these criteria while allowing cross-tenant or obsolete images.

Also applies to: 64-69

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@enhancements/OSAC-1270-base-os-management/prd.md` around lines 25 - 27,
Update the DiskImage selection and provisioning acceptance criteria to enforce
OSAC-2540 eligibility: allow only globally visible or same-tenant images, block
obsolete images from new bare-metal provisioning, and preserve OSAC-2540
behavior for deprecated images. Apply the same eligibility requirements to the
related criteria at the additional referenced section.


## Out of Scope

- Custom OS image upload by tenants — images are curated and published by Cloud Provider Admins or Tenant Admins only.
- In-place OS upgrade (package-level) — OS image selection applies at provision time only.
- OS configuration management beyond initial boot (e.g., configuration drift detection).
- BaremetalInstanceTemplate — no DiskImage field on the template.
- BaremetalInstanceCatalogItem schema changes — the catalog item's existing parameter model is sufficient to accept a DiskImage reference without structural changes.

## User Stories

### Cloud Provider Admin

- As a Cloud Provider Admin, I want to create a BaremetalInstanceCatalogItem that references a global DiskImage as default so that all tenants provisioning bare-metal instances from it receive a platform-approved OS image without having to select one.
- As a Cloud Provider Admin, I want DiskImage deletion to be blocked when any BaremetalInstance or BaremetalInstanceCatalogItem references it, so that I do not inadvertently break running workloads or catalog offerings.

### Cloud Infrastructure Admin

Not affected by this feature. Cloud Infrastructure Admins manage core infrastructure (network, storage, compute backends) and are not involved in OS image selection or catalog management for bare-metal instances.

### Tenant Admin

- As a Tenant Admin, I want to create a BaremetalInstanceCatalogItem that references one of my organization's DiskImages as default so that my users' bare-metal instances are provisioned with our approved OS image without requiring manual selection.
- As a Tenant Admin, I want DiskImage deletion to be blocked when any BaremetalInstance or BaremetalInstanceCatalogItem references it, so that I do not inadvertently break running workloads or catalog offerings.

### Tenant User

- As a Tenant User, I want to select a DiskImage when creating a bare metal instance so that the instance is provisioned with my chosen OS.

## Dependencies

- **OSAC-2540 (DiskImage resource):** Defines and implements the DiskImage API resource, metadata schema, two-tier visibility (global + tenant-scoped), image lifecycle (active, deprecated, obsolete, reactivation), and image source format. This feature extends DiskImage to BaremetalInstance and must land after OSAC-2540.
- **OSAC-1118 (Baremetal OSAC API):** Provides the BaremetalInstance lifecycle foundation (create, provisioning, ready, deprovision, deleted) that this feature extends with OS image selection.

## Acceptance Criteria

- [ ] A Tenant User can select a DiskImage when creating a BaremetalInstance and the instance is provisioned with that OS image.
- [ ] BaremetalInstance creation fails with a clear error when no DiskImage is specified and the BaremetalInstanceCatalogItem provides no default.
- [ ] A Cloud Provider Admin can create a BaremetalInstanceCatalogItem that references a global DiskImage as default.
- [ ] A Tenant Admin can create a BaremetalInstanceCatalogItem that references a tenant-scoped DiskImage as default.
- [ ] Deleting a DiskImage that is referenced by any BaremetalInstance or BaremetalInstanceCatalogItem is rejected.

@coderabbitai coderabbitai Bot Jul 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Keep deletion protection consistent with the requirement.

The requirement limits blocking references to BareMetalInstances in non-deleted states, but this acceptance criterion says “any” BareMetalInstance. Add the non-deleted qualifier so deleted historical resources do not unintentionally prevent DiskImage deletion.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@enhancements/OSAC-1270-base-os-management/prd.md` at line 68, Update the
DiskImage deletion acceptance criterion to specify that deletion is rejected
only when referenced by BaremetalInstances or BaremetalInstanceCatalogItems that
are not deleted, allowing references from deleted historical resources.

- [ ] E2E tests cover DiskImage selection during bare-metal instance provisioning.
Loading