Recently I had a need to do some automation against a group of IOS-XE routers and decided I’d like to take another look at using the RESTCONF API that is offered by the devices. In this post, I’ll show how Cisco YANG Suite can help reduce the development effort when working with YANG models and RESTCONF.
Translating YANG Models to RESTCONF
One of the main challenges for me with using RESTCONF in the past has been figuring out the required URL and payload for the requests. For example, a RESTCONF URL to retrieve the configuration of interface GigabitEthernet1 on a router looks like this: /data/ietf-interfaces:interfaces/interface=GigabitEthernet1, but how are the components of that URL built? Cisco’s Hank Preston wrote a very thorough and helpful blog post that explains how the YANG tree is mapped into a URL, and it is a great reference to gain further understanding.
Even with an understanding of how the URL and payloads are built from the YANG models, the process of figuring them out involves downloading, examining, and interpreting manually the YANG model file(s) for the particular feature you are trying to work with on the router. For me there was always a painful and usually time-consuming process of inspecting YANG model(s) in a text editor, and then going through trial and error until I finally managed to build the correct URL and payload to configure a feature. I thought, if only the router had a Swagger API documentation page that provided the URL and required payload like other APIs I have worked with, things would be so much easier!
Cisco YANG Suite is a tool that can provide that functionality and more! In this post, I’ll first explain how to get up and running quickly with Cisco YANG Suite. Then I’ll walk through an example scenario of using YANG Suite to automatically generate the appropriate RESTCONF calls, eliminating the need to open and interpret any YANG model files in a text editor.
Installing YANG Suite
Cisco YANG Suite can be run as a Docker container locally on your machine, which requires that you have Docker Desktop installed. For other installation options, please see the YANG Suite documentation. The first step is downloading the code to your machine from the GitHub repository. The best way to do that is with the Git command line utility, using the command:
git clone https://github.com/CiscoDevNet/yangsuite/
You will now have a yangsuite directory. Change to the directory yangsuite/docker. Here you will find the setup script start_yang_suite.sh. Execute the script to begin setup.
$ ./start_yang_suite.sh
Hello, please setup YANG Suite admin user.
username: admin
password:
confirm password:
email: matt.mullen@networktocode.com
The script prompts for definition of superuser credentials and asks whether you want to generate “test” certificates. Test certificates are self-signed certificates that are used for SSL and are automatically generated by the script. Since we are only using YANG Suite on the local machine, self-signed certificates will be fine here.
Setup test certificates? (y/n): y
################################################################
## Generating self-signed certificates... ##
## ##
## WARNING: Obtain certificates from a trusted authority! ##
## ##
## NOTE: Some browsers may still reject these certificates!! ##
################################################################
Generating a 2048 bit RSA private key
......................................................+++
.......+++
writing new private key to 'nginx/nginx-self-signed.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) []:US
State or Province Name (full name) []:NC
Locality Name (eg, city) []:Raleigh
Organization Name (eg, company) []:Network to Code
Organizational Unit Name (eg, section) []:
Common Name (eg, fully qualified host name) []:
Email Address []:
Certificates generated...
Building docker containers...
Once you enter the certificate details, the containers begin launching. The containers will be running interactively in your terminal, so you must leave the terminal window where you ran the script open. Once the activity in the terminal has stopped scrolling, the containers should be running and YANG Suite will be available at the URL: https://localhost:8443.
Upon accessing the above URL for the first time, you will be prompted to accept the YANG Suite License and Privacy statement. Assuming you agree to the legal mumbo jumbo, click Accept and log in with the superuser credentials you defined during the setup script.
Upon successful login, you will be at the Welcome screen.
YANG Suite Initial Setup
There are a few one-time setup tasks that we must do in order to begin using YANG Suite:
- Define a Device Profile
- Create a YANG Module Repository
- Create a YANG Module Set
The examples in this post are using the IOS-XE Always-On sandbox, which consists of a CSR1000V router with programmability features such as
NETCONFandRESTCONFenabled and ready for use. You can find the credentials and other related information in the IOS-XE Always-On DevNet Sandbox.
Device Profile
The first thing we need to do is download YANG models to work with. This can be accomplished by either uploading the YANG models from your system, or by downloading them from an existing device on the network. We’ll go ahead and download the models from the router in the IOS-XE Always-On sandbox (https://sandbox-iosxe-latest-1.cisco.com). To do that, we will create a Device Profile.
Click on Setup > Device Profiles and then Create New Device. Then enter the details for the IOS XE sandbox:
Ignore the “Invalid IP Address” error when entering the hostname into the Address field. This appears to be a bug.
It is also necessary to scroll down and enable the NETCONF and RESTCONF protocols. Make sure to check the Skip SSH key validation for this device checkbox under the NETCONF section. Once complete, click Create Profile.