Ansible NX-API Failures Across a Mixed NX-OS Fleet
An automation team manages 40 Nexus 9000 switches with Ansible using the cisco.nxos.nxos_config module over NX-API HTTPS. The inventory contains a mix of NX-OS 9.3(10) and 10.3(4a). A service account named svc-ansible is used for all devices. After onboarding 12 new switches, the playbook fails on those hosts with connection timeouts; the other 28 work. On another five switches, the playbook connects but returns HTTP 401. The service account is in the network-operator role. The team uses ansible_connection: httpapi, ansible_httpapi_use_ssl: true, and ansible_httpapi_validate_certs: false. The 12 new switches have feature nxapi enabled but their management interface is in VRF management; the working switches use the default VRF. The five 401 switches use a local user with the same name but a different password in the inventory group.
1. Diagnose the two failure groups and explain why the same playbook works on 28 devices.
Read the worked answer
The 28 working devices prove the playbook syntax, transport, and credentials are broadly correct. The 12 timeouts are a reachability or NX-API listener problem: feature nxapi is enabled, but NX-API is listening in the default VRF while the management IP is in VRF management. The TCP connection to HTTPS never reaches the listener, so Ansible reports a timeout. The five HTTP 401 failures are authentication failures, not authorization failures. HTTP 401 means the credentials were rejected; the inventory group has a different password for the local svc-ansible user. If the role were the problem, the device would normally return 403 or an authorization error after successful login. The mixed NX-OS versions are not the primary cause of either group, although they can affect module behavior later. Confirm with a manual curl to the NX-API endpoint from the control node in the management VRF and with a login test on one 401 device.
2. What NX-OS and Ansible changes fix both groups, and what RBAC role should the automation account use?
Read the worked answer
On the 12 new switches, configure NX-API to use the management VRF, for example nxapi use-vrf management, and confirm the HTTPS port and management route. Ensure the control node can reach the management IP and that no ACL blocks TCP 443. On the five 401 switches, correct the inventory password for svc-ansible, preferably with Ansible Vault or a credential store rather than plaintext group vars. For RBAC, network-operator is read-only and cannot push configuration with nxos_config. Create a dedicated automation role with only the required configuration and show permissions, or use network-admin only if the risk is accepted and controlled. Do not share personal accounts. Validate with a read-only nxos_command task first, then a harmless configuration change in check mode. Confirm that ansible_httpapi_use_ssl: true matches the NX-API HTTPS listener on every device.
3. How would you make the playbook idempotent and safe for a mixed-version fleet?
Read the worked answer
Use nxos_config with explicit lines and parents so repeated runs converge on the same configuration. Avoid match: none unless you deliberately want to push every run, because it defeats idempotence. Run check_mode or --check first, enable backup: yes, and review diffs before applying. Use nxos_facts to gather version and capability data, and branch templates only where 9.3 and 10.3 genuinely differ. Set serial to a small canary batch and use max_fail_percentage to stop the rollout on failure. Keep credentials per host or per group and test the connection before configuration. For NX-API, validate that the same transport settings work on both versions; if a module has version-specific behavior, pin the collection version and test it against a lab switch. Finally, log the before and after configuration and verify with a post-change nxos_command check.