> 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 Assignment

The Spectrum-X Overlay Assignment workflow changes the Spectrum-X assignment on a specific set of device ports. With a target Overlay ID, it binds that overlay's VRF to the device and ports. Without a target Overlay ID, it removes the selected ports' existing Spectrum-X assignment without creating a replacement. It updates Nautobot's IPAM intent and matching `OverlayAssignment` entries in the overlays plugin 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 Spectrum-X Overlay lifecycle, after [Spectrum-X Overlay Creation](/switch-infrastructure/config-manager/user-guides/spectrum-x-overlay-lifecycle/spectrum-x-overlay-creation) provisions the VRF and Overlay objects.

For the end-to-end assign + render + deploy lifecycle, use [Spectrum-X Overlay Tenant Change](/switch-infrastructure/config-manager/user-guides/spectrum-x-overlay-lifecycle/spectrum-x-overlay-tenant-change) — it calls this workflow as a child plus the render and deploy steps.

## Prerequisites

Before running, confirm:

* **For assignment or moves, the target 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. This is not required for removal-only changes.
* **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

Spectrum-X Overlay Assignment is not exposed in the Config Manager UI today. It is invoked as a child of [Spectrum-X Overlay Tenant Change](/switch-infrastructure/config-manager/user-guides/spectrum-x-overlay-lifecycle/spectrum-x-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. When an Overlay ID is supplied, it queries Nautobot for the matching VRF and requires exactly one result. For removal-only changes, it skips the target-VRF lookup.

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

   Attaches the target VRF to the device's VRF list in Nautobot. If the VRF is already assigned, the stage reports `vrf_assigned=False`. Removal-only changes skip this step.

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

   For each port in `port_names`, sets the target VRF or clears the VRF for a removal-only change, running all per-port writes in parallel. It reconciles the overlays plugin so interface assignments match the new Spectrum-X intent while preserving assignments for other overlay types. When no interface on the device remains mapped to an old VRF or Spectrum-X overlay, the corresponding device-level association is deleted. The result separates changed ports into `assigned_ports` and `unassigned_ports`, reports cleaned-up device VRFs in `removed_vrf_ids`, and exposes plugin mutations through `overlay_assignments_created` and `overlay_assignments_removed`.

## Verifying outcomes

After the workflow reports success, confirm:

* **All three stages green** on the Config Manager run page.
* **Run a deploy** to push the resulting intended-config change to the device. The simplest path is [Spectrum-X Overlay Tenant Change](/switch-infrastructure/config-manager/user-guides/spectrum-x-overlay-lifecycle/spectrum-x-overlay-tenant-change), which combines assignment with the subsequent re-render and deploy.

For assignment runs, also confirm:

* **Result shape** — `assigned_ports` lists the interfaces changed, `vrf_assigned=true` means the target device-level binding was new, and `overlay_assignments_created` and `overlay_assignments_removed` reflect plugin reconciliation.
* **Nautobot** shows the target VRF on the device and on each named interface.
* **Nautobot overlays plugin** shows `OverlayAssignment` entries for the device and each named interface under the target overlay.

For removal-only runs, instead confirm:

* **Result shape** — `unassigned_ports` lists the interfaces changed, `vrf` is `null`, `removed_vrf_ids` lists unused device/VRF associations cleaned up, and the overlay-assignment counts reflect plugin reconciliation.
* **Nautobot** shows no VRF association on any selected interface and no device/VRF association when no other device interface uses that VRF.
* **Nautobot overlays plugin** shows no Spectrum-X `OverlayAssignment` on any selected interface and no device-level assignment when no other interface uses that overlay.

## Common issues

**`get_device_and_vrf` raises `ApplicationError` "0 VRFs found".**

The overlay has not been created yet at this site. Run [Spectrum-X Overlay Creation](/switch-infrastructure/config-manager/user-guides/spectrum-x-overlay-lifecycle/spectrum-x-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.

## Related guides

* [Spectrum-X Overlay Creation](/switch-infrastructure/config-manager/user-guides/spectrum-x-overlay-lifecycle/spectrum-x-overlay-creation) — provision the VRF and Overlay metadata.
* [Spectrum-X Overlay Tenant Change](/switch-infrastructure/config-manager/user-guides/spectrum-x-overlay-lifecycle/spectrum-x-overlay-tenant-change) — assignment + render + deploy in one workflow.
* [Spectrum-X Overlay Deletion](/switch-infrastructure/config-manager/user-guides/spectrum-x-overlay-lifecycle/spectrum-x-overlay-deletion) — tear down an overlay (only after VRFs are unassigned).