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:
- Terraform 1.9.0 or later
- Your preferred text editor / IDE (such as Visual Studio Code)
- IOS-XR device reachable from your workstation
-
Enable gNMI on Devices
Section titled “Enable gNMI on Devices”gNMI must be enabled on each IOS-XR device before Terraform can communicate with it. Connect to each device and run:
config tgrpcport 57400no-tlsaddress-family ipv4commitendEnsure the device management IP is reachable from the machine running Terraform.
-
Set Environment Variables
Section titled “Set Environment Variables”The IOS-XR module authenticates using environment variables. Set the following in your terminal:
Terminal window export IOSXR_USERNAME=adminexport IOSXR_PASSWORD=passwordexport IOSXR_TLS=falseIOSXR_TLS=falsematches theno-tlssetting on the device. Leave it unset once TLS is enabled. -
Create Your First Data File
Section titled “Create Your First Data File”In a new project directory, create a file named
inventory.nac.yamlwith the following content. Replace thehostwith your device’s management address:iosxr:devices:- name: ROUTER1host: 10.1.1.1configuration:hostname: ROUTER1clock:timezone: America-New_YorkThis file describes the desired state of a single device. The
configurationblock uses the same structure as the IOS-XR CLI, so you can describe any setting you would normally configure via the command line.The
hostis the device address, optionally followed by a port (10.1.1.1:57400). Without a port, gNMI uses 57400. -
Create the Terraform Configuration
Section titled “Create the Terraform Configuration”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-iosxrmodule reads the YAML file and maps its contents to the underlying IOS-XR provider resources automatically. -
Initialize Terraform
Section titled “Initialize Terraform”Run the following command to download the provider and module:
Terminal window terraform init -
Apply the Configuration
Section titled “Apply the Configuration”Preview and apply your changes:
Terminal window terraform applyReview the plan and type
yesto 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.
Going Further
Section titled “Going Further”Global Configuration
Section titled “Global Configuration”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: ROUTER2The 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
Section titled “Device Groups”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: ROUTER2Both 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
Section titled “Templates”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.255Then 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.2When 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
Section titled “Interface Groups”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.255The 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.