User GuidesSpectrum-X Overlay Lifecycle

Spectrum-X Overlay Tenant Change

View as Markdown

The Spectrum-X Overlay Tenant Change workflow drives an end-to-end overlay change against a single device: assign or remove the overlay on selected ports, re-render the tenant configuration, wait for the new render to land in the Config Store, and deploy the rendered configuration to the device. It is the supported operator entry point for adding, moving, removing, or expanding a tenant’s footprint on a switch. The final tenant-scoped deployment runs as an internal child workflow so callers cannot bypass assignment reconciliation and render synchronization.

Prerequisites

Before running, confirm:

  • For assignment or moves, the target overlay exists at the site (Spectrum-X Overlay Creation has been run, with the Overlay and L3 VXLANs created in Nautobot). No target overlay is needed when only removing an assignment.
  • Device exists in Nautobot with a primary IPv4, a supported platform (Cumulus Linux or NVOS), and current credentials in the secrets store.
  • Target ports exist as interfaces in Nautobot on the selected device. The form queries these interfaces after you choose the device. For assignment or move operations, ports already assigned to the target VRF are silently skipped as no-ops. Removal-only runs intentionally treat selected interfaces with existing Spectrum-X assignments as removal targets.
  • Render service is healthy. The workflow waits up to a bounded window for the render service to produce the new tenant config; outages on render will stall the workflow.
  • The tenant-scoped deployment validation will accept the diff. The internal deployment child only applies diffs that match the tenant-allowed nv set / nv unset patterns.

Running the workflow

  1. Navigate to the Config Manager URL for your environment.
  2. Click the + in the top right and select SpXOverlayTenantChangeWorkflow.
  3. Fill in the form using the field reference below and submit.
FieldDescriptionRequired
SiteThe site the overlay and device belong to.Yes
Overlay IDThe overlay to apply to the selected ports. Leave blank to remove their current Spectrum-X assignment without creating a replacement.No
DeviceThe target device.Yes
PortsOne or more interfaces queried from the selected device. The chosen ports are assigned to the target overlay, or unassigned when Overlay ID is blank. Already-assigned ports are skipped.Yes

After submission, a status page shows the six stages. The workflow runs without human approval.

Execution stages

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

  1. get_device — Load the target device record from Nautobot.

    Resolves the device by UUID and attaches search attributes for observability.

  2. assign_spx_overlay — Run Spectrum-X Overlay Assignment as a child workflow.

    Invokes Spectrum-X Overlay Assignment with the same inputs. With an Overlay ID, it binds the target VRF to the device and ports. Without an Overlay ID, it clears the selected ports’ VRF and Spectrum-X overlay assignments. After either operation, it removes any device/VRF association for which no interface on the device still maps to that VRF. The stage display links to the child workflow as soon as it starts. If the child fails, the stage retains the link and the tenant-change workflow stops before rendering or deployment. On success, the display shows the target Overlay, L3 VXLAN, VRF, and assigned ports, or the ports whose assignment was removed. If the requested state is already present, the next stage checks for a pending recorded configuration change before deciding whether to deploy.

  3. determine_deployment_action — Decide whether rendering and deployment are needed.

    Continues to render and deploy when the assignment workflow changed a VRF, port, device association, or overlays-plugin assignment. When the requested state is already present, it checks for a pending recorded configuration change. If one exists, render_tenant_config and wait_for_render are marked UNREACHABLE, and deploy applies the latest rendered tenant configuration. If none exists, all three downstream stages are marked UNREACHABLE and the workflow exits successfully with device_deployed=null.

  4. render_tenant_config — Trigger a tenant-scoped re-render for the device.

    Submits a render request to the render service to generate the updated tenant configuration that reflects the requested overlay change. The stage captures matching tenant and full intended configuration commit IDs from the same render snapshot.

  5. wait_for_render — Wait for the render to land in the Config Store.

    Polls the Config Store for the rendered configuration tagged with the commit ID from the prior stage. Times out if the render service does not produce the file within the configured window.

  6. deploy — Apply the rendered configuration.

    Invokes the internal tenant deployment child workflow against the device. The stage display links to the child while it is running and retains the link whether the child succeeds or fails. The child validates that the diff contains only tenant-allowed nv set / nv unset operations before applying it. Removal paths use the matching full intended configuration so omitted settings produce the required nv unset commands.

Verifying outcomes

After the workflow reports success, confirm:

  • All six stages green on the Config Manager run page (or determine_deployment_action green and downstream UNREACHABLE on the no-op path).
  • assign_spx_overlay stage display shows either the target Overlay, L3 VXLAN, VRF, and assigned ports or the ports whose assignment was removed. It also lists device/VRF associations removed by cleanup.
  • vrf_assigned, assigned_ports, unassigned_ports, removed_vrf_ids, overlay_assignments_created, overlay_assignments_removed, and vrf in the result reflect the change you intended.
  • device_deployed is the device name when a deploy actually ran; null when the no-op short-circuit fired.
  • Nautobot shows the desired VRF on assigned ports and no VRF on ports removed without replacement. Device/VRF associations remain only while at least one interface maps to that VRF.
  • Nautobot overlays plugin shows matching Spectrum-X assignments for the device and interfaces; stale assignments are removed.

Common issues

Workflow exits with downstream UNREACHABLE.

assign_spx_overlay reported no changes — the VRF was already bound to the device and to all named ports. Successful no-op; the device is already in the desired state.

render_tenant_config or wait_for_render times out.

The render service either rejected the render or is unavailable. Open the Render Service status page; once render is healthy, re-run this workflow.

deploy fails with DiffValidationError.

The tenant-scoped diff produced by the re-render contains commands outside the allowed VXLAN, EVPN, interface-VRF, or non-default-VRF operations. Either restructure the template change so only the tenant scope is affected, or apply the change via Configuration Deploy with a human approval.

get_device_and_vrf (inside the assign_spx_overlay child) raises ApplicationError.

Either zero or multiple VRFs were returned for the overlay_id + namespace_tag combination. Run Spectrum-X Overlay Creation if the overlay does not exist; reconcile duplicates in Nautobot if it does.