Skip to content

Deploy On-Prem Authoritative Foundation (HyOps Blueprint)

  • Purpose: Bring up the on-prem authoritative foundation so that subsequent platform services can provision from NetBox-backed IPAM-driven intent. Owner: Platform engineering

  • Trigger: New on-prem environment, Proxmox SDN rebuild, or NetBox authority replacement

  • Impact: SDN segmentation and IPAM authority become active; downstream IPAM-gated platform VM steps depend on this state

  • Severity: P2 Pre-reqs: hyops init proxmox completed for target env; Proxmox API access confirmed; vault decrypt working; required NetBox and PostgreSQL secrets set.

  • Rollback strategy: Destroy optional VM steps first (custom_platform_vm, postgres_core_vm, control_plane_vm), then platform/onprem/netbox, then core/onprem/network-sdn. Review Proxmox SDN state manually before re-applying.

Context

Blueprint ref: onprem/authoritative-foundation@v1 Location: hybridops-core/blueprints/onprem/authoritative-foundation@v1/blueprint.yml

This is the Day-1+ chain. Non-foundation steps (control_plane_vm, postgres_core_vm, custom_platform_vm) are marked optional: true and gate on NetBox being ok before they run. They are the IPAM-driven expansion layer: finalize NetBox inputs before activating them.

Step flow:

  1. core/onprem/network-sdn (bootstrap): enforce Proxmox SDN zone, VNets, and DHCP (skip_if_state_ok: true, live verification on skip enabled)
  2. platform/onprem/netbox (bootstrap): deploy NetBox as the IPAM authority and reconcile live service drift on deploy
  3. platform/onprem/control-node (authoritative, optional): IPAM-gated control-node VM
  4. platform/onprem/postgresql-core (authoritative, optional): IPAM-gated PostgreSQL core VM
  5. platform/onprem/platform-vm (authoritative, optional): IPAM-gated generic platform VM slot

Steps 3–5 require platform/onprem/netbox state to be ok and use addressing_mode: ipam with ipam_authority: netbox. Do not activate them until NetBox is populated with the intended IPAM data for the target environment.

Preconditions and safety checks

  1. Validate init readiness:

    hyops init status --env <env>

  2. Confirm Proxmox API access and SDN permissions:

    hyops preflight --env <env> --module core/onprem/network-sdn

  3. Ensure required secrets exist (NetBox DB password at minimum for step 2):

    hyops secrets ensure --env <env> NETBOX_DB_PASSWORD

  4. Validate blueprint definition and preflight gate:

    hyops blueprint validate --ref onprem/authoritative-foundation@v1
hyops blueprint preflight --env <env> --ref onprem/authoritative-foundation@v1

Steps

Phase 1: Foundation (SDN + NetBox)

  1. Initialize an env-scoped blueprint overlay
    hyops blueprint init --env <env> \
  --ref onprem/authoritative-foundation@v1 \
  --dest-name authoritative-foundation.yml

Edit ~/.hybridops/envs/<env>/config/blueprints/authoritative-foundation.yml and set:

  • network_sdn.inputs.zone_name, zone_bridge, dns_domain, vnets: match your Proxmox topology
  • netbox_foundation.inputs.db_state_ref: point to your PostgreSQL core state if using a separate DB host

Source blueprint defaults intentionally mirror the minimal bootstrap foundation (vnetmgmt + vnetdata). If your environment already carries additional VNets, always use an env-scoped overlay rather than relying on the source defaults directly.

  1. Keep the first authoritative run foundation-only

Current hyops blueprint commands do not support a per-step --steps selector. For the first authoritative run, use the env-scoped overlay file and remove the optional VM steps from the overlay until NetBox/IPAM inputs are ready.

  1. Execute the foundation overlay

    hyops blueprint deploy --env <env> \
  --file $HOME/.hybridops/envs/<env>/config/blueprints/authoritative-foundation.yml \
  --execute \
  --yes

  2. Verify NetBox is reachable and populate IPAM data

    hyops state show --env <env> --module core/onprem/network-sdn
hyops state show --env <env> --module platform/onprem/netbox

Access NetBox via the published URL in module state and populate prefixes, IP ranges, and device records for the planned VMs before proceeding to Phase 2.

Phase 2: Authoritative VM expansion (IPAM-gated, optional)

Only proceed once NetBox state is ok and IPAM data is populated.

  1. Finalize optional step inputs in the overlay and re-add the steps

At minimum:

  • control_plane_vm.inputs.vm_name
  • postgres_core_vm.inputs.target_state_ref or explicit target inputs, if you intend to reconcile an existing PostgreSQL host

  • custom_platform_vm.inputs.addressing plus the VM-set details required by your platform-vm contract

  • Rerun the full overlay

network_sdn remains state-skippable with live skip verification, while netbox_foundation is reconciled on deploy so authority service drift is caught live:

hyops blueprint deploy --env <env> \
  --file $HOME/.hybridops/envs/<env>/config/blueprints/authoritative-foundation.yml \
  --execute

Verification

Success indicators:

  • Blueprint summary ends with status=ok.
  • core/onprem/network-sdn state is ok; SDN zone, VNets, and DHCP pools are visible in Proxmox UI.
  • platform/onprem/netbox state is ok; NetBox URL is reachable and returns a healthy API response.
  • Optional VM steps (if activated) report status=ok; VMs are provisioned with IPAM-assigned addresses.

Spot-check state for key steps:

hyops state show --env <env> --module core/onprem/network-sdn
hyops state show --env <env> --module platform/onprem/netbox
hyops state show --env <env> --module platform/onprem/control-node

Post-actions and clean-up

  • Document the NetBox URL and admin credentials in the environment state record.
  • After NetBox is populated, activate optional VM steps as platform capacity is needed.
  • This foundation is the prerequisite for any subsequent blueprint that uses ipam_authority: netbox (e.g. onprem/postgresql-ha@v1, onprem/rke2@v1).
  • If SDN was rebuilt, verify downstream module states that reference network segmentation outputs.

References

License: MIT-0 for code, CC-BY-4.0 for documentation