Cisco APIC Installation and ACI Upgrade and Downgrade Guide

PDF

Cisco APIC Installation and ACI Upgrade and Downgrade Guide

Best practice for downgrade checklists and procedures

Updated: July 12, 2026

Want to summarize with AI?

Log in

Outlines the checklist items to review before downgrading to older versions and specific procedures for downgrades from Cisco APIC 6.2(1) or later.

In general, apply the same checklists used for upgrades when you downgrade to an older version. Also, check whether new hardware or software features are supported on older versions. If you use such features, disable or change the configurations before downgrading. Otherwise, some features may stop working after you downgrade to an older version. This applies to all releases.

Feature compatibility review

Here are some example features to review before downgrading. This list is not comprehensive; check the Release Notes or Configuration Guides to confirm that your features are supported on older releases.

  • The ability to use the DUO application as an authentication method when logging in to Cisco Application Policy Infrastructure Controller (APIC) was introduced as part of the Cisco APIC release 5.0(1). If you are running release 5.0(1) and you have DUO set up as your default authentication method, but then you decide to downgrade from release 5.0(1) to a previous release where DUO was not supported as an authentication method, we recommend that you change the default authentication method from DUO to an option that was available prior to release 5.0(1), such as Local, LDAP, RADIUS, and so on. If you do not change the default authentication method before downgrading in this situation, you will have to log in using the fallback option after the downgrade, then you will have to change the authentication method to an option that was available prior to release 5.0(1) at that point.

    Navigate to Admin > AAA > Authentication, then change the setting in the Realm field in the Default Authentication area of the page to change the default authentication method before downgrading your system. You will also have to manually delete the DUO login domain after the downgrade.

  • Starting with release 4.2(6) release, SNMPv3 supports the Secure Hash Algorithm-2 (SHA-2) authentication type. If you are running on Cisco APIC release 4.2(6) or later and you are using the SHA-2 authentication type, and then downgrade from Cisco APIC release 4.2(6) to a previous release, the downgrade will be blocked with the following error message:

    SHA-2authentication type is not supported.

    You can choose to either change the authentication type to MD5 or delete the corresponding SNMPv3 users to continue.

  • Changing the container bridge IP address on Cisco APIC is supported only on Cisco APIC release 4.2(1) or later. If the container bridge IP address on Cisco APIC for AppCenter is configured with a non-default IP address, change it back the default 172.17.0.1/16 prior to downgrading to the older versions than 4.2(1).

  • A static route (MO:mgmtStaticRoute) for Inband and/or Out-of-band EPG under Tenants > mgmt > Node Management EPGs is supported only on Cisco APIC release 5.1 or later. Delete this configuration and ensure the required service is still reachable via other means prior to the downgrade.

  • Newly added microsegment EPG configurations must be removed before downgrading to a software release that does not support it.

  • Downgrading the fabric starting with the leaf switch will cause faults such as policy-deployment-failed with fault code F1371.

  • If you must downgrade the firmware from a release that supports FIPS to a release that does not support FIPS, you must first disable FIPS on the Cisco ACI fabric and reload all the switches in the fabric for the FIPS configuration change.

  • If you have Anycast services configured in your Cisco ACI fabric, you must disable the Anycast gateway feature and stop Anycast services on external devices before downgrading from Cisco APIC 3.2(x) to an earlier release.

  • CiscoN9K-C9508-FM-E2 fabric modules must be physically removed before downgrading to releases earlier than Cisco APIC 3.0(1). The same applies to any new modules for their respective supported version.

  • If you are downgrading from Cisco APIC release 4.0(1) or later to release 3.2(x) or earlier, you may encounter a minor traffic drop in the fabric due to a difference in QoS classes supported between the releases. For more information, see CSCwa32037.

  • If you have remote leaf switches deployed, and you downgrade the Cisco APIC software from release 3.1(1) or later to an earlier release that does not support the remote leaf switches feature, you must decommission the nodes before downgrading. For information about prerequisites to downgrading Remote Leaf switches, see the Remote Leaf Switches chapter in the Cisco APIC Layer 3 Networking Configuration Guide.

  • If the following conditions are met:

    • You are running the 5.2(4) release and the Cisco APIC created one or more system-generated policies.

    • You downgrade the Cisco APIC from the 5.2(4) release, then later upgrade back to the 5.2(4) release.

    Then, one of the following behaviors will occur:

    • If the Cisco APIC finds a policy with the same name and parameters as a system-generated policy that it is trying to create, then the Cisco APIC will take ownership of the policy and you cannot modify the policy. This occurs if you did not modify the policy after downgrading from the 5.2(4) release.

    • If the Cisco APIC finds a policy with the same name as a system-generated policy that the Cisco APIC is trying to create, but the parameters are different, then the Cisco APIC will consider the policy to be a custom policy and you can modify the policy. This occurs if you modified the policy after downgrading from the 5.2(4) release.

    Because of this behavior, you should not modify the system-generated policies after you downgrade from the 5.2(4) release.

  • If you are downgrading from a Cisco APIC release that supports the Transport Layer Security (TLS) version 1.3, you enabled TLS 1.3 in a management access policy, and the target Cisco APIC release does not support TLS 1.3, then you must disable TLS 1.3 and instead enable TLS 1.2.

  • You must decommission an unsupported leaf switch that is connected to the Cisco APIC and move the cables to the other leaf switch that is part of the fabric before you downgrade the image.

  • In the Cisco APIC 6.0(2) release or later, if the cluster's discovery mode is set to "strict" and you want to downgrade to any 4.2 release or earlier, you must first change the discovery mode "permissive."

  • The APIC-M4/L4 server is supported in the Cisco APIC 6.0(2) release and later and 5.3(1) release and later. However, if you downgrade from the 6.0(2) or 6.0(3) release to a 5.3 release, you see a pre-upgrade validation warning that the APIC-M4/L4 server is not supported. In this case, you can ignore the warning.

    The following screenshot shows an example of this pre-upgrade validation warning:

Downgrade process from Cisco APIC 6.2(1) or later to pre Cisco APIC 6.2(1)

Due to upgrades and optimizations introduced in Cisco APIC release 6.2(1)—including centralized orchestration and faster reboot processes—downgrades from 6.2(1) or newer versions to releases older than 6.2(1) are not supported.

If you need to perform an emergency downgrade (for example, if an issue arises after upgrading and a rollback is necessary), Cisco TAC assistance is required. Below is an example process to guide you:

Downgrade Procedure (with Cisco TAC assistance):

  1. Ensure APICs and switches are running a pre-6.2 release.

  2. Export a configuration backup (including the AES encryption key) as described in Cisco ACI Configuration Files: Import and Export with Global AES Encryption.

  3. Upgrade APICs (and switches, if required) to a 6.2(1) or newer release.

  4. If a problem occurs and a rollback is needed, save your fabric-wide settings by running the command cat /data/data_admin/sam_exported.config on APIC1.

  5. Re-image all APICs with the pre-6.2 release ISO. Do not modify the switches at this stage.

  6. Contact Cisco TAC to recover the APIC cluster. TAC will use the configuration backup and AES key from Step 2. This APIC cluster recovery process can only be performed by Cisco TAC.

  7. If the switches were also upgraded to release 6.2(1) or later, downgrade them to the pre-6.2 version using the procedure described in Upgrading or Downgrading with APIC Release 5.1 or Later Using the GUI.

Alternative Procedure:

If traffic disruption is acceptable (such as in a lab environment), you can rebuild the fabric without assistance from Cisco TAC:

  • Save the fabric-wide settings by running 
    cat
                        /data/data_admin/sam_exported.config
    on APIC1.

  • Prepare the pre-6.2 configuration backup and the corresponding AES key.

    Note

    Without a configuration backup, you must rediscover all switches and manually reconfigure all policies.

  • Cleanly initialize (factory reset) both the APICs and switches:

    • Use the Decommission and Remove option to decomission all switches from the APIC GUI.

    • After removal, initialize all APICs using the commands acidiag touch setup and acidiag reboot.

  • Re-image each APIC with the pre-6.2 ISO.

  • Complete the initial setup of APIC1 using your saved settings.

  • Restore APIC1 by importing the pre-6.2 configuration backup and AES key.

  • All switches should be discovered and registered automatically, and remaining APICs will join the cluster. Contact Cisco TAC if additional help is required.

  • If switches have also been upgraded to 6.2(1) or later, downgrade them to the pre-6.2 version using the procedure described in Upgrading or Downgrading with APIC Release 5.1 or Later Using the GUI.

    Note

    If your pre-6.2 and 6.2(1) or newer releases support Enhanced Mixed Version, and only the switches require rollback, you can follow the Downgrade Only Switches to the Older Version with Enhanced Mixed Version Support procedure as described in the Operations Allowed During Mixed Versions on Cisco ACI Switches documentation.