> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/switch-infrastructure/config-manager/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/switch-infrastructure/config-manager/_mcp/server.

# Spectrum-X Overlay Tenant Change

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](/switch-infrastructure/config-manager/user-guides/spectrum-x-overlay-lifecycle/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.

| Field          | Description                                                                                                                                                                               | Required |
| :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| **Site**       | The site the overlay and device belong to.                                                                                                                                                | Yes      |
| **Overlay ID** | The overlay to apply to the selected ports. Leave blank to remove their current Spectrum-X assignment without creating a replacement.                                                     | No       |
| **Device**     | The target device.                                                                                                                                                                        | Yes      |
| **Ports**      | One 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](/switch-infrastructure/config-manager/user-guides/spectrum-x-overlay-lifecycle/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](/switch-infrastructure/config-manager/services/render/overview) 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](/switch-infrastructure/config-manager/user-guides/configuration-deploy/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](/switch-infrastructure/config-manager/user-guides/spectrum-x-overlay-lifecycle/spectrum-x-overlay-creation) if the overlay does not exist; reconcile duplicates in Nautobot if it does.

## Related guides

* [Spectrum-X Overlay Creation](/switch-infrastructure/config-manager/user-guides/spectrum-x-overlay-lifecycle/spectrum-x-overlay-creation) — provision the VRF, VXLAN, and Overlay metadata before assigning it.
* [Spectrum-X Overlay Assignment](/switch-infrastructure/config-manager/user-guides/spectrum-x-overlay-lifecycle/spectrum-x-overlay-assignment) — the assignment child workflow this orchestration invokes.
* [Spectrum-X Overlay Deletion](/switch-infrastructure/config-manager/user-guides/spectrum-x-overlay-lifecycle/spectrum-x-overlay-deletion) — counterpart deletion lifecycle.
* [Render Service](/switch-infrastructure/config-manager/services/render/overview) — produces the tenant configurations this workflow waits on.
* [Configuration Deploy](/switch-infrastructure/config-manager/user-guides/configuration-deploy/configuration-deploy) — alternative path when a change is too broad for tenant deploy.