YANG-Based Network Automation in SONiC: NETCONF, RESTCONF, and gNMI

1. Background: Deep technical challenges faced by traditional CLI and SNMP

Before the emergence of model driven network automation, network operations mainly relied on Command Line Interface (CLI) and Simple Network Management Protocol (SNMP). However, in modern data centers and cloud native networks, these two technologies face significant limitations in terms of underlying architecture:

• CLI lacks structured data and transaction management capabilities: The output of CLI is pure text for personnel to read, without a standard data format. This results in automated programs relying solely on direct text matching to extract information, and even minor changes in system versions or command syntax can easily lead to parsing failures. In addition, CLI cannot guarantee that a set of configuration commands will either be successful or ineffective; Once an error occurs during the modification process, the system cannot automatically ‘undo’ and restore to its previous normal state. When issuing network policies in batches across devices, if some commands fail to execute, it can easily lead to inconsistent network configuration status or cause network interruptions.
• SNMP focuses on monitoring and lacks configuration capabilities: The original design intention of SNMP is mainly for network status monitoring, and its data structure (MIB tree) is difficult to directly correspond with modern complex network business models. At the same time, SNMP has weak support for network configuration, with most vendors providing interfaces that only support read-only queries and lack a unified configuration writing standard. Difficult to meet the requirements of large-scale and complex automated network deployment.

2. What is YANG

YANG (RFC 7950), as a universal data modeling language in the field of networks, defines a structured model of device configuration and status. It enables automated systems to no longer rely on error prone text scraping, achieving precise management based on standard data formats.

• Strict hierarchical and strong type verification: YANG organizes network data into strict logical trees (Modules, Containers, Lists, Leaves). It has built-in powerful data constraint rules, such as type checking, regular constraint patterns, dependency relationship must/when, etc. This means that the automation system can complete 100% syntax and logic pre validation on the client side before issuing configurations, intercepting configuration errors before deployment.
• Physical isolation between configuration data and status data: YANG clearly defined “Configuration Data” (the instructions we expect the device to execute) and “Operational/State Data” (the underlying hardware entries or counters that actually occur on the device) at the model level. This isolation provides a foundation for precise closed-loop automated monitoring.
• Multidimensional evolution of model ecology: In addition to the native models of various vendors, the industry has widely promoted the OpenConfig (led by hyper scale cloud vendors) standard model. Based on a unified YANG model, a single automation code can achieve indiscriminate management of heterogeneous devices.

AsterNOS supports dual track YANG model ecology. On the one hand, providing highly customized private YANG models; On the other hand, supporting OpenConfig public YANG model ensures seamless interoperability of devices in multi-vendor hybrid networking and cloud native environments. Both private and public models are supported by parsing, validation, and scheduling engines in the architecture.

3. NETCONF、RESTCONF and gNMI

AsterNOS fully supports three modern management protocols, NETCONF, RESTCONF, and gNMI, with YANG data model as the core.

The architecture is divided into four core processing layers from top to bottom, achieving perfect decoupling between the protocol layer and the business control layer:

• Upper Presentation Layer: Klish CLI and RESTCONF requests access through HTTP Server; NETCONF relies on a highly secure SSH Server; GNMI establishes connections through high-performance gRPC servers.
• Presentation Layer: This is a crucial step in achieving normalization. The traditional command line passed in by Klish is dynamically translated into expressions that comply with YANG specifications through a Command Converter. All protocol requests will ultimately converge to YANG Model Validation/Request Dispatch, which serves as the “scheduling brain” and combines with the model dictionary loaded by YANG Parser to perform 100% pre validation on the types, boundaries, and dependencies of requests, and then distribute them uniformly to lower layers.
• Control Layer: Responsible for specific business lifecycle management. The CRUD controller receives standard modeled requests and converts them into specific business operations. At the same time, the Notification Agent continuously listens to the underlying state and events at this layer, and penetrates upwards and backwards to distribute to gNMI Telemetry or NETCONF subscription channels.
• Model Layer & Database: The Object Mapping module is responsible for bidirectional mapping between the business model and the Key Value format of the SONiC underlying architecture. The mapped data configuration and session state are ultimately written directly to the Cfg DB in Redis Server through Redis Connector. This enables all protocol operations to achieve complete convergence of their configuration database (Cfg DB) before reaching ASIC hardware, with 100% underlying consistency.

3.1 NETCONF

NETCONF is based on SSH transmission and uses XML encoding.

AsterNOS implements strict separation and closed-loop synchronization of the three major databases: <running/> (current running configuration library), <startup/> (next startup loading library), and <operational/> (read-only running state library containing device underlying hardware counts).

Database	Explanation
<running/>	This database stores the currently valid running configurations. The data in this database can be modified, and the modifications take effect immediately.
<startup/>	This database stores the configuration that will take effect after the next startup. Cannot modify data in this database. The configuration in <running/> can only be replaced in this database by executing <copy-config> or <save-config>.
<operational/>	This is the default data storage for all read operations. It contains system status and configuration from sources other than user configuration. (For example, system default values and configurations learned from the cluster)

3.1.1 Message Structure

• Message: Provide an independent and standardized transmission framework for RPC packets. The client will encapsulate the specific request instructions in a <rpc> element with globally unique message id and underlying protocol namespace declaration and send them to the switch; After processing by the switch, the result will be encapsulated within the <rpc-reply> element that strictly corresponds to the message id in response (success will return <ok> , failure will return <rpc-error> containing highly structured diagnostic information such as <error-tag> and trigger automatic rollback).
• Operations: Defined a set of basic operational instructions. The core supported operations include queries (<get>, <get-config>), configuration distribution (<edit-config>), configuration solidification and copying (<copy-config>), and session management (<close-session>).
• Content: Define configuration and status data based on YANG data model. The data must be transmitted nested in XML format within the message.

3.1.2 Basic Operations

• <get-config>: Used to query all or part of the specified configuration data in the <running/>, <operational/>, and <startup/> configuration databases.
• <get>: Used to query configuration data and running status data of <running/>.
• <edit-config>: Used to load or modify configuration data for the <running/> database. Supports four operational attributes: merge, replace, create, and delete. Once the configuration is issued, it will take effect immediately in the system.
• <copy-config>: Used to copy data or files from one configuration database to another configuration database or file. In practical operation, the source can be <running/>, <startup/>, or a specific URI (such as scp/ftp/file, etc.), and the target can be <startup/> or a URI. Note: Currently AsterNOS does not support writing URI as a source directly to the database target。
• <close-session>: Used to close the current NETCONF session normally and elegantly, and release the locks and resources associated with the session.

3.1.3 Core Capabilities

In addition to basic operational capabilities, AsterNOS has also implemented a series of standard capability sets.

• Writable-running: This capability indicates that the device supports direct write capability to the <running/> configuration database. Allow automated scripts to directly modify the running configuration through <edit-config>, and the configuration changes will take effect immediately, eliminating the traditional two-stage process of “writing candidate database first, and then manually commit” that is cumbersome for devices.
• Rollback-on-Error: This capability indicates that the device has the ability to roll back errors. Unlike traditional devices that require the client to specify <error-option>rollback on error</error-option>, AsterNOS has built-in integration in the underlying system: when any node configuration fails in the same request, the system will automatically force the revocation of all modifications caused by the request, achieving a secure ‘all or nothing’ deployment guarantee.
• Validate: This capability indicates that the device has the ability to verify the legitimacy of configuration. Before configuring and distributing the application to the device, the system will automatically complete syntax checks and business logic validation. Therefore, in practical use, it is not necessary and not supported for the client to manually call a separate <validate> RPC command or carry the <test-option> parameter in <edit-config>.
• Distinct Startup: This capability indicates that the device has the ability to independently start the configuration library, that is, it can strictly distinguish between <running/> (current runtime library) and <startup/> (next startup loading library). Operations on the <running/> database will not be automatically synchronized to the <startup/> database. Users must explicitly perform the <copy-config> operation (copy <running/> to <startup/>) or call the <save-config> RPC to solidify the configuration.
• URL: This capability indicates that the device has the ability to use URL paths for configuration data transfer. The system supports carrying <uri> elements in<copy config>and<edit config>operations. The supported URL protocol types include file (local file), http, https, scp, sftp, ftp, etc., which greatly facilitates remote batch import and backup of configuration files.
• IETF-NETCONF-Monitoring: The system partially supports the RFC6022 monitoring standard. The client can use the <get> operation to query all currently supported Capability sets, Datastores, and all loaded YANG Schema lists (including identifiers, versions, formats, etc.) of the device. At the same time, it supports the client to call a dedicated <get-schema> RPC and directly download the specified YANG model file content from the switch to the local for parsing.
• AsterNOS Native Extended RPC Operation: In addition to standard capabilities, the system also supports a large number of private RPC for device operation and maintenance through the YANG model. For example:

<save-config>: Quickly save the current configuration.

<image-upgrade>: Support system image upgrade through remote path automation and the option to choose whether to retain the current configuration.

<clear-counters-interface> / <show-interface-summary> and so on: Perform fine-grained interface statistics cleaning and status diagnosis

3.2 RESTCONF

RESTCONF (RFC 8040) is a network management interface based on the HTTP/HTTPS protocol, which maps YANG data models to RESTful style web resources.

3.2.1 Message Structure

• Request Line: Contains standard HTTP verbs (operation methods) and precisely located URL paths. The operation methods correspond to GET (read), POST (create new resource or execute RPC action), PUT (replace completely), PATCH (local incremental update), and DELETE. URLs do not use traditional shell encapsulation, but directly point to specific resource instances in the runtime library (such as/rest/v1/running/interfaces/Ethernet1) or operational actions (such as/rest/v1/rpc/show version), achieving stateless operations directly to the target.
• Request Header: Carry web negotiation metadata and device authentication information. In addition to specifying the data interaction type (Content Type: application/json) and carrying a persistent API Token for secure and secret free authentication (in the format Authorization: Bearer {session-token}), as a standardized and complete HTTP communication, the actual message also needs to include basic negotiation headers such as Accept: */* and User Agent.
• Request Data / Body: The specific content of the resources to be issued or modified. Using pure JSON format as the data payload for requests and responses to enhance affinity with DevOps scripts such as Python and Ansible.

3.2.2 Basic Operations

• GET: Used to retrieve specified resources (configuration or status data) from the server. This is a read-only operation and will not change the device status.
• POST: It has a dual function. Firstly, it is used to create a new resource within a specified path (such as adding a new interface or route); Secondly, RPC actions used to call devices (such as POST/rest/v1/rpc/show version).
• PATCH: Used for making local modifications or updates to existing resources. The request payload only needs to include the attributes that need to be changed, and it will replace the original data.
• PUT: Used to replace the specified resource. Unlike PATCH, the payload of a PUT request must include a complete representation of all required attributes of the resource.
• DELETE: Used to delete specified resources. If attempting to delete a resource that no longer exists, the server will return 404 Not Found.

3.2.3 Core Capabilities

AsterNOS’ REST API is implemented based on the standard RESTCONF (RFC 8040) specification and optimized for automated operations scenarios. Its core capabilities are mainly reflected in the following aspects:

• Standard HTTP Operations and Resource Isolation: Use standard HTTP verbs (GET, POST, PUT, PATCH, DELETE) for network resource management. In terms of URL path design, data resources and operational resources are strictly isolated: the reading and modification of configuration and state data directly correspond to resources under the/rest/v1/running/path; And system level control actions (such as clearing table entries, system diagnostics, etc.) are uniformly encapsulated in the/reset/v1/rpc/path and triggered through POST requests.
• Stateless Interaction: In the architecture design of AsterNOS, both RESTCONF and NETCONF have the ability to bypass candidate database, go directly to the runtime database (<running/>), and take immediate effect. The core difference between the two at the bottom level lies in the communication state: NETCONF relies on SSH based Stateful Sessions, while RESTCONF adopts HTTP based stateless interaction mode. Each REST request is independent and lightweight, without the need to maintain session locks, greatly reducing the overhead of concurrent interactions, making it ideal for agile automation of CI/CD pipelines and rapid delivery of scripts.
• Unified pure JSON data payload: Mandatory and unique use of pure JSON format as the data payload for the request body and response body. By abandoning XML encoding, the system can be directly parsed by automated operation and maintenance tools such as Python and Ansible, as well as web front-end native parsing, without the need for additional format conversion.
• URL Path Compression and Query Filtering: To reduce the path complexity caused by the deep YANG model, the system introduces a path compression mechanism that automatically omits URL paths and redundant list nodes in JSON data when specific conditions are met. At the same time, the native support for depth query parameters is used to limit the hierarchical depth of resource retrieval (up to 10 levels can be parsed in depth), avoiding pulling too much invalid data at once.
• API Token Authentication Mechanism: Specially designed for automated program access. The system supports generating long-lasting API Tokens with specified expiration times. Automated scripts only need to carry the Bearer Token in the HTTP request header to call the interface, which improves script execution efficiency and reduces authentication overhead for continuous interaction.

3.3 gNMI

GNMI (gRPC Network Management Interface) is a network device management protocol based on gRPC, which supports configuration reading and modification, as well as real-time collection of device status data in a streaming manner. It is an important interface for network telemetry and automation. Based on the gRPC (HTTP/2) framework, the underlying layer adopts efficient Protobuf binary transmission and JSON/JSON_iETF encoding.

3.3.1 Message Structure

• gRPC Metadata: Provide a low-level communication and security framework for gNMI. GNMI uses TLS (HTTP/2) for encrypted transmission, and clients do not need to configure complex certificate verification. However, they need to carry plaintext username and password credentials in gRPC Metadata and send them to the switch for authentication.
• RPC Method: Defined specific gNMI protocol actions initiated by the client. AsterNOS fully supports the four core methods defined by the standard: Capabilities, Get, Set, and Subscribe.
• Data Payload: Defined the specific objectives and business data of the operation. The target path adopts a format similar to XPath and strictly applies the “Path Compression” rule. When configuring Set or subscribing to data push, the specific numerical payload will be encoded in JSON, JSON_iETF, or underlying GPB (Protocol Buffers) binary format, nested in gRPC packets for high-speed transmission.

3.3.2 Basic Operations

• Capabilities: Used to discover and obtain all YANG model sets currently supported on the target device, as well as the gNMI protocol version information currently running.
• Get: Used to retrieve configuration data and/or operational status data for one or more target data tree paths from the device.
• Set: Used to create, update, replace, or delete configurations on the target device. A Set request can include a combination of update, replace, and delete operations for different paths.
• Subscribe: Used to implement streaming subscriptions for network data. The client can subscribe to specific YANG data paths and require the device to push real-time updates or actively report the device’s operating status and statistical data according to a specified schedule interval when data changes occur.

3.3.3 Core Capabilities

• Streaming Telemetry: With the help of the Subscribe operation, AsterNOS has achieved a revolutionary transformation from the traditional SNMP “Pull” mode to the modern “Push” mode. The device can actively push time-series data such as network status changes and traffic counts to remote data collectors with extremely high accuracy (such as nanoseconds), and seamlessly integrate with modern observability tool stacks such as Prometheus and Grafana, providing real-time network views and monitoring charts.
• Flexible JSON/JSON_iETF/GPB Encoding Support: GNMI provides multiple payload encodings for different interaction scenarios. When configuring distribution or regular queries, support simple and easy to read JSON or strictly follow the JSON IETF format specified in RFC 7951; When executing high-frequency Subscribe telemetry push, it supports the use of GPB binary format with extremely high compression rate to carry massive data, achieving ultimate performance.
• Stateless Configuration & Path Compression: In addition to serving as a telemetry engine, gNMI also supports stateless configuration issuance and complete replacement of devices through Set operations. At the same time, to ensure the absolute stability of the underlying configuration processing, the system requires that each configuration request must be accurately and uniquely located on a single target path, rejecting ambiguous batch mixing operations, thereby ensuring the safety boundary and predictability of each automated change.

4. Horizontal Comparison and Selection Guide for the Three Protocols

NETCONF (Absolute Transaction Security for Configuration): Suitable for issuing complex network policies across devices and synchronizing the status of the entire network. It is based on SSH’s stateful connection and built-in Rollback-on-Error mechanism, which can ensure the forced revocation of modifications in the event of local node configuration failure, ensuring strong consistency boundaries for network changes.

RESTCONF (Agile Cross System Integration): Suitable for quick integration with CI/CD automated pipelines, DevOps scripts (such as Ansible, Python), and cloud management platforms. Its stateless interaction mode and pure JSON payload eliminate the need to maintain complex session locks on the device side, greatly reducing the development threshold and concurrent interaction overhead of external systems.

gNMI (High Performance State Monitoring and Telemetry): Suitable for high-frequency state collection in modern cloud native environments. The active push mechanism of its Streaming Telemetry is a core protocol that replaces traditional SNMP passive polling and seamlessly integrates with observability tool stacks such as Prometheus or Grafana.