User GuidesSpX Overlay Lifecycle

SpX Overlay Tenant Change

View as Markdown

The SpX Overlay Tenant Change workflow drives an end-to-end overlay change against a single device: assign the overlay to the device and 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 workflow most operators interact with when adding, moving, or expanding a tenant’s footprint on a switch — the underlying SpX Overlay Assignment, Render Service, and Tenant Deploy workflows are exposed individually for advanced cases but are normally orchestrated by this workflow.

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 (SpX Overlay Creation has been run, with the Overlay and L3 VXLANs created in Nautobot).
  • Device exists in Nautobot with a primary IPv4, a supported platform (Cumulus Linux or NVOS), and current credentials in the secrets store.
  • Port names match Nautobot interface names on the target device. Already-assigned ports are silently skipped.
  • 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.
  • Tenant Deploy validation will accept the diff. Tenant Deploy 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 device.Yes
DeviceThe target device.Yes
Port Names (comma-separated)Interface names on the device to bind to the overlay’s VRF (comma-separated list). Already-assigned ports are skipped.Yes
NamespaceTag used to identify the overlay namespace in Nautobot.No

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

Execution stages

The workflow runs five 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 SpX Overlay Assignment as a child workflow.

    Invokes SpX Overlay Assignment with the same inputs to bind the VRF to the device and its ports. The stage display shows the Overlay name, L3 VXLAN name, VRF, and assigned ports. If the assignment is a complete no-op (vrf_assigned=false and no assigned_ports changed), the workflow short-circuits — render_tenant_config, wait_for_render, and deploy are marked UNREACHABLE and the workflow exits successfully with device_deployed=null.

  3. 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 new VRF assignment. The stage captures the resulting tenant_config_file commit ID for tracking.

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

  5. deploy — Apply the rendered configuration via Tenant Deploy.

    Invokes Tenant Deploy as a child workflow against the device. Tenant Deploy performs its own diff validation (allowed nv set patterns only) before applying.

Verifying outcomes

After the workflow reports success, confirm:

  • All five stages green on the Config Manager run page (or assign_spx_overlay green and downstream UNREACHABLE on the no-op path).
  • assign_spx_overlay stage display shows the Overlay name, L3 VXLAN name, VRF name, and assigned ports.
  • vrf_assigned, assigned_ports, 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 VRF on the device and ports.
  • Nautobot overlays plugin shows the Overlay with the device assignment recorded.

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 (Tenant Deploy child) fails with DiffValidationError.

The tenant-scoped diff produced by the re-render exceeds the tenant-allowed nv set / nv unset set. See Tenant Deploy → Diff validation rules. 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 SpX Overlay Creation if the overlay does not exist; reconcile duplicates in Nautobot if it does.