How to Permanently Decommission a Leaf Switch in Cisco ACI Fabric: A Complete Guide for Network Engineers

 ACI leaf switch is more than simply unplugging cables and removing the hardware. The switch can be referenced throughout the fabric by policies, vPC configurations, management settings, and routing components. If these dependencies are not removed correctly, the fabric may continue to generate faults and warnings long after the switch has been taken out of service.

This guide walks through a clean and permanent method for removing a leaf switch from an ACI fabric while ensuring the environment remains stable and fault-free.

When Would You Need to Decommission a Leaf Switch?

Network engineers commonly decommission leaf switches during:

• Hardware refresh projects
• Data center migrations
• Fabric redesign initiatives
• Capacity optimization exercises
• RMA and hardware replacement activities
• Retirement of unused infrastructure

No matter the reason, following a structured process helps prevent operational issues later.

Why Proper Decommissioning Matters

Before removing a leaf switch, it is important to understand that the node may still be referenced by:

• vPC configurations
• Endpoint Group (EPG) static bindings
• L3Out configurations
• Interface policies
• Management connectivity settings
• Maintenance groups and policy groups

Leaving these references behind can generate faults and impact fabric health even after the physical switch has been disconnected.

Step 1: Remove vPC Dependencies

If the leaf switch is part of a vPC pair, begin by removing the explicit vPC protection group associated with the node.

This is one of the most frequently missed steps during decommissioning. If the vPC relationship remains configured, the surviving peer may continue looking for its partner and generate unnecessary faults within the fabric.

Always verify that all vPC references have been removed before proceeding.

Step 2: Remove All References to the Leaf Switch

Before decommissioning the node, review the fabric and remove every configuration object that references the switch.

Static Path Bindings

Check all Endpoint Groups (EPGs) and remove any static path bindings associated with the leaf switch.

L3Out Configuration

Review:

• Node Profiles
• Interface Profiles

Remove any references to the target node.

Interface Policies

Validate and clean up:

• Interface Selectors
• Interface Profiles
• Leaf Switch Profiles

Management Configuration

Verify and remove:

• Out-of-Band (OOB) Management Addresses
• In-Band (INB) Management Addresses

Policy Group Membership

Ensure the node is removed from:

• Leaf Policy Groups
• Maintenance Groups
• Operational Groups

Cleaning these dependencies beforehand helps ensure a smooth removal process and reduces troubleshooting efforts afterward.

Step 3: Decommission the Node from APIC

After confirming that all dependencies have been removed, navigate to:

Fabric → Inventory → Fabric Membership

Select the leaf switch you want to retire and choose the Decommission option.

When prompted, select:

Remove from Controller

This is the permanent decommission option.

When selected, APIC removes:

• Node ID association
• Serial number registration
• Fabric membership information

After the process completes, the switch is no longer considered an active member of the ACI fabric.

Step 4: Verify Successful Removal

Allow a few minutes for APIC convergence and database updates.

Once convergence is complete, verify the following:

• The node no longer appears in Fabric Membership
• The serial number has been removed from APIC inventory
• No active faults are associated with the node
• No policies reference the decommissioned switch

This validation step provides confidence that the node has been successfully removed from the fabric.

Step 5: Clean the Switch Configuration

Although the switch has been removed from APIC, the physical device may still retain its ACI identity.

Connect to the switch console and run:

setup-clean-config.sh

After the cleanup process completes, reload the switch:

reload

This removes residual ACI configuration and fabric identity information from the hardware.

Performing this cleanup is highly recommended if the switch will be:

• Added to another ACI fabric
• Used in a lab environment
• Returned to inventory
• Repurposed for another project

Step 6: Physically Disconnect the Switch

The final step is to remove all physical connections.

Disconnect:

• Uplinks
• Downlinks
• Management cables
• Power connections (when approved by local procedures)

Physical removal should always occur after the logical decommissioning process is fully completed.

Many engineers make the mistake of disconnecting the switch first, which can complicate troubleshooting and validation activities.

A good rule to remember is:

"Logically remove first, physically remove last."

Common Mistakes to Avoid

Skipping vPC Cleanup

This can cause vPC-related faults on the peer switch.

Forgetting Static Path Bindings

Orphaned EPG configurations can remain in the fabric.

Leaving L3Out References Behind

Routing policies referencing decommissioned nodes can cause operational issues.

Not Selecting "Remove from Controller"

The switch may continue to appear in the fabric inventory.

Skipping Switch Cleanup

The device may retain old fabric identity information and create issues when reused.

Disconnecting Cables Too Early

This makes verification and troubleshooting more difficult.

Best Practice Checklist

Before retiring a Cisco ACI leaf switch, confirm the following:

✅ vPC protection groups removed

✅ Static path bindings cleaned

✅ L3Out references removed

✅ Interface profiles cleaned

✅ OOB and INB management addresses removed

✅ Policy groups updated

✅ Node decommissioned from APIC

✅ Serial number removed from Fabric Membership

✅ Switch cleaned using setup-clean-config.sh

✅ Physical cables disconnected last

Conclusion

A clean Cisco ACI leaf switch decommission requires more than simply removing hardware from the rack. By systematically removing policy references, cleaning vPC dependencies, decommissioning the node from APIC, clearing the switch configuration, and finally disconnecting physical cabling, you can avoid unnecessary faults and maintain a healthy fabric.

Following this approach will help network engineers perform leaf switch retirements confidently while ensuring operational consistency across the data center environment.

Related Networking Articles

Continue learning Cisco ACI and Data Center Networking concepts through Netterrene:

• https://netterrene.blogspot.com/
• https://netterrene.blogspot.com/search/label/Cisco%20ACI
• https://netterrene.blogspot.com/search/label/Data%20Center
• https://netterrene.blogspot.com/search/label/Cisco
• https://netterrene.blogspot.com/search/label/Networking

For more Cisco ACI troubleshooting guides, best practices, and real-world operational lessons, visit:

https://netterrene.blogspot.com/

Cisco ACI MoQuery – Advanced Commands for Day‑to‑Day Operations

Cisco ACI provides a powerful graphical interface through APIC, but experienced ACI engineers rarely rely only on the GUI during daily operations. In real production environments, engineers prefer moquery because it offers fast, accurate, and read‑only access to the Cisco ACI Management Information Tree (MIT).

Moquery is safe to use in production, does not impact traffic, and does not program hardware. It exposes the real‑time state of the fabric and eliminates guesswork during troubleshooting. For day‑to‑day ACI operations, moquery is often the first tool engineers reach for.

---

What Is MoQuery in Cisco ACI?

Moquery is a command‑line utility available directly on the APIC that allows engineers to query managed objects (MOs) stored in the ACI database. Unlike the APIC GUI, moquery does not hide relationships or simplify outputs. It shows raw and authoritative information exactly as it exists in the fabric.

Moquery is commonly used for:

• Endpoint troubleshooting
• Contract and policy validation
• VRF and bridge domain verification
• Fault analysis
• Fabric and node health checks

---

Endpoint Troubleshooting Using MoQuery

Endpoint‑related issues are the most common problems in Cisco ACI environments. When endpoints are not reachable or behave unexpectedly, moquery provides immediate visibility.

To display all learned endpoints:

moquery -c fvCEp

This command shows:

• MAC address
• IP address
• EPG association
• Bridge Domain
• Leaf and interface where the endpoint is learned

To find a specific IP address:

moquery -c fvCEp | grep 10.10.10.25

To find a specific MAC address:

moquery -c fvCEp | grep 00:50:56

These commands are used daily to identify incorrect endpoint learning, endpoint mobility events, duplicate IPs, and static path misconfigurations.

---

Validating Application Profiles and EPGs

To list all Endpoint Groups (EPGs) in a tenant:

moquery -c fvAEPg

This command is helpful when:

• EPGs do not appear in the GUI
• Verifying naming conventions
• Confirming EPG existence during migrations

To identify which application profile an EPG belongs to:

moquery -c fvAEPg | grep dn

This is especially useful in environments with many application profiles and similarly named EPGs.

---

Contract Troubleshooting Using MoQuery

Contracts are one of the most frequent causes of traffic drops in Cisco ACI. Moquery allows engineers to validate contract relationships without relying on GUI assumptions.

To list all contracts:

moquery -c vzBrCP

To check which EPGs are providers of a contract:

moquery -c fvRsProv

To check which EPGs are consumers of a contract:

moquery -c fvRsCons

These commands confirm whether the correct EPGs are actually providing and consuming the intended contracts.

---

Validating Contract Subjects and Filters

Many contract issues occur not because the contract is missing, but because the filter is wrong.

To inspect contract subjects:

moquery -c vzSubj

To list filters:

moquery -c vzFilter

To validate filter entries (ports, protocol, and direction):

moquery -c vzEntry

These commands remove ambiguity and clearly show whether the contract allows the required traffic.

---

Taboo Contract Verification

Taboo Contracts explicitly deny traffic and override permit contracts. They should be used sparingly, as misconfiguration can cause outages.

To list all Taboo Contracts:

moquery -c vzTaboo

To inspect Taboo contract subjects:

moquery -c vzTSubj

If traffic is unexpectedly denied, these commands should always be checked early in troubleshooting.

---

Validating vzAny and VRF‑Level Policies

vzAny represents all EPGs within a single VRF and is commonly used for shared services or broad policy application.

To list all VRFs:

moquery -c fvCtx

To confirm vzAny configuration:

moquery -c vzAny

This is critical in environments using:

• Shared‑services architectures
• Permit‑all designs
• Contract Preferred Groups

Many production incidents occur because engineers are unaware of an existing vzAny contract.

---

Bridge Domain Troubleshooting

Bridge Domain issues can silently break connectivity.

To list all bridge domains:

moquery -c fvBD

To display bridge domain subnets:

moquery -c fvSubnet

To validate Bridge Domain to VRF mapping:

moquery -c fvRsCtx

These commands help identify:

• Missing gateways
• Incorrect VRF bindings
• Wrong subnet scope

---

L3Out and External Connectivity Validation

To list all Layer‑3 Outs:

moquery -c l3extOut

To view external EPGs:

moquery -c l3extInstP

To check external subnets:

moquery -c l3extSubnet

These are essential when troubleshooting:

• North‑south traffic issues
• Firewall integration
• Route advertisement problems

---

Fault and Fabric Health Troubleshooting

To display all active faults:

moquery -c faultInst

To see only critical faults:

moquery -c faultInst | grep critical

To find operational faults:

moquery -c faultInst | grep oper

These commands are faster and often more actionable than navigating the APIC fault dashboard.

---

Fabric and Node Health Validation

To list all fabric nodes:

moquery -c fabricNode

To check fabric health scores:

moquery -c fabricHealth

These commands are commonly used before and after production changes to ensure stability.

---

Interface and Path Troubleshooting

To list physical interfaces:

moquery -c ethpmPhysIf

To check interface operational state:

moquery -c ethpmPhysIf | grep operSt

To validate static path bindings:

moquery -c fvRsPathAtt

These commands explain many partial connectivity issues, link‑state problems, and unexpected traffic drops.

---

Best Practices for Daily MoQuery Usage

• Use moquery during incidents, not after
• Save outputs for RCA and audits
• Combine moquery with grep for faster analysis
• Learn common managed object classes such as fvCEp, fvAEPg, fvBD, fvCtx, and faultInst

---

Why Every ACI Engineer Should Master MoQuery

Moquery significantly reduces MTTR, increases confidence during incidents, and exposes the actual state of the fabric. Engineers who master moquery troubleshoot faster, avoid mistakes, and operate more effectively in large ACI environments.

---

Conclusion

Moquery is one of the most powerful yet underutilized tools in Cisco ACI. While the APIC GUI is excellent for visualization, moquery provides the facts. For serious ACI operations, moquery should be part of every engineer’s daily workflow.