Task 03 - Global configuration

Estimated Time to Complete: ~25 minutes

In this task you'll use IOS XE as Code global configuration to apply settings across all devices at once. A login banner is the example - you'll see how global settings eliminate the need to repeat the same configuration on each device individually.

What you'll learn

By the end of this task you will have:

• Written a global Network as Code configuration file that applies to every registered device
• Run the full Terraform workflow end-to-end: init → plan → apply
• Verified the deployed banner by SSH-ing to each device

Global configuration

Global configurations define network-wide settings that apply to all devices unless explicitly overridden at the device group or device level. The configuration precedence hierarchy works as follows:

1. Device (highest precedence) - device-specific overrides
2. Device Group (medium precedence) - role or location-specific settings
3. Global (lowest precedence) - organization-wide defaults

By placing the banner in the global section, it will automatically apply to all devices listed in your configuration, ensuring consistency without duplication.

Create the global configuration file

First, create the global configuration file using your WSL Ubuntu terminal:

touch ~/nac-iosxe/data/global.nac.yaml

Then open data/global.nac.yaml in VS Code and add the following content. Notice how the banner is defined once in the global section and will be applied to every device registered in the per-device files you created in Task 02:

---
iosxe:
  global:
    configuration:
      banner:
        login: "Welcome to the IOS XE as Code lab!"

Key elements explained:

• --- - YAML document start marker
• iosxe: - Root key indicating IOS XE specific configuration
• global: - Defines configurations that apply to all devices
• configuration: - Contains the actual configuration settings
• banner: - Specifies banner configurations (note: singular, not "banners")
• login: - The login banner text displayed to users before they log in to the device

The figure below illustrates how to create the data/global.nac.yaml file with Visual Studio Code:

Documentation reference

But how do you know what configuration options are supported, and what the correct YAML structure is?

The data model documentation is published on the Network as Code website. Specifically, the banner configuration is described here: IOS XE Banner Configuration.

You can refer to this documentation at any time for more details on available configuration options, data types and guides. The curated configuration examples provide excellent references to help you create your own configurations.

Applying configuration with Terraform CLI

Now that you've created your configuration files, it's time to deploy them to your network devices using Terraform. Terraform follows a simple three-step workflow that ensures safe and predictable infrastructure changes.

Terraform workflow

Terraform uses a declarative approach where you define the desired state (in your YAML files), and Terraform figures out how to achieve that state. There are four moving parts:

1. Author (*.nac.yaml) - the YAML you write. Version-controlled, never touched by Terraform itself.
2. Preview (terraform plan) - read-only. Connects to devices, reads current state, shows you what would change. Safe to run any time.
3. Execute (terraform apply) - writes configuration over NETCONF and updates state. This is the step that actually changes the network.
4. Remember (terraform.tfstate) - auto-maintained. Tracks every resource Terraform has created, so subsequent plans know what's already there.

Of the three commands, only apply (and its counterpart destroy) change anything on the wire. plan is a read-only diff and can be run freely.

Step 1: In WSL (Ubuntu) and navigate to your project

In Windows Subsystem for Linux (WSL) terminal, navigate to your project directory:

cd ~/nac-iosxe

List the files in your directory:

tree -a

You should see your project structure:

cisco@wkst1:~/nac-iosxe$ tree -a
.
├── .env
├── data
│   ├── devices
│   │   ├── access01.nac.yaml
│   │   ├── access02.nac.yaml
│   │   ├── border.nac.yaml
│   │   └── core.nac.yaml
│   ├── global.nac.yaml
│   ├── groups
│   └── templates
└── main.tf

4 directories, 7 files
cisco@wkst1:~/nac-iosxe$

Step 2: Load environment variables from .env file

Before running Terraform, you need to load the credentials from your .env file. Your .env file contains simple key-value pairs (e.g. IOSXE_USERNAME=nac_admin).

To load these variables and make them available to Terraform, use this simple command:

source .env

Verify the variables are loaded:

env | grep IOSXE

You should see the environment variables displayed:

cisco@wkst1:~/nac-iosxe$ env | grep IOSXE
IOSXE_USERNAME=nac_admin
IOSXE_PASSWORD=cisco
cisco@wkst1:~/nac-iosxe$

These credentials allow Terraform to authenticate with your IOS XE devices over NETCONF.

Making Environment Variables Persistent:

Environment variables exported in your current shell session are not persistent - they disappear when you close the terminal. If you exit WSL and later open a new session, you must export them again.

To avoid manually exporting variables every time you open WSL, you can add the export command to your ~/.bashrc file. This file runs automatically whenever you start a new bash session, so your environment variables will be loaded automatically.

To make the export permanent, add it to your bashrc

echo 'source ~/nac-iosxe/.env' >> ~/.bashrc

This appends the source command to your ~/.bashrc file. Now every time you open WSL, your IOS XE credentials will be automatically loaded from the .env file.

Step 3: Verify NETCONF reachability

Before running Terraform, confirm the NETCONF subsystem is up on one of the lab devices. NETCONF listens on TCP/830 by default, and the simplest way to check it from WSL is a one-shot SSH handshake against the netconf subsystem - the device replies with an XML <hello> message containing its supported capabilities.

Test against access01 (198.18.130.11):

ssh -s -p 830 -o StrictHostKeyChecking=no $IOSXE_USERNAME@198.18.130.11 netconf

When prompted, enter the password (cisco).

What each flag does:

• -s - request an SSH subsystem (rather than an interactive shell).
• -p 830 - NETCONF's default port.
• -o StrictHostKeyChecking=no - skip the first-connection host-key prompt (lab-only; never use this in production).
• netconf - the subsystem name.

<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <capabilities>
    <capability>urn:ietf:params:netconf:base:1.0</capability>
    <capability>urn:ietf:params:netconf:base:1.1</capability>
    <capability>urn:ietf:params:netconf:capability:writable-running:1.0</capability>
    <capability>urn:ietf:params:netconf:capability:rollback-on-error:1.0</capability>
    ...
  </capabilities>
  <session-id>123</session-id>
</hello>
]]>]]>

If you see the <hello> XML with a capability list, NETCONF is reachable and your credentials work. Press Ctrl+C to exit - Terraform will manage its own NETCONF sessions from here on.

Step 4: Enable the NETCONF candidate datastore on each device

While the base NETCONF subsystem is already running, the candidate datastore capability has not yet been enabled. This is the missing CLI line that activates the <candidate> -> <commit> -> <discard-changes> flow Terraform relies on for transactional, all-or-nothing pushes (see the NETCONF datastore diagram in Task 01). Without it, NETCONF on IOS XE falls back to writing directly to running, which loses the "all RPCs commit together or none of them do" guarantee.

Enable it on all four lab devices using Solar-PuTTY. Open Solar-PuTTY, connect to each of core, border, access01, access02 as nac_admin / cisco, and run the same three commands on each:

configure terminal
netconf-yang feature candidate-datastore
end
write memory

Repeat for all four devices before moving on. Each box should accept the commands and save without errors.

Verify the capability now appears. Re-run the Step 3 NETCONF handshake against access01:

ssh -s -p 830 -o StrictHostKeyChecking=no $IOSXE_USERNAME@198.18.130.11 netconf

<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <capabilities>
    <capability>urn:ietf:params:netconf:base:1.0</capability>
    <capability>urn:ietf:params:netconf:base:1.1</capability>
    <capability>urn:ietf:params:netconf:capability:candidate:1.0</capability>
    <capability>urn:ietf:params:netconf:capability:confirmed-commit:1.1</capability>
    <capability>urn:ietf:params:netconf:capability:rollback-on-error:1.0</capability>
    ...
  </capabilities>
  <session-id>124</session-id>
</hello>
]]>]]>

The candidate:1.0 and confirmed-commit:1.1 capability lines are what tells you the feature is now active. Press Ctrl+C to exit. Terraform will use this datastore for every subsequent apply.

Step 5: Initialize Terraform

Initialize your Terraform project to download the required Network as Code module:

terraform init

What happens during initialization:

• Terraform reads your main.tf file
• Downloads the netascode/nac-iosxe module from GitHub (as defined in main.tf)
• Creates a .terraform directory with downloaded modules
• Creates a .terraform.lock.hcl file to lock module versions

Expected output:

Initializing the backend...             ← Reading backend config from main.tf.

Initializing modules...                 ← Found `module "iosxe"` in main.tf.
Downloading git::https://github.com/
  netascode/terraform-iosxe-nac-iosxe.
  git for iosxe...                      ← Cloning the Network as Code module from GitHub.
- iosxe in .terraform/modules/iosxe     ← Stored locally under .terraform/.
- iosxe.model in .terraform/modules/
  iosxe/modules/model                   ← Submodule that builds the data model.

Initializing provider plugins...        ← Now downloading the providers
                                          the Network as Code module declares.
- Finding ciscodevnet/iosxe versions
  matching "0.18.0"...
- Finding netascode/utils versions
  matching "1.1.0-beta3"...
- Finding hashicorp/local versions
  matching ">= 2.5.2"...
- Installing ciscodevnet/iosxe
  v0.18.0...
- Installed ciscodevnet/iosxe v0.18.0
  (signed by a HashiCorp partner)       ← Signature-verified. Good.
- Installing netascode/utils
  v1.1.0-beta3...
- Installed netascode/utils
  v1.1.0-beta3 (self-signed)            ← Helper provider for YAML merging.
- Installing hashicorp/local v2.9.0...
- Installed hashicorp/local v2.9.0
  (signed by HashiCorp)                 ← Writes rendered files to disk.

Terraform has created a lock file
  .terraform.lock.hcl                   ← Next init will pin these versions.

Terraform has been successfully
  initialized!                          ← 🎉 You're ready to run `plan`.

Step 6: Preview changes with Terraform plan

Before applying any changes to the lab devices, preview what Terraform will do:

terraform plan

What Terraform plan does:

• Reads your data/*.yaml configuration files
• Connects to your IOS XE devices (using credentials from environment variables)
  • Checks the current state of all previously applied resources
  • This is skipped on the first run since no resources have been created yet
• Compares desired state (YAML) vs. current state (device configuration)
• Shows you what will be added, changed, or deleted

Expected output:

Review the plan carefully to ensure Terraform will make the changes you expect. This is your safety check!

In this case, you will configure the login banner on all four devices. Terraform will create a resource for each banner on each device. This is indicated by the + signs in the plan output.

Step 7: Apply configuration to devices

If the plan looks good, apply the configuration:

terraform apply

Terraform will show you the plan again and ask for confirmation:

...
Plan: 6 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value:

Type yes and press Enter to proceed.

What happens during apply:

• Terraform opens a NETCONF session to each device over SSH (TCP/830)
• Uses the Network as Code modules and Terraform IOS XE provider to translate your YAML configuration into YANG data and writes it to the device's candidate datastore over NETCONF
• Issues <commit> so the candidate config is atomically swapped into running
• Applies the commands to the devices
• Tracks the applied state in terraform.tfstate file

Expected output:

terraform apply -auto-approve

module "iosxe" {
  source      = "git::https://github.com/netascode/terraform-iosxe-nac-iosxe.git"
  # ... other arguments ...
  save_config = true     # persist to startup-config after every apply
}

Step 8: Verify the global configuration

After Terraform completes successfully, verify the banner was applied to all devices. Because you used global configuration, the banner should be deployed to all four switches automatically.

Open Solar-PuTTY and connect to each switch:

1. Open Solar-PuTTY from your desktop
2. Connect to the core switch first
3. Verify that the pre-authentication banner appears upon ssh connection (shown below)
4. Repeat for border router, then the access01 and access02 switches

Upon successful config deployment, you should see the following banner message:

Additionally, you can also verify the banner configuration by examining the running configuration. Once connected to each switch, run the following command:

show run | include banner

core#show run | include banner
banner login ^CWelcome to the IOS XE as Code lab!^C
core#

The ^C characters represent control characters used by IOS XE to delimit the banner text. The important part is that you see your configured text in the output.

What you should observe:

• ✅ The banner appears on the core switch (198.18.130.10)
• ✅ The banner appears on the border switch (198.18.130.20)
• ✅ The banner appears on the access01 switch (198.18.130.11)
• ✅ The banner appears on the access02 switch (198.18.130.12)

for ip in 198.18.130.10 198.18.130.20 198.18.130.11 198.18.130.12; do
  echo "--- $ip ---"
  sshpass -p cisco ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
    nac_admin@$ip "show run | include banner"
done

Terraform state

After running terraform apply, Terraform creates a terraform.tfstate file that tracks:

• What resources have been created
• Current configuration of each resource
• Device connection details

Troubleshooting common issues

How to read a Terraform + IOS XE provider error

Most failures you'll see during terraform apply follow the same shape. Learning the anatomy once means every future error is readable. Here's a real example, annotated:

Error: Client Error                                         ← (1) error category
                                                               (Client/Server/Provider)
  with module.iosxe.iosxe_banner.banner[0],                 ← (2) Terraform resource
  on .terraform/modules/iosxe/iosxe/banner.tf line 5,         identifier + source file
  in resource "iosxe_banner" "banner":
   5: resource "iosxe_banner" "banner" {

Failed to commit (iosxe_banner.banner[0]),                  ← (3) operation that failed
  got error: NETCONF RPC error from 198.18.130.10:830:        and which device
    bad-element: banner                                     ← (4) device-side detail -
    error-message: 'banner' is not a valid element            this is what the device
    error-severity: error                                     actually said back

Four parts, always in this order:

1. Error category - Client Error means your input or config is wrong; Server Error means the device rejected something; Provider Error means the Terraform provider itself had a bug. Category tells you whose problem it is.
2. Terraform resource identifier - which specific resource Terraform was trying to operate on. Match this to your YAML to find the source.
3. Operation and target device - Failed to commit / Failed to create / Failed to delete, plus the device IP. Tells you exactly which device to investigate.
4. Device-side detail - the actual NETCONF/RESTCONF error payload from the device. This is what the IOS XE box said back when Terraform tried to push the config. 90% of the time this line names the offending element or value explicitly.

Working error messages right-to-left (detail -> device -> resource -> category) usually gives you the root cause in under a minute. For very noisy errors, re-run with TF_LOG=DEBUG terraform apply to see the full NETCONF XML payload the provider sent - often the fastest way to spot a subtle field mismatch.

What you've accomplished

Congratulations! You've successfully:

• ✅ Created YAML configuration files
• ✅ Initialized Terraform with the Network as Code module
• ✅ Previewed changes with terraform plan
• ✅ Applied configuration to your network devices with terraform apply
• ✅ Verified the banner on your devices

What's next?

In the next task, you'll learn how to use device groups to apply configurations to multiple devices efficiently.

← Previous: Task 02 - Editing YAML files · Next: Task 04 - Device group configuration