Skip to content
Network as Code

First Steps

This guide walks you through configuring a Cisco NX-OS switch using Network as Code — starting from a single YAML file and a one-line Terraform module. The whole workflow is driven by the nac CLI, which wraps Terraform/OpenTofu, nac-validate and nac-test.

Prerequisites:

  • uv, used to install nac and to run nac-validate and nac-test
  • OpenTofu or Terraform 1.9.0 or later. If neither is installed, nac setup can download OpenTofu for you.
  • Your preferred text editor / IDE (such as Visual Studio Code)
  • NX-OS device reachable from your workstation

  1. Install the nac CLI

    Section titled “Install the nac CLI”

    nac is published on PyPI as nac-cli:

    Terminal window
    uv tool install nac-cli

  2. Enable NX-API on Devices

    Section titled “Enable NX-API on Devices”

    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 your workstation.

  3. Set Environment Variables

    Section titled “Set Environment Variables”

    The NX-OS provider and the tests authenticate using environment variables. Set the following in your terminal:

    Terminal window
    export NXOS_USERNAME=admin
    export NXOS_PASSWORD=password

  4. Create Your First Data File

    Section titled “Create Your First Data File”

    In a new project directory, create a file named inventory.nac.yaml with the following content. Replace the url with your device’s management address:

    nxos:
      devices:
        - name: SWITCH1
          url: https://10.1.1.1
          configuration:
            system:
              hostname: SWITCH1
              mtu: 9216
            vlan:
              vlans:
                - id: 10
                  name: WEB

    This file describes the desired state of a single switch: its hostname, system MTU and a VLAN. The configuration block uses the same structure as the NX-OS CLI, so you can describe any setting you would normally configure via the command line.

  5. Create the Terraform Configuration

    Section titled “Create the Terraform Configuration”

    In the same directory, create a file named main.tf:

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

      yaml_files = ["inventory.nac.yaml"]
    }

    This is the only Terraform configuration required. The nac-nxos module reads the YAML file and maps its contents to the underlying NX-OS provider resources automatically. It also writes the rendered data model to model.yaml, which is the file that nac validates and tests.

  6. Set Up and Initialize

    Section titled “Set Up and Initialize”

    Verify the prerequisites, then download the provider and module:

    Terminal window
    nac setup
    nac init

  7. Validate the Data Model

    Section titled “Validate the Data Model”
    Terminal window
    nac validate

    This renders model.yaml and validates it against the schema and rules packaged with the module, catching errors such as typos or invalid values before anything is sent to the device.

  8. Plan and Apply the Configuration

    Section titled “Plan and Apply the Configuration”
    Terminal window
    nac plan
    nac apply

    nac plan saves the changes required to reach the desired state to plan.tfplan, and nac apply pushes exactly this plan to the device via NX-API.

  9. Test the Deployment

    Section titled “Test the Deployment”
    Terminal window
    nac test

    This runs the tests packaged with the module against the device and verifies that the configuration in model.yaml was applied, for example that VLAN 10 exists with the name WEB. The results, including an HTML report, are written to tests/results/.

Congratulations! You have configured and tested your first NX-OS device using Network as Code. Continue with Multiple Devices to learn how to scale this to multi-device deployments using global configuration, device groups, templates and interface groups.