Parent folderOpen Confluence

RWS Architecture article

ADR-002 NX-OS configuration replace for DC 3.0 deployments

DC 3.0 requires deterministic, auditable network configuration delivery across a large fabric. Incremental changes are hard to validate end-to-end and allow drift to accumulate ove

  1. Typeadr
  2. Statusaccepted
  3. Domainnetwork
On this page
  1. Context and Problem Statement
  2. Decision Drivers
  3. Considered Options
  4. Decision Outcome
  5. Positive Consequences
  6. Negative Consequences
  7. Pros and Cons of the Options
  8. Option 1 – NX-OS configure replace (chosen)
  9. Option 2 – Incremental changes
  10. Option 3 – Targeted template push
  11. Option 4 – Manual CLI changes
  12. Links and References

Context and Problem Statement

DC 3.0 requires deterministic, auditable network configuration delivery across a large fabric. Incremental changes are hard to validate end-to-end and allow drift to accumulate over time. We need a deployment mechanism that applies the complete intended configuration as a single unit and supports rollback if validation fails.

Decision Drivers

  • Full, deterministic deployment from netbox-derived source data so the rendered config is the complete intent.
  • Eliminate configuration drift by replacing the entire device config rather than patching sections.
  • Support rollback with bounded blast radius via native timeout semantics.
  • Ensure repeatable, auditable change delivery with a single change boundary per device.
  • Align with platform automation and validation tooling that expects full-intent artifacts.

Considered Options

  1. NX-OS configure replace to apply a full configuration file in one operation.
  2. Incremental changes (Ansible or API patching) applied by diffing and updating sections.
  3. Template-based push of targeted sections without full replacement.
  4. Manual CLI changes without a generated full configuration.

Decision Outcome

Chosen option: NX-OS configure replace for all DC 3.0 device deployments.

This approach aligns with deterministic generation, provides atomic replace semantics, and enables rollback with a defined timeout. It avoids long-lived drift and preserves a single source of truth. Vendor documentation confirms the replace workflow and rollback behavior as supported operational patterns for NX-OS.

Positive Consequences

  • Ensures the running configuration matches the generated intent.
  • Reduces drift and eliminates partial updates.
  • Supports rollback using native NX-OS mechanisms.
  • Simplifies audit trails: a single replace operation per change.

Negative Consequences

  • Requires complete configuration generation for every change.
  • Demands strong prechecks and validation to avoid outages.
  • Requires a staging location for the configuration file.

Pros and Cons of the Options

Option 1 – NX-OS configure replace (chosen)

  • Good: Deterministic full replace with rollback support.
  • Good: Clear, auditable change boundary tied to a single artifact.
  • Good: Built-in rollback timeout enables safe validation windows.
  • Bad: Requires full config generation and pre-validation for every change.

Option 2 – Incremental changes

  • Good: Small changes can be applied quickly.
  • Bad: Drift accumulates when data is incomplete or updates are skipped.
  • Bad: Partial updates complicate auditing because intent is distributed across diffs.

Option 3 – Targeted template push

  • Good: Faster delivery for scoped changes.
  • Bad: Diverges from full-intent deployments and weakens auditability.
  • Bad: Hard to guarantee completeness when source data is partial.

Option 4 – Manual CLI changes

  • Good: Immediate fixes in emergencies.
  • Bad: Untracked drift and no repeatable source of truth.
  • Bad: Manual steps are not scalable or auditable across the fabric.

Links and References