Skip to content

First Steps

This guide walks you through configuring a Cisco IOS-XR device using Network as Code — starting from a single YAML file and a one-line Terraform module, then progressively introducing the IOS-XR-specific constructs that make it easy to scale to multi-device deployments.

Prerequisites:

  1. gNMI must be enabled on each IOS-XR device before Terraform can communicate with it. Connect to each device and run:

    config t
    grpc
    port 57400
    no-tls
    address-family ipv4
    commit
    end

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

  2. The IOS-XR module authenticates using environment variables. Set the following in your terminal:

    Terminal window
    export IOSXR_USERNAME=admin
    export IOSXR_PASSWORD=password
    export IOSXR_TLS=false

    IOSXR_TLS=false matches the no-tls setting on the device. Leave it unset once TLS is enabled.

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

    iosxr:
    devices:
    - name: ROUTER1
    host: 10.1.1.1
    configuration:
    hostname: ROUTER1
    clock:
    timezone: America-New_York

    This file describes the desired state of a single device. The configuration block uses the same structure as the IOS-XR CLI, so you can describe any setting you would normally configure via the command line.

    The host is the device address, optionally followed by a port (10.1.1.1:57400). Without a port, gNMI uses 57400.

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

    module "iosxr" {
    source = "netascode/nac-iosxr/iosxr"
    version = "0.1.1"
    yaml_files = ["inventory.nac.yaml"]
    }

    This is the only Terraform configuration required. The nac-iosxr module reads the YAML file and maps its contents to the underlying IOS-XR provider resources automatically.

  5. Run the following command to download the provider and module:

    Terminal window
    terraform init
  6. Preview and apply your changes:

    Terminal window
    terraform apply

    Review the plan and type yes to confirm. Terraform pushes the configuration to the device via gNMI.

Congratulations! You have configured your first IOS-XR device using Network as Code. The sections below show how to extend this foundation to multi-device deployments using global configuration, device groups, templates, and interface groups.

When managing multiple devices, it is common to have settings that apply to all of them — such as NTP servers or the time zone. Rather than repeating these in every device block, you can define them once under the global key.

Add a second device and move shared configuration to global:

iosxr:
global:
configuration:
ntp:
servers:
- address: 10.0.0.10
devices:
- name: ROUTER1
host: 10.1.1.1
configuration:
hostname: ROUTER1
- name: ROUTER2
host: 10.1.1.2
configuration:
hostname: ROUTER2

The IOS-XR module merges configuration at three levels — global → device group → device — with more specific levels taking precedence. NTP is now applied to both devices without duplication.

Device groups let you apply a shared configuration block to a set of devices. This is useful for anything that is common to a role (e.g., all provider edge routers share the same time zone and NTP source).

Add a device_groups section and reference the group from each device:

iosxr:
global:
configuration:
ntp:
servers:
- address: 10.0.0.10
device_groups:
- name: ROUTERS
configuration:
clock:
timezone: America-New_York
devices:
- name: ROUTER1
host: 10.1.1.1
device_groups:
- ROUTERS
configuration:
hostname: ROUTER1
- name: ROUTER2
host: 10.1.1.2
device_groups:
- ROUTERS
configuration:
hostname: ROUTER2

Both devices now inherit the clock setting from the ROUTERS group. A device can belong to multiple groups, and each group is merged in order before the device-level configuration is applied.

Templates allow you to define reusable configuration blocks that are rendered per device using variable substitution. This avoids writing nearly-identical YAML blocks for each device when only a few values differ.

The simplest template type is model — defined inline in your YAML. Add a loopback template that uses a per-device variable:

First, register the template in your YAML (you can add this to inventory.nac.yaml or a separate file):

iosxr:
templates:
- name: LOOPBACK
type: model
configuration:
interfaces:
loopbacks:
- id: 0
ipv4:
address: ${lo0_ip}
mask: 255.255.255.255

Then assign the template and provide the variable on each device:

iosxr:
device_groups:
- name: ROUTERS
templates:
- LOOPBACK
configuration:
clock:
timezone: America-New_York
devices:
- name: ROUTER1
host: 10.1.1.1
device_groups:
- ROUTERS
variables:
lo0_ip: 10.0.0.1
- name: ROUTER2
host: 10.1.1.2
device_groups:
- ROUTERS
variables:
lo0_ip: 10.0.0.2

When Terraform runs, the LOOPBACK template is rendered once per device, substituting ${lo0_ip} with the value from each device’s variables block. ROUTER1 gets 10.0.0.1 and ROUTER2 gets 10.0.0.2 as their loopback address.

Interface groups define a named set of interface configuration that can be reused across multiple interfaces or devices. They are especially useful for enforcing consistent settings on a class of interface — for example, all loopbacks should have the same description and shutdown state.

Add an interface group and reference it from the loopback template:

iosxr:
interface_groups:
- name: LOOPBACK_INTERFACE
configuration:
description: Router ID
shutdown: false
templates:
- name: LOOPBACK
type: model
configuration:
interfaces:
loopbacks:
- id: 0
interface_groups: [LOOPBACK_INTERFACE]
ipv4:
address: ${lo0_ip}
mask: 255.255.255.255

The interface_groups key on an interface is a list, so a single interface can inherit from multiple groups. Group configuration is merged before any inline interface configuration is applied.


You now have the full building blocks of a Network as Code IOS-XR deployment. Explore the IOS-XR Data Models section for the complete list of configurable attributes.