User GuidesSpectrum-X Overlay Lifecycle

Spectrum-X Overlay Assignment

View as Markdown

The Spectrum-X Overlay Assignment workflow changes the Spectrum-X assignment on a specific set of device ports. With a target Overlay ID, it binds that overlay’s VRF to the device and ports. Without a target Overlay ID, it removes the selected ports’ existing Spectrum-X assignment without creating a replacement. It updates Nautobot’s IPAM intent and matching OverlayAssignment entries in the overlays plugin without touching the device itself; the device-side change happens when a subsequent deploy applies the resulting intended configuration. Assignment is the second step in the Spectrum-X Overlay lifecycle, after Spectrum-X Overlay Creation provisions the VRF and Overlay objects.

For the end-to-end assign + render + deploy lifecycle, use Spectrum-X Overlay Tenant Change — it calls this workflow as a child plus the render and deploy steps.

Prerequisites

Before running, confirm:

  • For assignment or moves, the target overlay exists at the site with exactly one VRF allocated under overlay_id + namespace_tag. Multiple VRFs (or zero) under the same Overlay ID is treated as an error. This is not required for removal-only changes.
  • Device exists in Nautobot and is in the site you are assigning at.
  • Port names match Nautobot interface names on the target device. Already-assigned ports for this VRF are skipped, not re-assigned.

Running the workflow

Spectrum-X Overlay Assignment is not exposed in the Config Manager UI today. It is invoked as a child of Spectrum-X Overlay Tenant Change, which orchestrates assignment plus the subsequent re-render and deploy. To run assignment in isolation, submit the workflow through the API with the target overlay, device, ports, and site.

After submission, a status page shows the three stages.

Execution stages

The workflow runs three stages in order. None require manual approval.

  1. get_device_and_vrf — Resolve the device and the overlay’s VRF.

    Loads the target device record. When an Overlay ID is supplied, it queries Nautobot for the matching VRF and requires exactly one result. For removal-only changes, it skips the target-VRF lookup.

  2. assign_vrf_to_device — Bind the VRF to the device record.

    Attaches the target VRF to the device’s VRF list in Nautobot. If the VRF is already assigned, the stage reports vrf_assigned=False. Removal-only changes skip this step.

  3. assign_vrf_to_ports — Bind the VRF to each named port.

    For each port in port_names, sets the target VRF or clears the VRF for a removal-only change, running all per-port writes in parallel. It reconciles the overlays plugin so interface assignments match the new Spectrum-X intent while preserving assignments for other overlay types. When no interface on the device remains mapped to an old VRF or Spectrum-X overlay, the corresponding device-level association is deleted. The result separates changed ports into assigned_ports and unassigned_ports, reports cleaned-up device VRFs in removed_vrf_ids, and exposes plugin mutations through overlay_assignments_created and overlay_assignments_removed.

Verifying outcomes

After the workflow reports success, confirm:

  • All three stages green on the Config Manager run page.
  • Run a deploy to push the resulting intended-config change to the device. The simplest path is Spectrum-X Overlay Tenant Change, which combines assignment with the subsequent re-render and deploy.

For assignment runs, also confirm:

  • Result shape — assigned_ports lists the interfaces changed, vrf_assigned=true means the target device-level binding was new, and overlay_assignments_created and overlay_assignments_removed reflect plugin reconciliation.
  • Nautobot shows the target VRF on the device and on each named interface.
  • Nautobot overlays plugin shows OverlayAssignment entries for the device and each named interface under the target overlay.

For removal-only runs, instead confirm:

  • Result shape — unassigned_ports lists the interfaces changed, vrf is null, removed_vrf_ids lists unused device/VRF associations cleaned up, and the overlay-assignment counts reflect plugin reconciliation.
  • Nautobot shows no VRF association on any selected interface and no device/VRF association when no other device interface uses that VRF.
  • Nautobot overlays plugin shows no Spectrum-X OverlayAssignment on any selected interface and no device-level assignment when no other interface uses that overlay.

Common issues

get_device_and_vrf raises ApplicationError “0 VRFs found”.

The overlay has not been created yet at this site. Run Spectrum-X Overlay Creation first.

get_device_and_vrf raises ApplicationError “multiple VRFs found”.

Nautobot has more than one VRF matching overlay_id + namespace_tag + site. Investigate — Overlay IDs are expected to be unique within a site. Reconcile the duplicates before re-running.

assign_vrf_to_device reports vrf_assigned=false.

The device was already bound to this VRF. Successful no-op.

assign_vrf_to_ports reports many ports in already_assigned_ports.

Those ports were already bound to this VRF. Successful no-op for those ports — assigned_ports lists only the ports newly bound by this run.