Multi-Device Deploy
Multi-Device Deploy
Multi-Device Deploy
The Multi-Deploy workflow rolls a configuration change out across every device that matches a given role, grouping devices by the shape of their pending diff so that operators approve each unique change only once. It is the standard tool for fabric-wide updates — for example, pushing a new BGP policy, NTP server, or AAA stanza across all spine switches in a site.
Each batch still requires a human approver to review the shared diff before any device is touched. For changes to a single device, use Configuration Deploy instead.
Before running Multi-Deploy, confirm the following are in place:
deploy_enabled=True, so any switch marked deploy-disabled (commonly Kubernetes-attached management switches on shared-network deployments) is automatically excluded. See Hosting Options for why this matters.The workflow form accepts the following inputs:
After submission, a status page appears showing the four parent-workflow stages. Once the workflow reaches the execute_batches stage, it spawns one child Batch Deploy per batch — each with its own approval gate that must be cleared before any device is reconfigured.
The parent workflow runs four stages in order. None of the parent stages require manual approval; the approval gates are inside the child batch workflows.
discover_devices — Query Nautobot for in-scope devices.
Calls Nautobot with the supplied role, location, status, and tenant filters, and deploy_enabled=True. The stage display reports how many devices were discovered. If no devices match, the workflow exits early with "No devices found with role '<role>'" and no further stages run.
collect_diffs — Generate a candidate diff for every device.
For each discovered device, in parallel, the workflow loads the device’s intended configuration (with its own commit SHA) from the Config Store and runs a candidate diff against the device’s live configuration. Devices with no diff are dropped from later stages. Devices that error out during diff collection (unreachable, render failure, syntax error) are recorded in discovery_failures and reported in the final result but do not stop the workflow. If no device has changes to apply, the workflow exits with "No devices have configuration changes to deploy".
group_and_batch — Group by shared diff and slice into batches.
Devices with byte-identical diff content are grouped together (see Diff grouping and batching below). Each group is then split into batches no larger than max_batch_size. The stage display reports the number of diff groups, the number of batches, and how each group breaks down.
execute_batches — Spawn a child batch workflow per batch.
For each batch, the parent starts a child Batch Deploy and posts a clickable link to it on the stage display. The parent stage stays running and updates the display as each child completes (succeeded, failed, or rejected). The approval gate for each batch lives inside its child workflow — open the child link to review the diff and approve or reject.
The parent workflow is complete only after every child batch workflow terminates. The final result aggregates total successes, failures, and rejections across all batches.
The point of Multi-Deploy is that a fabric-wide change usually produces the same diff on most devices, and operators should not have to approve the same diff dozens of times.
The group_and_batch stage builds groups using the following rule:
DiffGroup. They will share a single approval gate inside their child workflow.If a diff group is larger than max_batch_size, the group is split into multiple batches. Every batch in a split group still shows the same diff content; the split exists purely to limit blast radius per approval.
A run that targets 30 spine switches with max_batch_size=10 might produce:
That is 30 devices, 3 diff groups, and 5 child batch workflows — meaning 5 approval gates total, each reviewing one of the three unique diffs.
Confirm the run succeeded by checking all of the following:
total_devices, successful_devices, failed_devices, and rejected_devices.execute_batches display reached a terminal state. Click each batch link to confirm the per-batch outcome (approved + applied, approved with some device failures, or rejected).discovery_failures with the error string — typically unreachable devices, missing intended configs, or render failures. Address these separately and re-run the workflow.perform_backups stage triggers a Configuration Backup per device as a child workflow; failures there mean the device is configured but no fresh backup was captured.rejected_devices and never had configuration applied. Re-run a smaller scope once the underlying objection is resolved.No devices found with role ‘<role>’.
Discovery returned zero devices. Confirm the role name in Nautobot exactly matches what you submitted (it is case-sensitive), and that the location/status/tenant filters are not too narrow. Devices marked deploy-disabled are excluded by design — check the Config Manager Info tab in Nautobot if you expected a specific switch to appear.
No devices have configuration changes to deploy.
Every targeted device’s running configuration already matches its intended configuration. This is a successful no-op. If you expected a change, confirm the render service produced a new intended config (the Render Service is triggered by Nautobot change events or template version bumps) and that the new config landed in the Config Store.
A diff group has split into more batches than expected.
max_batch_size is the only knob that splits a group. Increase it if you want fewer approvals; decrease it if you want tighter blast-radius control. Splitting does not change the diff being approved — every batch in a group shows the same diff.
A batch is stuck on “Waiting for approval”.
The child workflow is waiting on a human at its review_shared_diff stage. Click the batch link from the parent’s execute_batches display, review the diff, and approve or reject. The parent stage stays running and updates its display each time a child completes.
Some devices in a batch failed to apply but others succeeded.
The apply_configurations stage runs all device applies in parallel and reports successes and failures independently. Failed devices appear in the batch’s failed_devices map with the underlying error. Investigate the per-device error (commonly an NVUE syntax exception, a connectivity issue, or a non-retryable DiffChangedException if the device’s running config changed mid-run) and re-run Multi-Deploy with a narrower scope once resolved.
A DiffChangedException is reported for a device.
The device’s running configuration changed between diff collection and apply, so the diff the approver reviewed is no longer accurate. The activity does not retry — this is intentional. Re-run Multi-Deploy and a fresh diff will be collected and re-approved.