User GuidesSpX Overlay Lifecycle

SpX Overlay Assignment

View as Markdown

The SpX Overlay Assignment workflow binds an existing overlay’s VRF to a specific device and to a specific set of ports on that device. It updates Nautobot’s intent — the model of which VRF terminates on which port — 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 SpX Overlay lifecycle, after SpX Overlay Creation provisions the VRF and Overlay objects.

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

Experimental

This workflow is experimental and not intended for general use. Use it only in test or pilot environments.

Prerequisites

Before running, confirm:

  • 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.
  • 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

SpX Overlay Assignment is not exposed in the Config Manager UI today. It is invoked as a child of SpX 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 and queries Nautobot for the VRF matching overlay_id + namespace_tag + site. The query is asserted to return exactly one VRF — zero or more than one raises ApplicationError and halts the workflow.

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

    Attaches the VRF to the device’s VRF list in Nautobot. If the VRF is already assigned to this device, the stage short-circuits with vrf_assigned=False; otherwise it returns vrf_assigned=True.

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

    For each port in port_names, assigns the VRF to the interface in Nautobot, running all per-port writes in parallel. Ports that already have this VRF assigned are skipped and recorded in already_assigned_ports. The final assigned_ports list contains the ports actually changed by this run.

Verifying outcomes

After the workflow reports success, confirm:

  • All three stages green on the Config Manager run page.
  • Result shape — assigned_ports lists the ports actually changed; vrf_assigned=true means the device-level binding was new this run; vrf carries the bound VRF record.
  • Nautobot shows the VRF on the device and on each named interface.
  • Run a deploy to push the resulting intended-config change to the device. The simplest path is SpX Overlay Tenant Change, which combines assignment with the subsequent re-render and deploy.

Common issues

get_device_and_vrf raises ApplicationError “0 VRFs found”.

The overlay has not been created yet at this site. Run SpX 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.