NXOS Modules

Objective

Automate VLAN and interface configuration on Nexus (NX‑OS) switches using Ansible. In this lesson you'll use Ansible NX‑OS modules to create a VLAN, configure an access interface, and create a switched virtual interface (SVI). This matters in production because programmatic VLAN/interface provisioning reduces manual errors and accelerates onboarding of new racks or tenant networks in a data center or campus.

Quick Recap

We continue from the lab topology introduced earlier. This lesson uses the same devices: two Nexus switches (NX1 and NX2) and an Ansible control host. No new physical devices are added in this lesson.

ASCII topology (management and data-plane IPs shown):

NX1 (mgmt: 192.168.100.11) +-----------------+ +-----------------+ | Ansible Host | | NX2 (mgmt: | | mgmt: 192.168.100.10 |------------------| 192.168.100.12) | +-----------------+ 1G mgmt +-----------------+

Data-plane between NX1 and NX2: NX1 Ethernet1/1 (10.10.10.1/30) --- NX2 Ethernet1/1 (10.10.10.2/30)

VLAN 10 will be created and used on Ethernet1/2 on each switch for host connectivity (SVI on NX1: 10.10.20.1/24).

Important: lab domain names use lab.nhprep.com and any example passwords use Lab@123.

Key Concepts (theory + practical)

• Idempotency of Ansible modules — The NX‑OS Ansible modules are designed to be idempotent: running the same task multiple times will converge the device to the same intended state without repeated side effects. In production this means automation runs can be safely scheduled or retried.
• nxos_command vs configuration modules — Sending ad‑hoc commands (nxos_command / nxos.nxos_command) queries state or performs single‑shot actions; configuration modules (nxos_config / nxos_vlan / nxos_interface) express desired state and should be preferred for ongoing automation.
• VLAN database vs SVI behavior — Creating a VLAN adds it to the VLAN database. An SVI (interface VlanX) provides L3 termination for that VLAN. In production, an SVI will only be useful if at least one L2 port in the VLAN is up (or if the VLAN is used on termination points like virtual machines).
• Interface operational state — Setting an interface as access and assigning it to a VLAN does not force it up if the physical link is down. Monitoring link status is important when validating automation in production.
• Prompt handling and file copy — When automating file transfers (e.g., copying images or configs), Ansible modules can handle prompts (username/password). This is important for secure, automated image upgrades or backups.

Step-by-step configuration

Step 1: Prepare control host (install Ansible and NX‑OS collection)

What we are doing: Install Ansible and the NX‑OS collection so the control host has the modules needed to talk to Nexus switches. This matters because the collection provides the FQCN modules used in subsequent tasks.

# Install Ansible (creates the ansible runtime)
pip install ansible

# Install the NX-OS collection (provides cisco.nxos modules)
ansible-galaxy collection install cisco.nxos

What just happened: pip install ansible installs the Ansible engine (task runner and core libraries). ansible-galaxy collection install cisco.nxos downloads the vendor collection which contains NX‑OS modules such as nxos_config, nxos_vlan, nxos_interface, and nxos_command. Without these modules Ansible cannot natively build NX‑OS configuration tasks.

Real-world note: Using a Python virtual environment is recommended so Ansible and collections are isolated by project.

Verify:

# Verify ansible is installed (control host)
ansible --version

Expected output (example):

ansible [core 2.14.0]
  config file = None
  configured module search path = ['/home/nhprep/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/local/lib/python3.9/site-packages/ansible
  executable location = /usr/local/bin/ansible
  python version = 3.9.11 (default, ...)
Collections installed:
  cisco.nxos, version X.Y.Z

Step 2: Create VLAN 10 with nxos_vlan

What we are doing: Use the nxos_vlan module to ensure VLAN 10 exists on NX1. Programmatic VLAN creation removes manual CLI steps and is auditable.

# Ansible task snippet (playbook task)
- name: Ensure VLAN 10 exists on NX1
  cisco.nxos.nxos_vlan:
    vlan_id: 10
    name: LAB_VLAN_10
    state: present
  delegate_to: localhost

What just happened: The nxos_vlan module sends the necessary NX‑OS config commands to create VLAN 10 and set its name. The module will check the running config first and only apply changes if needed (idempotent). On the device the CLI equivalent is vlan 10 then name LAB_VLAN_10.

Real-world note: Use named VLANs for easier troubleshooting and to match IPAM records in real deployments.

Verify:

# On NX1 CLI
configure terminal
vlan 10
name LAB_VLAN_10
exit
show vlan id 10

Expected output:

VLAN Name                             Status    Ports
---- -------------------------------- --------- --------------------------
10   LAB_VLAN_10                      active    Ethernet1/2

Step 3: Configure physical interface as access and assign VLAN with nxos_interface

What we are doing: Configure Ethernet1/2 as an access port in VLAN 10. This connects end hosts to the VLAN; making it automated ensures consistent access port settings across many switches.

# Ansible task snippet
- name: Configure Ethernet1/2 as access on NX1
  cisco.nxos.nxos_interface:
    config:
      - name: Ethernet1/2
        description: "Access port for VLAN 10 - lab.nhprep.com"
        enabled: true
        mode: access
        access_vlan: 10
  delegate_to: localhost

What just happened: The nxos_interface module programs the interface configuration (description, administrative state, switchport mode, and VLAN membership). Under the hood the module issues the equivalent NX‑OS commands:

• interface Ethernet1/2
• description ...
• switchport mode access
• switchport access vlan 10
• no shutdown

This affects packet flow by ensuring frames received on Ethernet1/2 are tagged/untagged appropriately for VLAN 10 at L2.

Real-world note: Avoid forcing "no shutdown" on fiber ports with SFPs that are expected to be administratively down during staging; validate physical connectivity first.

Verify:

show running-config interface Ethernet1/2
show interface Ethernet1/2 status

Expected output:

! output of show running-config interface Ethernet1/2
interface Ethernet1/2
  description Access port for VLAN 10 - lab.nhprep.com
  switchport mode access
  switchport access vlan 10
  no shutdown

! output of show interface Ethernet1/2 status
Port        Name                            Status    Vlan    Duplex  Speed
Ethernet1/2 Access port for VLAN 10 - lab.nhprep.com  connected 10       full    1000

Step 4: Create SVI (interface Vlan10) with nxos_config

What we are doing: Configure SVI interface Vlan10 on NX1 so the switch can route for hosts in VLAN 10. Using nxos_config expresses the desired configuration for the SVI.

# Ansible task snippet
- name: Configure SVI for VLAN 10 on NX1
  cisco.nxos.nxos_config:
    lines:
      - interface Vlan10
      - description SVI for LAB_VLAN_10
      - ip address 10.10.20.1/24
      - no shutdown
  delegate_to: localhost

What just happened: The nxos_config module applies the provided lines in configuration mode. Creating interface Vlan10 with an IP address allows NX1 to route for VLAN 10. At the packet level, the SVI will respond to ARP requests for 10.10.20.1 and will forward traffic between VLAN 10 and other L3 destinations according to the routing table.

Real-world note: Ensure your management/control-plane ACLs allow ARP and necessary control protocols between hosts and the SVI during automated provisioning.

Verify:

show running-config interface Vlan10
show ip interface brief | include Vlan10
show arp | include 10.10.20

Expected output:

! show running-config interface Vlan10
interface Vlan10
  description SVI for LAB_VLAN_10
  ip address 10.10.20.1/24
  no shutdown

! show ip interface brief
Interface       IP-Address      OK? Method Status                Protocol
Vlan10          10.10.20.1      YES manual up                    up

! show arp | include 10.10.20
10.10.20.5      0001.6387.0a2b  Vlan10

Step 5: Validate end-to-end and idempotency

What we are doing: Re-run the playbook to confirm tasks are idempotent and check operational behavior (switchport connectivity, SVI reachability). Idempotency prevents configuration flicker in production.

# Re-run the same Ansible playbook on control host
ansible-playbook -i inventory.yml nxos_vlan_interface_playbook.yml

What just happened: Ansible compared desired state to the device's running state. Since VLAN, interface, and SVI already exist and match the intent, the modules report "ok" without making changes. This confirms safe, repeatable automation.

Verify:

# Example verification commands
show vlan id 10
show interface Ethernet1/2 status
show ip route

Expected output:

VLAN Name                             Status    Ports
---- -------------------------------- --------- --------------------------
10   LAB_VLAN_10                      active    Ethernet1/2

Port        Name                            Status    Vlan    Duplex  Speed
Ethernet1/2 Access port for VLAN 10 - lab.nhprep.com  connected 10       full    1000

Codes: C - connected, S - static, R - RIP, O - OSPF, B - BGP
Gateway of last resort is not set

C    10.10.20.0/24 is directly connected, Vlan10
C    10.10.10.0/30 is directly connected, Ethernet1/1

Real-world note: For production, implement pre-checks (link status, expected neighbors) and post-checks (reachability, monitoring alarms) in your automation pipeline.

Verification Checklist

• Check 1: VLAN 10 exists on NX1 — verify with show vlan id 10 and expect VLAN 10 and name LAB_VLAN_10 in output.
• Check 2: Ethernet1/2 is access in VLAN 10 — verify with show running-config interface Ethernet1/2 and show interface Ethernet1/2 status expecting "switchport access vlan 10" and status "connected" when the cable/host is up.
• Check 3: SVI Vlan10 is configured and up — verify with show ip interface brief expecting Vlan10 with IP 10.10.20.1 and Status/Protocol up.
• Check 4: Re-running the playbook produces no changes (idempotent) — verify that ansible-playbook reports tasks as "ok" and not "changed".

Common Mistakes

Symptom	Cause	Fix
VLAN present but SVI shows down	No active L2 member in VLAN (no access port up)	Plug in or enable at least one access port in VLAN 10; verify show interface status
Ansible task reports failure copying files or gathering facts	Missing collection or wrong Ansible version	Ensure Ansible is installed (pip install ansible) and the cisco.nxos collection is installed (ansible-galaxy collection install cisco.nxos)
Interface shows as trunk instead of access after automation	Module configuration incorrect or pre-existing config	Inspect running-config for interface; correct mode with nxos_interface to set mode: access
Playbook makes changes every run (not idempotent)	Using raw command pushes instead of configuration modules or different idempotency parameters	Use the nxos_vlan/nxos_interface/nxos_config modules (stateful modules) rather than ad-hoc command module for config changes

Key Takeaways

• Use vendor-specific modules (cisco.nxos.*) to declare desired state — this yields idempotent, auditable automation suitable for production.
• Automating VLANs, interfaces, and SVIs reduces manual error and accelerates provisioning, but always pair config tasks with validation checks (link state, ARP, route table).
• Distinguish between ad‑hoc command modules (for show commands and one-off tasks) and configuration modules (for persistent state).
• In a data center or campus, automation is most effective when integrated with IPAM, CMDB, and CI/CD pipelines so state is tracked, validated, and rolled back safely.

Tip: Always include verification tasks in your playbook (or an Ansible test play) to assert that the network state matches the desired state after changes.