Ansible nxos_command Module — Run Commands on Cisco NX-OS

Introduction

The cisco.nxos.nxos_command module execute commands on Cisco Nexus switches running NX-OS with Ansible. This guide covers installation, parameters, practical examples, and troubleshooting for production use.

Quick Reference

- name: Basic nxos_command usage
  cisco.nxos.nxos_command:
    state: present

Parameters

Parameter	Required	Default	Description
`state`	No	present	Desired state (present/absent)
`name`	Yes	—	Target resource name

Installation

# Install the collection
ansible-galaxy collection install cisco.nxos

# Verify installation
ansible-doc cisco.nxos.nxos_command

Basic Example

---
- name: Run Commands on Cisco NX-OS Devices
  hosts: all
  become: true
  tasks:
    - name: Ensure resource is configured
      cisco.nxos.nxos_command:
        name: example
        state: present

Advanced Examples

Idempotent Configuration

- name: Configure with all options
  cisco.nxos.nxos_command:
    name: production
    state: present
  register: result

- name: Show result
  ansible.builtin.debug:
    var: result

Conditional Execution

- name: Only on specific OS
  cisco.nxos.nxos_command:
    name: example
    state: present
  when: ansible_os_family == "Debian"

Loop Over Multiple Items

- name: Configure multiple resources
  cisco.nxos.nxos_command:
    name: "{{ item }}"
    state: present
  loop:
    - resource1
    - resource2
    - resource3

Error Handling

- name: Handle failures gracefully
  block:
    - name: Attempt configuration
      cisco.nxos.nxos_command:
        name: example
        state: present
  rescue:
    - name: Log failure
      ansible.builtin.debug:
        msg: "Failed to configure nxos_command: {{ ansible_failed_result.msg }}"

Troubleshooting

Error	Cause	Fix
Module not found	Collection not installed	`ansible-galaxy collection install cisco.nxos`
Permission denied	Insufficient privileges	Add `become: true`
Timeout	Network/resource unavailable	Increase timeout, check connectivity
Idempotency issue	Module reports changed every run	Check parameter values match desired state

Best Practices

Use FQCN — always use cisco.nxos.nxos_command instead of short name
Register results — capture output for conditional logic
Handle errors — use block/rescue for graceful failure handling
Test in check mode — run with --check before applying
Pin collection version — specify version in requirements.yml

ansible.builtin.debug — Display variable values
ansible.builtin.assert — Validate conditions
ansible.builtin.set_fact — Set variables from task results

Conclusion

The cisco.nxos.nxos_command module provides idempotent execute commands on Cisco Nexus switches running NX-OS with Ansible Always use the FQCN, handle errors with block/rescue, and test with --check mode before production deployment.