First Steps

This section provides a simple example of configuring Cisco NX-OS switches using Network-as-Code. It walks through a VXLAN EVPN fabric deployment to get familiar with the NX-OS NAC module and the YAML-driven approach.

The repository used in this example can be found at: https://github.com/netascode/nac-nxos-vxlan-example

This example assumes you have installed the following prerequisites.

• Terraform 1.9.0 or later.
• Git
• Your preferred text editor / Integrated Development Environment (IDE) (such as VisualStudio Code)

NX-API must be enabled on each NX-OS device before Terraform can communicate with it. SSH into each device and run:

feature nxapi

Ensure the device management IP is reachable from the machine running Terraform.

The NX-OS provider authenticates using environment variables:

export NXOS_USERNAME=admin
export NXOS_PASSWORD=password

git clone https://github.com/netascode/nac-nxos-vxlan-example.git
cd nac-nxos-vxlan-example

Open the folder in your preferred editor / IDE.

The main.tf file contains the required providers and points to the YAML data directory:

terraform {
  required_providers {
    nxos = {
      source = "CiscoDevNet/nxos"
    }
  }
}

module "nxos" {
  source  = "netascode/nac-nxos/nxos"
  version = "0.1.0"

  yaml_directories = ["data/"]
}

The required_providers block specifies the NX-OS provider from CiscoDevNet. Authentication is handled via the environment variables set in Step 2. The module block points to the NAC NX-OS module and reads all YAML files from the data/ directory. Device URLs are defined in the YAML inventory, so no explicit provider block with a URL is needed.

The data/ directory contains YAML files that describe the desired state of the fabric. Here are the key concepts:

The inventory.nac.yaml file defines the devices, their management URLs, device group memberships, and per-device variables:

nxos:
  devices:
    - name: LEAF1
      url: https://10.1.1.1
      device_groups:
        - LEAFS
      variables:
        hostname: LEAF1
        lo0_ip: 10.1.100.3
        vtep_ip: 10.1.200.1

    - name: SPINE1
      url: https://10.1.1.3
      device_groups:
        - SPINES
      variables:
        hostname: SPINE1
        lo0_ip: 10.1.100.1

Update the device URLs to match your environment.

Device groups allow you to logically group devices and assign shared templates and variables. For example, service_l2_101.nac.yaml defines a Layer 2 service across two leaf switches:

nxos:
  device_groups:
    - name: SERVICE_101
      devices:
        - LEAF1
        - LEAF2
      templates: [service_l2]
      variables:
        vlan_id: 101
        mcast_group: 225.1.1.1

This assigns the service_l2 template to both LEAF1 and LEAF2 with the specified variables. Adding more services is as simple as creating additional YAML files with different device groups and variables.

Templates are reusable configuration blocks with variable substitution. They can be defined inline as model-based templates or as external template files. Below is an example of a model-based template:

nxos:
  templates:
    - name: global
      type: model
      configuration:
        system:
          hostname: ${hostname}
          mtu: 9216
        feature:
          bgp: true
          ospf: true
          evpn: true
          nv_overlay: true

Variables like ${hostname} are resolved per device from the variables defined in the inventory. This allows the same template to produce different configurations for each device.

Interface groups define reusable interface configurations that can be applied to multiple interfaces across devices:

nxos:
  interface_groups:
    - name: FABRIC_INTERFACE
      configuration:
        switchport:
          enabled: false
        medium: p2p
        ip:
          unnumbered: lo0
        ospf:
          process: "1"
          area: 0.0.0.0
          network: p2p

An interface group is applied by referencing its name on individual interfaces:

interfaces:
  ethernets:
    - id: 1/1
      interface_groups: [FABRIC_INTERFACE]
    - id: 1/2
      interface_groups: [FABRIC_INTERFACE]

This applies the full FABRIC_INTERFACE configuration to both interfaces, avoiding repetition.

Initialize Terraform to download all required providers and modules:

terraform init

Preview the changes:

terraform plan

Apply the configuration to push changes to the NX-OS devices:

terraform apply

Type yes to approve.

SSH into the NX-OS devices and verify that the configuration was applied:

show running-config | include hostname
show vlan brief
show ip bgp summary
show nve peers

Run terraform destroy to remove all configuration managed by Terraform:

terraform destroy

Type yes to approve. Verify on the devices that the configuration has been reverted.