Create the YAML definition for extracting operational data.
Retrieving operational data allows you to extract useful running-state data from the device. For example, you can configure an interface to be in OSPF. The status of that interface neighbor relationship (for example, show ospf neighbors) is the operational data.
Rather than requiring you to code the specific Junos OS or XML commands and extract the various bits of data, you can define a simple YAML file that instructs the framework what to do.
The following is an example that corresponds to the Junos OS CLI command to display the interface media data for all Ethernet interfaces (ae*, fe*, ge*, and xe*):
show interfaces media "[afgx]e*"
You can choose to call your table definition anything you want. The above example on line 2 defines the name as EthPortTable. Your YAML file can contain multiple table definitions (as well as views). The JunosPyEZ loader assumes that anything you define starting at the first column in the text file (like EthPortTable) will be a new widget definition (table, view, and so on). Your YAML file can contain multiple widget definitions.
EthPortTable: rpc: get-interface-information
Every Junos command has a corresponding XML based Remote Procedure Call (RPC). You can view this RPC definition directly on the Junos CLI using the "pipe display" filter, as illustrated:
jeremy@junos> show interfaces media "[afgx]e*" | display xml rpc
The XML tag immediately following the <rpc> element is the RPC command tag. In this case the tag-name is <get-interface-information>. You can see that this tag-name is used in the example YAML (highlighted) identified by rpc property. You simply provide the tag-name text without the angle brackets.
rpc: get-interface-information args:
In some cases, you will want to include default arguments to the command, such as values you do not want the user to have to specify. In this example we always want to include the "media" flag and default the "interface-name" field to the set of values to retrieve the Ethernet ports. You do this by including the optional args property in the YAML definition:
Pay special attention to the fact that these defaults are indented under the args keyword. If a default arg is a flag, like media, then simply set the value to True. Otherwise set it to the value you want. You can see that we replace dashes (-) with underscores (_) in hyphenated names like interface-name.
Some commands can take an optional first argument that does not require a specific keyword. If you look at the Junos OS CLI show interfaces command, for example, you'll see an example where the first argument could be the interface name:
jeremy@junos> show interfaces ?
<[Enter]> Execute this command
<interface-name> Name of physical or logical interface
ge-0/0/0 management port
If you want your YAML definition to make use of this so that the caller of the table can retrieve operational data without specifying the keyword explicit (to mimic the CLI behavior), then you can define the args_key property in your YAML:
Each table item represents a "record" of data. You need to define the XML XPath that identifies the record container, in other words, the thing that contains the fields of data you want to extract. For the case of the "show interfaces" command, we want to identify each interface as the unique record.
To identify the XML XPath, you can examine the Junos OS command results in XML using the pipe display, as illustrated. The following output has been edited for brevity. You know you want the physical information information, so this XML item is highlighted below:
jeremy@junos> show interfaces media "[afgx]e*" | display xml
When Junos PyEz extracts the data from the table, the XPath expression is relative to the top-level element immediately following the <rpc-reply> tag. In this case the XPath is relative from <interface-information>. From that point of reference, the XPath expression to select each physical interface is simply: physical-interface. You identify the table-item XPath in the YAML definition using the itemproperty:
Each table item needs a unique identifier so that the user of the table can select the record by name. Junos OS conventionally uses the XML element-tag <name> for this purpose, but in many instances a different element tag is used. If table-item uses this <name> tag, then you do not need to define a specific key, name is the default. If you need to identify a different item-key tag, you can use the key property.
For example, consider the show route command. If we wanted to create a table of route entries, the associated YAML would look like the following:
I will leave it as an exercise for the reader to examine the specific Junos OS XML command and response output.
Some tables also take multiple key values. When this is the case, the key property must be defined as a list. Here is a snippet of the YAML for extracting LACP status. You can find the complete example in the Junos PyEZ library (op/lacp.yaml):
# Each LACP port maintains a "state" table that ha a composite key of the
# interface name and it's role (Actor/Partner). name with the "_" so this
# item does not get exported to the global namespace
(REQUIRED, sort of)
The table view property identifies the View widget that maps your field-name definitions to the XML or XPath in each record. The topic of creating a View widget is discussed in a separate reference article (TBD).
Generally speaking, you will always associate a view to a table, since that's really the way to make accessing data easy. If you do not specify a view, then when the caller selects a table item, they will be given the XML data (lxml). They would then have to extract fiel -data manually using a standard lxml programming technique.
The following table summarizes the operational table property definitions:
Required / Optional
Default RPC command arguments so the called doesn't have to always specify these.