OpenCHAMI Fabrica-Generated Core Services Migration Tracking

---

## Traceability Metadata

| Field | Value |
|-------|-------|
| **Specification Name** | OpenCHAMI Fabrica-Generated Core Services Migration Tracking |
| **Spec Number** | BR-23098 |
| **Category** | provisioning-boot |
| **Related To** | BR-36094, BR-80993, BR-19442, BR-31940, JA-21006, JA-9043 |

---

# OpenCHAMI Fabrica-Generated Core Services Migration Tracking

---

## Summary

OpenCHAMI is incrementally replacing several of its legacy Go services with services generated by its own `Fabrica` code-generation framework (consistent resource-based REST APIs, storage, and versioning conventions). As of OpenCHAMI v0.2.0, three legacy components have already been replaced: the Boot Script Service (BSS) by `boot-service`, the cloud-init server by `metadata-service`, and Hydra/OPAAL (OIDC auth) by `tokensmith`. A fourth, more consequential migration — SMD (State Management Database) to a new `Inventory Service` — has been introduced upstream but is not yet backward-compatible (it drops SMD's node-discovery capability) and is not part of the official release train. This spec tracks Omnia's adoption path for the already-released Fabrica services and flags the SMD/Inventory Service transition as a future watch item. It intentionally does not modify any existing Omnia functional spec (e.g., BSS override behavior) — that is deferred to a dedicated follow-on spec once this dependency migration lands.

---

## Problem Statement

Omnia's provisioning stack is built and documented against the legacy OpenCHAMI component names — BSS, the cloud-init server, and SMD. OpenCHAMI's own systemd unit set no longer includes `bss.service`, `cloud-init-server.service`, Hydra, or OPAAL as of release v0.2.0; they are replaced by `boot-service.service`, `metadata-service.service`, and `tokensmith.service`, with new API path prefixes (`/boot-service/*` instead of `/boot/v1/*`, `/metadata-service/*` instead of `/cloud-init/*`) and new `ochami` CLI verbs (`ochami boot`, `ochami metadata`). If Omnia continues pinning to pre-v0.2.0 OpenCHAMI packaging, it stops receiving upstream fixes; if it upgrades without accounting for the new service names and paths, PXE boot and node personalization can break. This is a dependency-version migration, not a change to Omnia's own functional behavior.

---

## Value Proposition

### Customer Value

Customers stay current with OpenCHAMI's actively supported service set instead of a deprecated BSS/cloud-init/Hydra/OPAAL stack, while `boot-service`'s legacy-compatible API mode provides a safe interim compatibility path so existing Omnia automation is not required to change on day one of the upgrade.

---

## User Personas

- **Infra Admin**: Upgrades the OIM's OpenCHAMI package set.
- **Cluster Admin**: Consumes BSS/metadata configuration through Omnia's existing abstractions.
- **Security Administrator**: Owns the auth path change from Hydra/OPAAL to tokensmith's JWKS/token model.

---

## Use Cases

### Use Case 1: OpenCHAMI Package Upgrade on the OIM
**Actor**: Infra Admin
**Context**: The OIM currently runs OpenCHAMI pre-v0.2.0 (BSS, cloud-init server, Hydra/OPAAL).
**Action**: The administrator upgrades the OIM's OpenCHAMI package set to v0.2.0 or later.
**Result**: `boot-service`, `metadata-service`, and `tokensmith` come up in place of the legacy services.

### Use Case 2: Legacy API Compatibility During Transition
**Actor**: System (automatic)
**Context**: Omnia's own playbooks still call BSS-style endpoints.
**Action**: `boot-service` runs with its legacy-compatible API mode enabled, serving BSS-compatible endpoints under `/boot/v1/*`.
**Result**: Existing Omnia automation continues to function without immediate changes while a native-API migration is scoped separately.

### Use Case 3: Auth Path Cutover
**Actor**: Security Administrator
**Context**: Components that previously validated tokens against Hydra/OPAAL need to point at the new auth service.
**Action**: The administrator updates JWKS/cert-consuming configuration to reference `tokensmith`'s endpoint.
**Result**: Token issuance and validation continue to work under the new service.

---

## Scope Definition

### Goals (Execution Outcomes)

- Confirm Omnia can run against OpenCHAMI v0.2.0+ using `boot-service`'s legacy-compatible mode as an interim step, without breaking PXE boot, cloud-init, or auth flows.
- Inventory every Omnia playbook, config template, and doc reference that names BSS, the cloud-init server, Hydra, or OPAAL directly.
- Identify the follow-on spec(s) needed to move Omnia's own automation to the native `boot-service` / `metadata-service` / `tokensmith` resource APIs, rather than the legacy compatibility layer.

### Non-Goals (Scope Boundaries)

- Rewriting BR-80993 (BSS User Overrides), BR-36094 (Kernel Boot Parameter Management), or any other existing functional spec to target the new native APIs. That is explicitly deferred to a later, separate spec once this dependency migration lands.
- Migrating SMD to Inventory Service. Inventory Service is not yet backward-compatible with SMD (no node-discovery support) and is not part of the official OpenCHAMI release train; tracked here only as a future watch item.
- Migrating Magellan or `coresmd`. Neither has a Fabrica-generated replacement today.

---

## Requirements

### Requirement: OpenCHAMI v0.2.0+ Compatibility [Req 1]

The OIM's OpenCHAMI package set must be upgradable to v0.2.0 or later without breaking existing PXE boot, cloud-init, or auth flows.

#### Scenario: PXE Boot via Legacy-Compatible boot-service
- When a node PXE boots against `boot-service` running with its legacy API mode enabled, it receives boot parameters using the same BSS-style payload Omnia already generates.

#### Scenario: Auth Continuity
- When a component previously validating tokens against Hydra/OPAAL is repointed at `tokensmith`'s JWKS endpoint, token validation continues to succeed.

### Requirement: Inventory of Legacy-Named Touchpoints [Req 2]

The system must produce an inventory of every Omnia playbook, config template, and documentation reference that names BSS, the cloud-init server, Hydra, or OPAAL directly, so follow-on migration specs can be scoped.

#### Scenario: Inventory Identifies Follow-On Candidates
- When the inventory is complete, it identifies BR-36094 and BR-80993 as the primary BSS-referencing specs that will need a dedicated native-API migration spec.

### Requirement: SMD / Inventory Service Watch Item [Req 3]

The system must track Inventory Service's stabilization (backward compatibility, discovery support) without taking any dependency on it.

#### Scenario: No Premature Adoption
- While Inventory Service remains non-backward-compatible with SMD, no Omnia spec references or depends on it. Adoption is only considered once a dedicated migration spec is scoped.

---

## Acceptance Criteria

- **AC-001**: The OIM successfully runs OpenCHAMI v0.2.0+ with `boot-service`, `metadata-service`, and `tokensmith` active, and existing Omnia-driven PXE boot and cloud-init flows continue to work via `boot-service`'s legacy API mode. [Req 1]
- **AC-002**: Auth-consuming components are validated against `tokensmith`'s JWKS endpoint in place of Hydra/OPAAL. [Req 1]
- **AC-003**: A documented inventory exists listing every Omnia spec, playbook, or doc referencing BSS, the cloud-init server, Hydra, or OPAAL by name. [Req 2]
- **AC-004**: No changes are made to BR-80993's, BR-36094's, or any other functional spec's Requirements or Acceptance Criteria as part of this spec. [Non-Goal confirmation]

---

## Dependencies

- **OpenCHAMI release v0.2.0+** (upstream): ships `boot-service`, `metadata-service`, and `tokensmith`.
- **BR-36094 (Kernel Boot Parameter Management)** and **BR-80993 (BSS User Overrides)**: both currently target legacy BSS directly; flagged here for a follow-on native-API spec, not modified by this spec.
- **BR-19442 (Diskful Boot with OpenCHAMI)**: depends on OpenCHAMI's provisioning schema generally; should be re-validated against v0.2.0.
- **JA-21006 / JA-9043 (Magellan/SMD-based discovery)**: unaffected for now — SMD remains in place until Inventory Service matures.

---

## Risks

| Risk | Category | Impact | Likelihood | Mitigation |
|---|---|---|---|---|
| `boot-service`'s legacy API mode is a "for the most part" compatibility layer, not a guaranteed 1:1 replacement | Technical | Medium | Medium | Validate every BSS-dependent Omnia flow (BR-36094, BR-80993) against the legacy mode before cutover. |
| Hydra/OPAAL → tokensmith changes the JWKS URL and bootstrap credential model | Technical | Medium | Medium | Update all JWKS/cert consumers in the same maintenance window as the OpenCHAMI upgrade. |
| Inventory Service (SMD replacement) matures faster than expected and diverges from Omnia's SMD assumptions | Operational | Low | Low | Treat as a watch item only (Req 3); do not adopt until a dedicated migration spec is scoped. |

---

## Assumptions / Open Questions

### Assumptions

- **A1**: OpenCHAMI v0.2.0's legacy-compatible API mode for `boot-service` is sufficient to avoid an immediate rewrite of BR-36094 / BR-80993.
- **A2**: Magellan and `coresmd` remain unchanged in this OpenCHAMI release cycle — no Fabrica-generated equivalents exist for either today.

### Open Questions

- **Q1**: What is OpenCHAMI's timeline for retiring `boot-service`'s legacy-compatible API mode, and does Omnia need to complete its native-API migration before that date?
- **Q2**: Does `tokensmith`'s own in-progress internal migration to being Fabrica-generated change its external API surface, or is it purely an internal implementation detail?

---

## Scope & Sequencing

This spec covers only the dependency-version migration (upgrading to OpenCHAMI v0.2.0+ and validating legacy-compatible behavior). It is a prerequisite for — but does not itself perform — a later native-API migration of BR-36094 and BR-80993, which should be scoped as a separate spec once this one lands. SMD → Inventory Service remains a watch item outside all current sequencing.

No concrete files or tests are named. Start by inventorying Omnia playbooks, configuration templates, and documentation for BSS, cloud-init server, Hydra, and OPAAL references, then validate the OpenCHAMI v0.2.0+ upgrade and existing PXE, cloud-init, and auth flows; done means the acceptance criteria and documented inventory are complete.

Written by the indexing model from the issue text.