In the world of data model-driven management, what is important is the set of YANG data modules from which APIs are deduced. Indeed, from a high level point of view, I see data models as APIs.
From an architecture point of view, there are multiples API locations, all deduced from YANG modules. A controller typically configures network elements (routers, switches) based on the Network Element YANG modules: typically interfaces, routing, QoS, etc.). Note that, in the NETCONF and RESTCONF terminologies, the controller is the client and the network elements the server, as the controller initiates the configuration session. Similarly, the orchestrator configures one or more controllers based on the network YANG modules APIs: typically a layer 3 VPN. And finally, operators can access the orchestrator north-bound interface to manage their services (based on the service delivery YANG modules). More details on the different YANG module types in the YANG Module Classification [RFC 8199] and the soon-to-be-published Service Modules Explained [RFC 8309] IETF draft.
The next picture shows a YANG data module on the left and RESTCONF RPCs to edit the associated resources on the right. The color scheme shows how to build the RESTCONF GET, POST, PUT, and DELETE methods from the YANG module, and we see that YANG keywords provide all the needed information.
The APIs for different programming language are deduced from the data models thanks to tooling. For example, the YANG Development Kit (YDK) offers python and C++ bindings. And once you deal with python or C++ APIs, whether the encoding is based on XML or JSON is completely irrelevant.
Extending this thought, we could say that the protocol choice, RESTCONF, NETCONF or even gRPC, doesn’t matter. Well, in fact, there are capability differences between the different protocols. This article focuses on the differences between the two standard protocols: NETCONF and RESTCONF (a following blog will focus on gRPC).
The Protocol NETCONF protocol [RFC6241] provides mechanisms to install, manipulate, and delete the configuration of network devices. It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages. The NETCONF protocol operations are realized as remote procedure calls (RPCs).
While the NETCONF protocol should be known by now [RFC6241], let’s say a few words about the newly specified RESTCONF protocol. RESTCONF, specified by the IETF [RFC8040], specifies an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in the Network Configuration Protocol (NETCONF). Quoting the “Subset of NETCONF Functionality” section from the RFC:
RESTCONF does not need to mirror the full functionality of the
NETCONF protocol, but it does need to be compatible with NETCONF.
RESTCONF achieves this by implementing a subset of the interaction
capabilities provided by the NETCONF protocol — for instance, by
eliminating datastores and explicit locking
RESTCONF uses HTTP methods to implement the equivalent of NETCONF
operations, enabling basic CRUD operations on a hierarchy of
The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data
resources represented by YANG data models. These basic edit
operations allow the running configuration to be altered by a
RESTCONF is not intended to replace NETCONF, but rather to provide an
HTTP interface that follows Representational State Transfer (REST)
principles and is compatible with the NETCONF datastore model.
So what are the technical differences between NETCONF and RESTCONF?
- First of all, RESTCONF supports XML or JSON as an encoding, but as I mentioned before, this might be a detail.
- The NETCONF capabilities allows to discover all the NETCONF server capabilities: NETCONF version, datastore, YANG modules, feature, and deviation. YANG1.1 requires that a NETCONF server announces the modules it implements with the YANG module “ietf-yang-library” [RFC7895]. With RESTCONF, the server reports each YANG modules, deviations, features it supports using the “ietf-yang-library” YANG module, defined YANG Module Library [RFC7895].
- With the NETCONF capabilities in mind, the natural service automation flow is the NETCONF <lock> operation (on the running data store), editing the configuration in the candidate configuration datastore, validate the configuration, then the commit operation (to apply the configuration in the candidate datastore to the running data store), and finally the unlock operation. These transactions are done for the multiple devices, from an orchestrator, to achieve network wide transaction, as a two-phase commit transaction. RESTCONF doesn’t provide the notion of lock, of candidate config and commit: the configuration changes are directly applied. Therefore, RESTCONF does not provide for distributed transactions, but only device-by-device configuration. The two-phase commit transaction is not possible with RESTCONF.
Note1: this two-phase commit is mostly important when configuring services across network elements, so between the controller and network elements. On the orchestrator north-bound interface, a single RESTCONF request with all service parameters is perfectly fine: the request is atomic.
- Three-phase transaction, available in NETCONF, is basically a two-phase commit and a confirmed-commit. Since RESTCONF does not even support a two-phase commit, RESTCONF obviously doesn’t support the three-phase transaction.
- The NETCONF <get> operation gets the running configuration and operational data, and the NETCONF <get-config> operation is used to get configuration data from a specified datastore (e.g. candidate). With RESTCONF the non-configuration part can be retrieved by the ‘content’ query parameter to “nonconfig”. The value could be “config”, “nonconfig” and “all”. The “all” is the equivalent of NETCONF <get>. In this regard, RESTCONF can provide more fine-grained access.
- The RESTCONF protocol has no concept of transaction. A RESTCONF call is a transaction by itself, as it uses the HTTP POST, PUT, PATCH, and DELETE methods are used to edit data resources represented by YANG data models.
- RESTCONF lacks any way of validating without activating a configuration. However, the validation is implicit, part of the RESTCONF calls, which suceeds or fails.
- With NETCONF, SSH sessions are established from the NETCONF client to the NETCONF server, and that might imply many concurrent SSH sessions. It’s also worth nothing that the SSH handshakes take some time for the establishment. RESTCONF is based on HTTPS.
- And finally, RESTCONF does not provide the <copy-config> capability, available for NETCONF
Next to the technical differences, a tooling issue!
It’s a little bit over-simplistic to think that, if you’re a Web developer, you “just” select RESTCONF as the protocol, as opposed to NETCONF. However, I want to stress the importance of tooling. Automation in general, and specifically network configuration, implies the integration of an entire tool chain. And if the existing tool chain (for example, storage and compute) is centered around HTTP, the RESTCONF option might be best one. In the end, it’s all about seamless integration.
Operators will anyway decide for themselves but they should take an informed decision, let’s provide the information in a different format, based on their documented requirements [RFC3535]. This RFC is 14 years old, but the operational requirements in that RFC are still valid today. This spreadsheet below mainly compares how NETCONF and RESTCONF fulfill the RFC 3535 operational requirements. Some requirements (like the first one) don’t really offer a clear winner though.
|RFC 3535 Requirement||NETCONF||RESTCONF|
|1. Ease of use is a key requirement for any network management technology from the operators point of view.||The NETCONF capabilities allows to discover all the NETCONF server capabilities: NETCONF version, datastores, supported YANG models, feature, deviation. YANG1.1 requires that A NETCONF server announce the modules it implements with the YANG module “ietf-yang-library”||With RESTCONF, the server lists each YANG modules, deviations, features it supports using the “ietf-yang-library” YANG module, defined in ietf-netconf-yang-library.|
|2. It is necessary to make a clear distinction between configuration data, data that describes operational state and statistics. Some devices make it very hard to determine which parameters were administratively configured and which were obtained via other mechanisms such as routing protocols.||See the Network Management Datastore Architecture.||With RESTCONF the non-configuration part can be retrieved the ‘content’ query parameter to “nonconfig”. The value could could be “config”, “nonconfig” and “all”. The “all” is the equivalent of NETCONF <get>. In this regard, RESTCONF can provide more fine-grained access.
See also the Network Management Datastore Architecture.
|3. It is required to be able to fetch separately configuration data, operational state data, and statistics from devices, and to be able to compare these between devices.||The <get> operation to get the running configuration and operational data and the <get-config> operation can be used to get configuration data from a specified datastore (e.g. candidate)||The HTTP GET is used to match both <get-config> and <get> NETCONF operations. With RESTCONF the “content” query parameter is used to specify the type of data to fetch (“config”, “nonconfig” or “all”).|
|4. It is necessary to enable operators to concentrate on the configuration of the network as a whole rather than individual devices.||The natural flow is the NETCONF lock operation (on the running data store), editing the config in the candidate configuration datastore, validate the configuration, then the commit operation (to apply the config in the candidate datastore to the running data store), and finally the unlock operation . Reference: RFC6241. These transactions are done for the multiple devices, from an orchestrator, to achieve network wide transaction, as a two-phase commit transaction||Since RESTCONF does not provide for distributed transactions (see item 5 below), it only provides device-by-device configuration. The network wide configuration is possible with RESTCONF, but without two-phase commit transaction.|
|5. Support for configuration transactions across a number of devices would significantly simplify network configuration management.||See requirement 4. The NETCONF protocol has the concept of transaction. Reference: RFC6241. These transactions are done for the multiple devices, from an orchestrator, to achieve network wide transaction, as a two-phase commit transaction||The RESTCONF protocol has no concept of transaction. A RESTCONF call is a transaction by itself, as it uses the HTTP POST, PUT, PATCH, and DELETE methods are used to edit data resources represented by YANG data models. However, (here is no concept of transactions across RESTCONF calls.|
|6. Given configuration A and configuration B, it should be possible to generate the operations necessary to get from A to B with minimal state changes and effects on network and systems. It is important to minimize the impact caused by configuration changes.||NETCONF has the concept of datastores: candidate (working copy to manipulate with no impact on the current configuration, for prevalidate), running (complete and active configuration), startup (configuration loaded by the device at startup). We could do a diff between those datastores. Note that the datastores are implemented on the NETCONF server. Reference: RFC6241||RESTCONF uses the datastores defined in NETCONF. However, there are implied rules in terms of transaction see https://tools.ietf.org/html/rfc8040#section-1.4 , and hence no possibility to do configuration differences on a RESTCONF server|
|7. A mechanism to dump and restore configurations is a primitive operation needed by operators. Standards for pulling and pushing configurations from/to devices are desirable.||Yes, with we can dump configuraton with the NETCONF commit operation. The restore can be done thanks to the rollback-on-error capability implementation on the NETCONF server. Reference: https://tools.ietf.org/html/rfc6241#section-8.5. If a NETCONF peer supports the :url capability (Section 8.8), the <url> element can appear as the <source> or <target> parameter, and entire configuration can be copied.||The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data resources represented by YANG data models. These basic edit operations allow the running configuration to be altered in an all-or-none fashion. This is similar to the “rollback-on-error” capability in NETCONF. Edits are usually applied to one data resource instance at a time. Reference: https://tools.ietf.org/html/rfc8040#section-1.2 Note that RESTCONF also supports getting and loading of full configs.|
|8. It must be easy to do consistency checks of configurations over time and between the ends of a link in order to determine the changes between two configurations and whether those configurations are consistent.||The NETCONF validate operation validates the content of a candidate datastore||There is no validate RESTCONF operation. However, the validation is implicit, part of the RESTCONF calls, which suceeds or fails.|
|9. Network wide configurations are typically stored in central master databases and transformed into formats that can be pushed to devices, either by generating sequences of CLI commands or complete configuration files that are pushed to devices. There is no common database schema for network configuration, although the models used by various operators are probably very similar. It is desirable to extract, document, and standardize the common parts of these network wide configuration database schemas.||YANG models define the schema for network configuration, hence migrating to NETCONF/YANG enables carriers to standardise their schemas. As YANG models are standardised in the IETF the schemas then will be standardised across vendors, and across carriers.||RESTCONF is YANG-modelled (like NETCONF/YANG) and hence the same comments apply here.|
|10. It is highly desirable that text processing tools such as diff, and version management tools such as RCS or CVS, can be used to process configurations, which implies that devices should not arbitrarily reorder data such as access control lists.||As noted in question 8….|
|11. The granularity of access control needed on management interfaces needs to match operational needs. Typical requirements are a role-based access control model and the principle of least privilege, where a user can be given only the minimum access necessary to perform a required task.||NACM – RFC 6536||NACM is supported as RESTCONF maps to NETCONF|
|12. It must be possible to do consistency checks of access control lists across devices.|
|13. It is important to distinguish between the distribution of configurations and the activation of a certain configuration. Devices should be able to hold multiple configurations.||NETCONF supports a commit operation, to active the candidate datastore configuration (note that there is a single configuration in the candidate data store). NETCONF permits the operator to specify the target datastore for an operation – typically only 3 datastores are provided (startup, running and candidate), however the copy-config command may use a URL as the source or target if the NETCONF server implements the :url capability.||RESTCONF configuration changes are automatically activated with each RESTCONF call. In order to make multiple configuration changes in the same transaction those changes must be aggregated into a single RESTCONF call. RESTCONF calls map to specific NETCONF datastores and there are implicit rules regarding the datastore operations (See https://tools.ietf.org/html/draft-ietf-netconf-restconf-09#section-1.3). There is no equivalent of copy-config in RESTCONF. There is no way to do a config diff between different datastore in RESTCONF.|
|14. SNMP access control is data-oriented, while CLI access control is usually command (task) oriented. Depending on the management function, sometimes data-oriented or task-oriented access control makes more sense. As such, it is a requirement to support both data-oriented and task-oriented access control.||NACM – RFC 6536.||NACM – RFC 6536.|
In summary, even if the negative marks against RESTCONF are resolvable (*), when you have the choice, NETCONF should be used for network elements configuration , while RESTCONF might be fine as the north-bound interface of the orchestrator or/and controller.
(*) For example, we added datastores to RESTCONF. However, my view has always been: if you want capabilities similar to NETCONF, well use NETCONF 🙂
Nice succinct summary !!
Thanks a lot for this work Benoît, it is very detailed and it is very helpful !
Thank you for the clear suggestion!