Tenant Deploy

The Tenant Deploy workflow applies a tenant-scoped configuration change to a single device without a human approval gate. Instead of asking an operator to review the diff, the workflow runs a regex-based allow/deny check on the diff content and only applies the change if it stays within the tenant-permitted set of operations. It is the workflow used by automated, tenant-driven flows (most commonly VPC Tenant Change) to converge a device after a tenant or VPC change in Nautobot.

For operator-driven, single-device changes, use Configuration Deploy instead.

Prerequisites

Before running Tenant Deploy (or before a parent workflow invokes it), confirm the following are in place:

• Device exists in Nautobot with a current intended tenant configuration in the Config Store. The intended config is produced by the tenant-scoped render path of the Render Service.
• Device is reachable from Config Manager on its management address and credentials are present in the secrets store.
• Diff is bounded to allowed operations. Tenant Deploy will refuse to apply diffs that touch the device’s underlay or default VRF — see Diff validation rules below. If the change you need falls outside the allowed set, route it through Configuration Deploy so a human can review it.

Running the workflow

This workflow is typically invoked as a child of another workflow (e.g. VPC Tenant Change) rather than started directly. When started directly:

1. Navigate to the Config Manager URL for your environment.
2. Click the + in the top right and select TenantDeployWorkflow.
3. Fill in the form using the field reference below and submit.

After submission, a status page appears showing the five stages.

Diff validation rules

The validate_configuration_diff stage replaces the human approval gate. It enforces the rules below against the candidate diff:

Allowed nv set / nv unset patterns:

• nv (set|unset) interface ... bridge domain ... and related VXLAN attachments under nve vxlan
• nv (set|unset) evpn ...
• nv (set|unset) interface ... ip vrf ...
• nv (set|unset) vrf <tenant-vrf> evpn ...
• nv (set|unset) vrf <tenant-vrf> router ...

Explicitly disallowed patterns (validation fails immediately, before any device-side change):

• nv (set|unset) vrf default ... — the default VRF is underlay-scoped and must not be touched by a tenant deploy.

If the diff contains anything outside the allowed list, the stage raises StageRuntimeFailure and the workflow halts before apply_configuration runs.

Execution stages

The workflow runs five stages in order. None require human approval — the third stage performs automated validation in lieu of an operator gate.

1. load_tenant_configuration — Load the tenant intended config from the Config Store.

   Pulls the tenant-scoped intended configuration plus its commit SHA for the device.

2. perform_configuration_diff — Compute the diff vs the device’s running config.

   Generates a candidate diff. If the diff is empty, the workflow exits successfully without applying anything. Otherwise the diff text is passed to validation.

3. validate_configuration_diff — Apply the allow/deny regex rules.

   Runs the rules in Diff validation rules. Pass → continue to apply. Fail → raise StageRuntimeFailure and halt; no change is applied.

4. apply_configuration — Apply the validated diff to the device.

   Pushes the configuration through apply_approved_configuration with partial=True (NVUE partial commit), so only the tenant-scoped sections are touched. The same non-retryable error set as Configuration Deploy applies — ConfigSyntaxException, ConfigApplyFailureException, DiffChangedException.

5. perform_backup — Capture a fresh backup.

   Starts the Configuration Backup workflow as a child workflow with trigger=WORKFLOW and the just-applied commit SHA.

Verifying outcomes

After the workflow reports success, confirm:

• All five stages green on the Config Manager run page (or the workflow exited at perform_configuration_diff if the diff was empty).
• Device running configuration matches the tenant intended configuration for the relevant tenant. Re-run; if the diff stage reports empty, the device is converged for the tenant scope.
• A fresh backup exists in the Config Store, tagged with the commit SHA the workflow used.

Common issues

validate_configuration_diff raises StageRuntimeFailure.

The candidate diff contains operations outside the tenant-allowed set — most commonly because the underlying template change is touching the underlay or the default VRF. Re-run the change through Configuration Deploy so a human reviews and approves it, or restructure the change so the tenant-scoped diff is the only thing produced.

DiffChangedException at apply.

The device’s running configuration changed between diff and apply. Re-run the parent workflow (typically VPC Tenant Change); it will compute a fresh diff and revalidate.

ConfigSyntaxException at apply.

The rendered tenant configuration is malformed for this device. Fix the upstream template or Nautobot data, re-render via the Render Service, and re-run.

Diff is non-empty but only contains allowed operations, and the workflow still failed.

The validator is strict about the exact nv set / nv unset shape — keyword order, vrf naming, and indentation matter. Inspect the diff on the stage page and compare against the allow patterns in Diff validation rules. If a legitimate tenant change is being blocked by an over-narrow rule, that is a platform-engineering ticket; route the change through Configuration Deploy as a workaround.

Related guides

• Configuration Deploy — single-device deploy with a human approval gate.
• VPC Tenant Change — primary parent workflow that invokes Tenant Deploy.
• VPC Assignment — sibling tenant-scoped workflow.
• Configuration Backup — child workflow triggered after a successful apply.
• Render Service — produces the tenant intended configurations.