Maintenance Contract Evolution

Summary

Maintenance on bare metal servers is expressed today via the ServerMaintenance CRD owned by metal-operator, driven by labels and annotations on the Server (metal.ironcore.dev/maintenance-{needed,requested,approved,reason}) combined with ServerMaintenanceSpec.Policy (OwnerApproval vs. Enforced). It works, but it is stringly-typed and leaks platform
maintenance into the core server lifecycle. There is no first-class cordon, no negotiated drain/eviction handshake between Server and ServerClaim, no fleet-wide rate-limiting of concurrent evictions, the BMC/BIOS update controllers sit next to claim/availability, and the Gardener / CAPI drain handshake lives in the CCM (the wrong layer).

The outcome we want is a first-class, typed maintenance contract on Server and ServerClaim (cordon, announce, approve, disruption budget), the maintenance machinery decoupled into the metal-maintenance-operator, a single controlled path for booting servers to a chosen image, and a clean upstream integration point for CAPI / MCM.

Scope

In Scope

• Cordon on Server (WS 1). A first-class, typed "do not place new claims here" signal. Foundation for the rest.
• Typed announce / approve + disruption budget (WS 2). Replace the label/annotation flow with a typed contract on Server and ServerClaim, plus fleet-wide rate-limiting of concurrent evictions.
• Move ServerMaintenance to metal-maintenance-operator (WS 3). Decouple platform maintenance from the core server lifecycle.
• Boot tool (WS 4). A single controlled path for booting a Server to a chosen image (maintenance OS, diagnostics, sanitization).
• Move BMC* / BIOS* controllers (WS 5). Firmware / settings / kernel work moves alongside ServerMaintenance.
• CAPI / MCM integration (WS 6). Upstream actors participate in the drain/approve handshake via the typed contract, replacing today's CCM-side logic.
• Enhancement proposals. Each workstream lands a written proposal in ironcore-dev/enhancements before implementation.

Out of Scope

• Redesigning the Server state machine (Initial -> Discovery -> Available -> Reserved). Maintenance stays an overlay.
• Replacing existing in-tree ServerMaintenance usage in a single cut-over. A deprecation window is expected.
• A single-cut migration of CCM logic. CCM and the new path coexist during the deprecation window.

Responsible Areas

• Metal Automation
• Gardener Extension
• Documentation

Contributors

• @adracus
• @afritzler

Acceptance Criteria

• Cordon (WS 1)

  • Enhancement proposal landed.
  • Typed cordon field on Server (no longer label/annotation driven).
  • Scheduling / claim placement honors the cordon signal.

• Typed announce / approve + disruption budget (WS 2)

  • Enhancement proposal landed.
  • Typed announce / approve fields on Server and ServerClaim replace the metal.ironcore.dev/maintenance-* labels and annotations.
  • Deprecation path documented for ServerMaintenanceSpec.Policy (OwnerApproval / Enforced).

• Move ServerMaintenance (WS 3)

  • ServerMaintenance CRD and controller live in metal-maintenance-operator.
  • Migration path for existing ServerMaintenance objects.

• Boot tool (WS 4)

  • Enhancement proposal landed.
  • A single controlled path exists for booting a Server to a chosen image.
  • Boot-driven controllers can be moved cleanly on top of it.

• Move BMC* / BIOS* (WS 5)

  • BMC and BIOS update controllers live in metal-maintenance-operator.
  • No remaining firmware / settings work in the claim / availability controllers of metal-operator.

• CAPI / MCM integration (WS 6)

  • CAPI providers / Gardener MCM participate in the drain / approve handshake via the typed contract.
  • CCM-side drain logic has a documented deprecation path; CCM and the new path coexist during the window.

• Common

  • Suggested order honored: WS 1 (cordon) -> WS 2 (announce/approve + DB) -> WS 4 (boot tool) -> WS 3 (move ServerMaintenance) || WS 5 (move BMC* / BIOS*). WS 6 (CAPI / MCM) runs on its own timeline.
  • Cross-repo coordination plan for WS 3, 5, 6 (PR ordering, releases, chart version pinning).
  • Long-lived bound claims with no upstream consumer have a defined approval path.

Action Items

• Assign labels (e.g., area/metal-automation, kind/design)
• Set milestone
• Open one tracking issue per workstream (1-6)
• Add this issue to the Roadmap project board