Skip to content

Deploy On-Prem Authoritative Foundation (HyOps Blueprint)

Execution context: Run this procedure from a terminal where hyops --help succeeds. If HybridOps.Core is not installed, complete the Quickstart. For deployment support, use GitHub Discussions.

  • Purpose: Establish the network and inventory authority required by subsequent platform operations.

  • 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. Each requires the logical primary_ipam authority with capability inventory_ipam. The blueprint currently binds that authority to NetBox.

The operation contract does not name NetBox. Preflight resolves the binding, evaluates its state, and records an authority receipt before an optional step can run.

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): establish the selected inventory and addressing authority
  3. platform/onprem/control-node (authoritative, optional): authority-gated control-node VM
  4. platform/onprem/postgresql-core (authoritative, optional): authority-gated PostgreSQL core VM
  5. platform/onprem/platform-vm (authoritative, optional): authority-gated platform VM slot

The canonical contract is:

authorities:
  primary_ipam:
    capability: inventory_ipam
    provider: netbox

contracts:
  addressing_mode: ipam
  requires_authority:
    ref: primary_ipam
    capability: inventory_ipam

Do not activate steps 3–5 until the selected authority contains the intended inventory and addressing 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: Network and inventory authority

  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 the configured authority and populate IPAM data

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

The shipped foundation binding is NetBox. Access it through the URL published in module state and populate prefixes, IP ranges, and device records for the planned VMs before proceeding to Phase 2.

Phase 2: Authority-gated VM expansion

Only proceed once blueprint preflight admits primary_ipam and the required 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 the authority foundation is reconciled on deploy so service drift is caught before the dependent operations:

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.
  • Blueprint preflight records primary_ipam, capability inventory_ipam, the selected binding, and the verified state without recording credentials.
  • 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

  • Retain the non-secret authority endpoint and instance identity in the run record. Keep credentials in the configured runtime vault or secret source.
  • After NetBox is populated, activate optional VM steps as platform capacity is needed.
  • This foundation is the prerequisite for subsequent operations that require the environment's inventory_ipam authority.
  • 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