Comparing NETCONF vs RESTCONF vs CLI

Objective

Compare the three common ways to interact with IOS XE devices — NETCONF, RESTCONF, and the traditional CLI — so you can choose the right tool for different operational and automation tasks. We will inspect how IOS XE represents the same configuration using NETCONF (XML) and RESTCONF (JSON) output formats, and show a Terraform example that uses RESTCONF/JSON. This matters in production because choosing the right interface affects scalability, auditability, tooling, and how you enforce desired state across many devices. Real-world scenario: an enterprise operations team wants to automate VLAN creation across hundreds of switches with Terraform and verify device configuration using NETCONF-based telemetry — understanding the strengths/limits of each method prevents surprises.

---

Topology (quick recap from Lesson 1)

The lab uses three Catalyst 9000 virtual switches reachable on the management network 198.18.1.0/24. We reference these management IPs exactly as provided.

ASCII topology:

 [Management Network: 198.18.1.0/24]
                 |
 -----------------------------------------
 |                 |                     |
 c9k-spine         c9k-leaf1             c9k-leaf2
 (198.18.1.21)     (198.18.1.31)         (198.18.1.32)

Device table:

Device name	Role	Management IP	Username	Password
c9k-spine	spine	198.18.1.21	developer	Lab@123
c9k-leaf1	leaf	198.18.1.31	developer	Lab@123
c9k-leaf2	leaf	198.18.1.32	developer	Lab@123

Tip: In production the management network often separates out-of-band management traffic from dataplane traffic so automation tooling and telemetry do not interfere with production forwarding.

---

Key Concepts (theory you must understand before touching commands)

• NETCONF vs RESTCONF format

  • NETCONF uses XML as its payload format and is session-oriented (commonly implemented over SSH). When you use NETCONF you are exchanging structured XML payloads that represent configuration or state. A NETCONF session persists and can be used for operations (get-config, edit-config) and subscription-based telemetry.
  • RESTCONF maps YANG-modeled data to a RESTful interface and most commonly uses JSON for payloads; Terraform’s IOS XE provider uses RESTCONF/JSON. RESTCONF is HTTP(S)-based and stateless per request (though the server may maintain internal state).

• CLI is the human-facing control plane

  • CLI changes are imperative: you type commands and the device applies them immediately. CLI is best for one-off changes, troubleshooting, or when an operator needs interactive control. Programmatic interfaces often convert or export CLI-config to machine-friendly formats.

• Tooling differences: stateful vs stateless

  • Terraform is stateful: it keeps a local state file and compares desired state to that stored state before applying changes (helps with safe deletions and drift detection). Ansible (when used with NETCONF) tends to be stateless in the sense it applies tasks without an external state file, unless you build that logic into your playbooks.

• Why format conversion matters

  • IOS XE provides CLI commands that produce the same configuration in NETCONF/XML and RESTCONF/JSON formats. This is critical when you are learning how YANG maps to actual CLI constructs — it lets you validate tooling that expects JSON or XML.

• Session lifecycle and telemetry

  • NETCONF sessions are persistent. If using NETCONF for telemetry push, make sure client tooling begins the session and does not immediately close it; otherwise telemetry subscriptions might not stay active. (When testing with a GUI YANG Suite you'll typically press a “Start Session” button to keep it open.)

---

Step-by-step configuration and inspection

For every step: we run the exact commands shown in the reference, explain the why, and show expected output.

Step 1: Show AAA configuration as NETCONF (XML) on c9k-spine

What we are doing:
We will ask the spine device to render its AAA-related configuration in NETCONF/XML format. This demonstrates how the same CLI configuration is represented for NETCONF clients (Ansible NETCONF modules, YANG tooling, etc.), and lets you inspect the XML structure that tooling will consume.

!-- SSH to c9k-spine (198.18.1.21) and run:
show running-config aaa | format netconf-xml

What just happened:
The device produced the AAA part of its running configuration converted into NETCONF-style XML. NETCONF clients can parse this XML to understand current configuration or to compute diffs for edit-config operations. NETCONF typically runs over SSH, keeping a persistent session for multiple RPCs; the XML structure follows YANG model mapping so each CLI stanza is represented as structured XML.

Real-world note: When using NETCONF for telemetry, ensure your client keeps the SSH session active — some GUI tools provide an explicit “Start Session” control.

Verify:

show running-config aaa | format netconf-xml

Expected output (example complete XML representation):

<config xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
  <aaa>
    <new-model></new-model>
    <authentication>
      <login>
        <local></local>
      </login>
    </authentication>
    <authorization>
      <exec>
        <local></local>
      </exec>
    </authorization>
    <accounting>
      <exec>
        <default></default>
      </exec>
    </accounting>
  </aaa>
</config>

Explanation of output: the XML shows the top-level container and sub-containers for authentication, authorization, and accounting consistent with YANG mapping. A NETCONF client would use such XML to construct get-config responses.

---

Step 2: Show AAA configuration as RESTCONF (JSON) on c9k-leaf1

What we are doing:
We will request the AAA configuration in RESTCONF/JSON format from leaf1 to see how RESTCONF represents the same data. This is the payload format Terraform uses via the IOS XE provider when using RESTCONF/JSON.

!-- SSH to c9k-leaf1 (198.18.1.31) and run:
show running-config aaa | format restconf -json

What just happened:
The device converted the AAA config into JSON that mirrors the YANG model structure. RESTCONF translates YANG-modeled elements into JSON objects and arrays. RESTCONF is typically accessed via HTTPS by automation tools; Terraform’s provider will send JSON payloads matching this structure.

Real-world note: Terraform expects JSON-shaped data when using the IOS XE RESTCONF provider; seeing the JSON lets you craft or validate provider resources.

Verify:

show running-config aaa | format restconf -json

Expected output (example complete JSON representation):

{
  "Cisco-IOS-XE-native:aaa": {
    "new-model": {},
    "authentication": {
      "login": {
        "local": {}
      }
    },
    "authorization": {
      "exec": {
        "local": {}
      }
    },
    "accounting": {
      "exec": {
        "default": {}
      }
    }
  }
}

Explanation: The JSON keys are namespaced as per IOS XE YANG module; objects represent containers and empty objects indicate presence-only containers (e.g., new-model). Terraform or RESTCONF clients will post/put JSON in this shape when changing these elements.

---

Step 3: Inspect Terraform resource example (RESTCONF/JSON mapping)

What we are doing:
We will review the Terraform HCL example that the IOS XE provider can use to manage a VLAN via RESTCONF. This demonstrates how declarative Terraform resources map to device configuration that RESTCONF exposes as JSON.

terraform {
  required_providers {
    iosxe = {
      source  = "CiscoDevNet/iosxe"
      version = ">=0.5.0"
    }
  }
}

provider "iosxe" {
  username = "developer"
  password = "Lab@123"
  url      = "https://198.18.1.31"
}

resource "iosxe_vlan" "example" {
  vlan_id  = 511
  name     = "Vlan511"
  shutdown = false
}

What just happened:
This HCL file declares a provider configured to contact the device at 198.18.1.31 and defines a VLAN resource. When you run terraform apply the provider translates the resource into RESTCONF JSON payloads and sends them over HTTPS to the device. Terraform keeps a local state file so future runs know whether the VLAN already exists and whether it needs to be created or destroyed.

Real-world note: Terraform’s statefulness makes it powerful for lifecycle management in production, but you must protect and share state files securely in multi-operator teams.

Verify:

!-- After applying terraform, review the device representation of VLANs using RESTCONF formatting:
show running-config | include vlan | format restconf -json

Expected output (example showing the resource presence in JSON):

{
  "Cisco-IOS-XE-native:vlan": {
    "vlan-list": [
      {
        "id": 511,
        "name": "Vlan511",
        "shutdown": false
      }
    ]
  }
}

Explanation: The JSON shows a vlan-list with id 511 and the configured name. This is the shape Terraform aimed to create via RESTCONF. (Exact JSON field names follow the device YANG mapping.)

---

Step 4: Compare CLI, NETCONF and RESTCONF approaches and their verification workflows

What we are doing:
We show the same AAA configuration via standard CLI, show as NETCONF XML, and show as RESTCONF JSON to compare which workflows are best suited for automation or manual tasks.

!-- On any device (example c9k-leaf2 198.18.1.32):
show running-config aaa
show running-config aaa | format netconf-xml
show running-config aaa | format restconf -json

What just happened:

• show running-config aaa provides the human-readable CLI view.
• The | format netconf-xml and | format restconf -json produce machine-parseable representations used by NETCONF and RESTCONF clients.
  This triad demonstrates how the same configuration is expressed in each interface, letting you decide whether to use CLI for interactive changes, NETCONF for session-based structured operations (e.g., Ansible NETCONF modules), or RESTCONF for RESTful automation stacks (e.g., Terraform).

Real-world note: For auditability and automation pipelines, teams often develop an “intent” in Terraform (RESTCONF/JSON) and use NETCONF or CLI for on-device verification and ad-hoc troubleshooting.

Verify:

show running-config aaa

Expected output (example CLI):

aaa new-model
aaa authentication login default local
aaa authorization exec default local
aaa accounting exec default start-stop group tac_plus

show running-config aaa | format netconf-xml

Expected XML output:

<config xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
  <aaa>
    <new-model></new-model>
    <authentication>
      <login>
        <default>
          <local></local>
        </default>
      </login>
    </authentication>
    <authorization>
      <exec>
        <default>
          <local></local>
        </default>
      </exec>
    </authorization>
    <accounting>
      <exec>
        <default>
          <start-stop>
            <group>tac_plus</group>
          </start-stop>
        </default>
      </exec>
    </accounting>
  </aaa>
</config>

show running-config aaa | format restconf -json

Expected JSON output:

{
  "Cisco-IOS-XE-native:aaa": {
    "new-model": {},
    "authentication": {
      "login": {
        "default": {
          "local": {}
        }
      }
    },
    "authorization": {
      "exec": {
        "default": {
          "local": {}
        }
      }
    },
    "accounting": {
      "exec": {
        "default": {
          "start-stop": {
            "group": "tac_plus"
          }
        }
      }
    }
  }
}

Explanation: Seeing the CLI and both machine formats side-by-side makes it clear how YANG maps and why automation tools choose one format over another.

---

Verification Checklist

• Check 1: NETCONF/XML view produced — Verify by running show running-config aaa | format netconf-xml on 198.18.1.21 and confirm XML contains containers.
• Check 2: RESTCONF/JSON view produced — Verify by running show running-config aaa | format restconf -json on 198.18.1.31 and confirm JSON keys include "Cisco-IOS-XE-native:aaa".
• Check 3: Terraform resource mapping — Verify HCL resource for iosxe_vlan exists in your Terraform file and that device JSON (via RESTCONF formatting) includes the vlan entry after terraform apply.

---

Common Mistakes

Symptom	Cause	Fix
NETCONF session cannot receive telemetry	NETCONF session closed by client immediately after RPC	Keep session alive; use "Start Session" in GUI tools or maintain SSH session in your client code so subscriptions persist
Terraform apply fails to create resource	Incorrect provider URL or credentials	Verify provider block uses the correct URL (e.g., "https://198.18.1.31") and credential values (username "developer", password "Lab@123")
JSON/RESTCONF payloads don't match expected model	Mismatch between HCL resource fields and device YANG model	Use `show running-config
Operators confused by differences between CLI and JSON keys	Expectation that CLI text maps 1:1 to JSON keys	Remember YANG maps CLI into structured containers; consult the JSON output to see precise element names

---

Key Takeaways

• NETCONF (XML) and RESTCONF (JSON) are machine-friendly views of the same YANG-modeled device configuration; use NETCONF for session-based operations and RESTCONF for HTTP/JSON RESTful automation.
• CLI is imperative and interactive — great for troubleshooting and immediate changes; programmatic interfaces enable scale and can be integrated into IaC pipelines.
• Terraform uses RESTCONF/JSON and is stateful — ideal for lifecycle management across many devices, but requires careful state handling and secure storage of credentials and state files.
• Always validate how your automation tool represents device config by using the device-side | format netconf-xml or | format restconf -json outputs — this prevents model mismatches in production.

Important: In production, plan your automation approach around the team’s operational practices — use RESTCONF/JSON for declarative IaC with Terraform, NETCONF/XML when you need session-based management or streaming telemetry, and CLI for ad-hoc operational tasks.