Operating-model plan: NetBox -> deploy (planning session input)

Date: 2026-07-25. Branch: dc-dc-stage4-phase3-maas-deploy. Status: ADVISORY / planning input. Adopts nothing. docs/CURRENT-STATE.md remains the sole status authority (GA-R1). Authored in the Chat design seat; PINNED for a dedicated operator planning session. Companion to: docs/audit/decision-recon-20260725.md, docs/audit/committee-20260724-track2-bundle-render.md, and the PROPOSED NetBox-coupling decision in docs/design-decisions.md.

A PLAN, not a decision. Deliberately NOT a D-NNN entry: the operator asked for a recommendation plus a dedicated planning session, so the target operating model is not ripe for ratification. Implement NOTHING from this file.

Authored against repo HEAD bc9a2df.

================================================================================

1. The model as the operator described it (2026-07-25)

================================================================================

Draft changes in NetBox -> a tool or queued item reads the changes; operator approves before anything begins -> OpenTofu / MAAS / Juju (whichever the change requires) processes the deployment, assignment or change -> the process is as automated and self-healing as possible without operator interaction -> operator is notified on completion, with logs entered and artifacts created -> operator is given next-step instructions derived from the process

This is the standard source-of-truth-driven infrastructure automation shape. The three recommendations below are refinements to it, not a different mechanism.

================================================================================

2. Recommendation A -- the approval gate belongs on the RENDERED DIFF

================================================================================

Approving "someone changed a prefix in NetBox" does not tell the operator what will happen to the cloud. Approving "here is the resulting overlay diff, the tofu plan, and the validator report" does.

NetBox draft -> renderer emits artifacts onto a git branch -> THE BRANCH DIFF IS THE CHANGE REQUEST -> operator approves the diff -> apply (tofu -> MAAS -> Juju, each gated as today)

Costs nothing extra: the artifacts are generated either way; the diff is free.
Rollback for free (git revert); audit for free (the diff IS the record, with reviewer and timestamp attached).
Matches existing discipline exactly: verify-before-mutate wants a verification artifact, and the diff plus validator report IS that artifact.
Keeps intent store and executable artifact reconciled by construction, not by trust.

================================================================================

3. Recommendation B -- split "self-healing" in two

================================================================================

SAFE, unattended -- CONVERGENT RE-ASSERT of declarative state:

re-run the renderer; diff generated output against committed output
re-apply idempotent configuration
re-run validators and behavioural assertions (provider-bundle-check.py, cloud-assert.sh) These read, compare and report. Run them on a timer.

NOT SAFE unattended -- AUTONOMOUS REMEDIATION of observed drift:

On a live multi-tenant cloud the remediation can BE the outage, and the blast radius crosses tenant boundaries. An automated actor that "repairs" a VIP or reassigns a prefix while tenants are running can take down a plane.
It contradicts the standing rules directly: destructive steps gated individually and never batched; no live re-architecture inside a step.

RECOMMENDATION: self-healing is READ / VERIFY / REPORT plus idempotent re-assert. Drift detection emits an alert AND a proposed remediation diff; the mutation stays gated. The automation's job is to make the operator's decision instant and well-evidenced, not to make it unnecessary.

================================================================================

4. Recommendation C -- the draft primitive already exists

================================================================================

No NetBox branching plugin is required. Code built the source separation in bc9a2df:

netbox/prod-draft-dump.py -> netbox.baldurkeep.com, FROZEN v1 reference (4.5.8), read-only for the duration of VR1 netbox/office1-record-dump.py -> office1-netbox 10.10.1.10:8000, the VR1 WORKING APEX / "the RECORD" (4.6.4). Read-only, token from environment, never embedded or printed, one script per SOURCE so the source can never be confused netbox/draft/vr1-draft.json (draft) vs netbox/draft/vr1-office1-current-20260725.json (record snapshot)

So: DIFF DRAFT AGAINST RECORD, and that diff is the intent change feeding the same approval gate in section 2. Low-tech, already committed, keeps write-back deferred per DOCFIX-195, and adds no new dependency to the airgap mirror (D-107).

================================================================================

5. Known gap to close in the session

================================================================================

GitBucket has no Actions-style CI runner, so "the renderer runs automatically" needs a host: a jumphost systemd timer, or a NetBox webhook plus a worker. Either way an automated push needs a GitBucket credential over HTTPS basic auth, because SSH access is v2-deferred. That is a security-ledger row (credential scope, storage, rotation), NOT a design decision, and it should be opened before any automated push exists.

SEQUENCING NOTE: the operator intends to migrate from GitBucket to an in-house product, SpryGit. The runner and API surface this operating model needs are therefore REQUIREMENTS INPUT for SpryGit -- captured in docs/audit/sprygit-requirements-inputs-20260725.md. Do not design around GitBucket's current limits as if they were permanent.

================================================================================

6. Agenda for the planning session

================================================================================

Ratify or amend the approval-gate placement (section 2).
Ratify the self-healing split; enumerate exactly which checks run unattended (3).
Decide intent-store mechanics: NetBox draft objects, draft-vs-record JSON diff, or both at different tiers (4).
Decide the runner and its credential posture; open the security-ledger row (5).
Decide whether generated artifacts are committed (recommended) or produced at deploy time.
Decide the notification and next-step surface: what the operator receives on completion, and how "next steps" derive from which gates passed.
Decide what this becomes: one process D-NNN (GA-R3: it needs architectural consequence and a Roosevelt-delta to qualify), or a process runbook governed by an existing decision. Doubt resolves DOWN to OPS.

================================================================================

7. Research scope requested by the operator -- NOT YET PERFORMED

================================================================================

The operator asked for best-practice workflow options grounded in real-world documentation and processes used by datacenters running this stack. That research has NOT been done; nothing in this file is its result. Candidate sources:

Canonical Charmed OpenStack reference architectures and operations guidance; terraform-provider-juju; Juju bundle/overlay lifecycle practice.
Sovereign Cloud Stack (SCS) operational documentation -- directly relevant, since this deployment implements the scs-0302 Domain Manager persona (D-051, D-064).
NetBox and Nautobot source-of-truth-driven automation, golden configuration, and intended-vs-actual reconciliation models.
GitOps control-loop practice for infrastructure, specifically where the approval gate sits relative to render and apply.
MAAS plus OpenTofu substrate lifecycle patterns for multi-site deployments.
OpenStack Operations Guide material on change management and drift.

For each: what the pattern is, who runs it at datacenter scale on this stack, where the approval gate sits, what it automates unattended, and what it deliberately refuses to automate. Deliverable: options with trade-offs plus a recommendation measured against the Roosevelt-delta fitness function.