Proxmox-Managed OIM (Omnia Infrastructure Manager)

---

## Traceability Metadata

| Field | Value |
|-------|-------|
| **Specification Name** | Proxmox-Managed OIM (Omnia Infrastructure Manager) |
| **Spec Number** | BR-96665 |
| **Category** | ha-day-2 |
| **Related To** | JA-14405, BR-22381, BR-57246, JA-14425, JA-6312 |

---

# Proxmox-Managed OIM (Omnia Infrastructure Manager)

---

## Summary

Infra Admins need the OIM (Omnia Infrastructure Manager) virtualized as a Proxmox VM, so it can be snapshotted, backed up, and restored using the same Proxmox-native mechanism as the rest of the management plane. This isolates the OIM-specific virtualization work from the broader Proxmox rollout for OME, SFM, and the Service K8s Control Plane (BR-22381), so OIM High Availability (JA-14405) can depend on it directly.

---

## Problem Statement

The OIM is deployed bare-metal only today, with Pacemaker/PCS as its only HA option. Virtualizing the OIM was previously bundled into a single spec covering OME, SFM, and the Service K8s Control Plane together, which made it hard for OIM HA to depend on Proxmox virtualization without also depending on unrelated, independently-timed work.

---

## Value Proposition

### Customer Value

Customers get a Proxmox-hosted OIM that can be snapshotted before upgrades and restored via whole-VM recovery, on its own delivery timeline — independent of whether they also adopt Proxmox for OME, SFM, or the Service K8s Control Plane.

---

## User Personas

- **Infra Admin**: Deploys and manages the OIM VM lifecycle.
- **Site Reliability Engineer (SRE)**: Performs disaster recovery and restore for the OIM VM.

---

## Use Cases

### Use Case 1: OIM VM Deployment
**Actor**: Infra Admin
**Context**: A Proxmox host is available with shared storage configured.
**Action**: Admin builds an OIM VM from their own OS subscription and runs the standard OIM setup.
**Result**: The OIM is fully operational and PXE-boots cluster nodes identically to a bare-metal OIM.

### Use Case 2: Whole-VM Backup and Restore
**Actor**: Site Reliability Engineer (SRE)
**Context**: Routine maintenance or disaster recovery for the OIM.
**Action**: Admin backs up the OIM VM to shared storage; on failure, restores it to any Proxmox host.
**Result**: Complete OIM state is captured or restored with no manual reconstruction.

### Use Case 3: Proxmox-Native HA Failover
**Actor**: System (automatic)
**Context**: The Proxmox host running the OIM fails.
**Action**: Proxmox detects the failure and restarts the OIM VM on a surviving host.
**Result**: The OIM resumes with minimal downtime — the mechanism JA-14405 depends on for OIM HA.

---

## Scope Definition

### Goals (Execution Outcomes)

- Define the Proxmox VM deployment model for the OIM.
- Provide backup/restore automation for the OIM VM via shared storage.
- Give JA-14405 (OIM HA) a direct Proxmox-native failover mechanism to depend on.

### Non-Goals (Scope Boundaries)

- Virtualizing OME, SFM, or the Service K8s Control Plane — that remains in BR-22381.
- Provisioning the Proxmox host OS itself (customer Day 0 prerequisite).
- Shipping a pre-built OIM VM image — the customer builds it from their own OS subscription.

---

## Requirements

### Requirement: OIM VM Networking and Storage [Req 1]

The OIM VM must reach the admin and BMC networks and use shared storage so it behaves identically to a bare-metal OIM and can fail over between hosts.

#### Scenario: PXE Boot via Bridged Networking
- When a bare-metal node requests a PXE boot, the OIM VM serves it identically to a bare-metal OIM.

### Requirement: Whole-VM Backup and Restore [Req 2]

The system must support backing up and restoring the OIM VM as a complete unit.

#### Scenario: Disaster Recovery Restore
- When an admin restores the OIM VM from a backup, the complete VM state returns with no manual reconstruction.

### Requirement: Proxmox-Native HA for the OIM VM [Req 3]

The system must configure native Proxmox HA for the OIM VM.

#### Scenario: Host Failure Failover
- When the Proxmox host running the OIM fails, the OIM VM automatically restarts on a surviving host.

---

## Acceptance Criteria

- **AC-001**: The OIM VM PXE-boots cluster nodes identically to a bare-metal OIM. [Req 1]
- **AC-002**: The OIM VM can be backed up and restored as a complete unit, with post-restore health checks confirming it is operational. [Req 2]
- **AC-003**: A simulated host failure triggers automatic OIM VM restart on a surviving host. [Req 3]
- **AC-004**: The OIM VM is built by the customer from their own OS subscription, not shipped as a pre-built image. [Req 1]

---

## Dependencies

- **Proxmox VE cluster** with shared storage (minimum 3 hosts for automated failover).
- **Relationship to BR-22381**: BR-22381 now covers OME, SFM, and the Service K8s Control Plane only; this spec covers OIM virtualization exclusively. The two are complementary, not mutually exclusive.
- **JA-14405 (OIM HA)** depends on this spec's Proxmox-native failover mechanism.

---

## Risks

| Risk | Category | Impact | Likelihood | Mitigation |
|---|---|---|---|---|
| Proxmox host is a single point of failure in single-host deployments | Operational | High | Medium | Document that HA requires 3+ hosts; provide manual recovery runbooks for smaller deployments. |
| Customer unfamiliarity with Proxmox | Adoption | Medium | High | Provide comprehensive documentation and runbooks. |

---

## Assumptions / Open Questions

### Assumptions

- **A1**: The customer deploys a minimum 3-node Proxmox cluster for HA; single-host deployments are supported without automated failover.

### Open Questions

- **Q1**: What is the supported Proxmox VE version range? (Tracked jointly with BR-22381.)

---

## Reliability

| Failure Mode | System Behavior |
|---|---|
| Proxmox host failure | HA fences the failed host and restarts the OIM VM on a surviving host. |
| Shared storage unavailable | OIM VM operations fail with actionable errors; a running VM may continue in degraded mode until next disk I/O. |

The issue provides no files, tests, or implementation entry points; begin by locating the existing OIM deployment and infrastructure automation in the repository. Use AC-001–AC-004 to define validation for PXE networking, complete backup and restore, customer-built images, health checks, and Proxmox failover, while resolving the supported Proxmox VE version.

Written by the indexing model from the issue text.