User GuidesConfiguration & Deploy

Tenant Deploy

View as Markdown

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.

Experimental

This workflow is experimental and not intended for general use. Use it only in test or pilot environments.

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.
FieldDescriptionRequired
SiteThe site of the target device. Drives the device list below.Yes
TenantOptional Nautobot tenant filter to narrow the device list.No
StatusOptional device-status filter to narrow the device list.No
DeviceThe target device. The list is filtered by the selections above.Yes

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.