> 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 full documentation content, see https://docs.nvidia.com/switch-infrastructure/config-manager/llms-full.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.

# SpX Overlay Tenant Change

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](/switch-infrastructure/config-manager/user-guides/sp-x-overlay-lifecycle/sp-x-overlay-assignment), [Render Service](/switch-infrastructure/config-manager/services/render/overview), and [Tenant Deploy](/switch-infrastructure/config-manager/user-guides/configuration-deploy/tenant-deploy) workflows are exposed individually for advanced cases but are normally orchestrated by this workflow.

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

| Field                            | Description                                                                                                            | Required |
| :------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | :------- |
| **Site**                         | The site the overlay and device belong to.                                                                             | Yes      |
| **Overlay ID**                   | The overlay to apply to the device.                                                                                    | Yes      |
| **Device**                       | The 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      |
| **Namespace**                    | Tag 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](/switch-infrastructure/config-manager/user-guides/sp-x-overlay-lifecycle/sp-x-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](/switch-infrastructure/config-manager/user-guides/configuration-deploy/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](/switch-infrastructure/config-manager/services/render/overview) 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](/switch-infrastructure/config-manager/user-guides/configuration-deploy/tenant-deploy#diff-validation-rules). 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 [SpX Overlay Creation](/switch-infrastructure/config-manager/user-guides/sp-x-overlay-lifecycle/sp-x-overlay-creation) if the overlay does not exist; reconcile duplicates in Nautobot if it does.

## Related guides

* [SpX Overlay Creation](/switch-infrastructure/config-manager/user-guides/sp-x-overlay-lifecycle/sp-x-overlay-creation) — provision the VRF, VXLAN, and Overlay metadata before assigning it.
* [SpX Overlay Assignment](/switch-infrastructure/config-manager/user-guides/sp-x-overlay-lifecycle/sp-x-overlay-assignment) — the assignment child workflow this orchestration invokes.
* [SpX Overlay Deletion](/switch-infrastructure/config-manager/user-guides/sp-x-overlay-lifecycle/sp-x-overlay-deletion) — counterpart deletion lifecycle.
* [Tenant Deploy](/switch-infrastructure/config-manager/user-guides/configuration-deploy/tenant-deploy) — the tenant-scoped deploy child this orchestration ends with.
* [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.