Normalize description in arista_eos and cisco_ios show interfaces (ne…

…tworktocode#1582) * add data model documentation * data model docs - finish usage description for IP_ADDRESSES * arista_eos - normalize DESCRIP to DESCRIPTION * cisco_ios - normalize DESCRIP to DESCRIPTION
mjbear · Jan 7, 2024 · f84de78 · f84de78
1 parent ab7787a
commit f84de78
Show file tree

Hide file tree

Showing 6 changed files with 144 additions and 94 deletions.
diff --git a/docs/dev/data_model.md b/docs/dev/data_model.md
@@ -0,0 +1,44 @@
+# Goals
+
+- The table below becomes an evolving reference of common capture group names
+- Normalize common capture groups across templates (including cross-vendor)
+
+# Reasoning
+
+Normalized capture group names enable more predictable structured data across templates where similar data exists.
+
+Example: Imagine the extra programming logic needed to consume structured data when capture groups could have two or more names across several templates or several vendors! Yikes! This is why we seek to normalize.
+
+# Considerations
+
+- Some capture groups are a single value and others are lists of values despite containing similar data as one another
+    - Example: single IP address vs list of IP addresses
+- Normalizing and using standard capture group names will take time, persistence, and patience from the community
+- Other than new templates, these normalization changes modify the expected template output and are considered "breaking changes" to be included in version releases
+
+# Common Capture Groups
+
+| Capture Group      | Usage Description |
+|--------------------|:------------------|
+| `BIA`              | use this if the template already has MAC_ADDRESS in use for the active MAC address |
+| `DESCRIPTION`      | often used for port or interface descriptions |
+| `GATEWAY`          | gateway address for a subnet |
+| `INTERFACE`        | full word instead of IFACE, INTF, INTFC, etc |
+| `IP_ADDRESS`       | for a single IP address, often IPv4 |
+| `IP_ADDRESSES`     | for lists of IPv4 addresses, but in the case of some templates there may be a mix of IP protocol versions |
+| `IP_HELPER`        | for lists DHCP IP helper addresses |
+| `IP_VERSION`       | Internet Protocol (IP) version in the case of multiple versions appearing in output (use where necessary) |
+| `IPV6_ADDRESS`     | for a single IPv6 address |
+| `IPV6_ADDRESSES`   | for lists of IPv6 addresses |
+| `IPV6_GATEWAY`     | for IPv6 gateway address |
+| `LOCAL_IP_ADDRESS` | local IP address in the case of First Hop Redundancy Protocols (FHRP)
+| `MAC_ADDRESS`      | instead of MAC or MACADDR |
+| `MGMT_IP_ADDRESS`  | instead of MGMT_IP or MGMT_ADDRESS or MANAGEMENT_IP or REMOTE_MANAGEMENT_ADDRESS |
+| `NEIGHBOR_ID`      | for router IDs remote to the system being parsed |
+| `NETMASK`          | for IPv4 dotted quad masks |
+| `NETWORK`          | for network numbers or subnet address (without the mask or prefix/slash notation); in place of ROUTE |
+| `PREFIX_LENGTH`    | instead of PREFIX or CIDR for the numbers of a slash notation or CIDR mask |
+| `PROTOCOL`         | instead of PROTO |
+| `ROUTER_ID`        | for local router IDs (local to the device being parsed) |
+| `VLAN_ID`          | instead of VLAN or TAG |
+| `VLAN_NAME`        | VLAN name or description |
diff --git a/docs/dev/dev_parser.md b/docs/dev/dev_parser.md
@@ -42,6 +42,12 @@ Start
   ^${TIME}\s+${TIMEZONE}\s+${DAYWEEK}\s+${DAY}/${MONTH}/${YEAR} -> Record
   ^. -> Error
 ```
+
+!!! tip
+    Use [standard capture group names](https://github.com/networktocode/ntc-templates/blob/master/docs/dev/data_model.md) where possible to achieve a level of normalization.
+
+    If templates you are creating or editing have capture groups that might be in common with others, please check other templates for similar capture groups as there might already be one in use. If you have a suggestion for a standard capture group name, suggest the change(s) to Network to Code for discussion and consideration.
+
 ### States
 
 If the raw output has a heading, the `Start` state should match on the column headings and then transition to another state that will match the device's output table with the capture groups. This helps ensure the regex patterns for the capture groups are attempting to match the correct information, and allows templates to easily add additional States for tables that have different headings. 
@@ -276,4 +282,4 @@ Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)
 LOCAL - Running command yamllint .
 
 [... skipping remaining output for brevity ...]
-```
+```
diff --git a/ntc_templates/templates/arista_eos_show_interfaces_description.textfsm b/ntc_templates/templates/arista_eos_show_interfaces_description.textfsm
@@ -1,7 +1,7 @@
 Value PORT (\S+)
 Value STATUS (up|down|admin\s+down)
 Value PROTOCOL (up|down|lowerlayerdown|notpresent|unknown)
-Value DESCRIP (\S.*?)
+Value DESCRIPTION (\S.*?)
 
 Start
   ^Interface\s+Status\s+Protocol\s+Description\s*$$ -> Begin
@@ -12,6 +12,6 @@ Start
   ^. -> Error
 
 Begin
-  ^${PORT}\s+${STATUS}\s+${PROTOCOL}(?:\s+${DESCRIP})?\s*$$ -> Record
+  ^${PORT}\s+${STATUS}\s+${PROTOCOL}(?:\s+${DESCRIPTION})?\s*$$ -> Record
   ^\s*$$
   ^. -> Error
diff --git a/ntc_templates/templates/cisco_ios_show_interfaces_description.textfsm b/ntc_templates/templates/cisco_ios_show_interfaces_description.textfsm
@@ -1,7 +1,7 @@
 Value PORT (\S+)
 Value STATUS (up|down|deleted|admin\s+down|reset)
 Value PROTOCOL (up|down)
-Value DESCRIP (\S.*?)
+Value DESCRIPTION (\S.*?)
 
 Start
   ^Interface\s+Status\s+Protocol\s+Description\s*$$ -> Begin
@@ -12,6 +12,6 @@ Start
   ^. -> Error
 
 Begin
-  ^${PORT}\s+${STATUS}\s+${PROTOCOL}(?:\s+${DESCRIP})?\s*$$ -> Record
+  ^${PORT}\s+${STATUS}\s+${PROTOCOL}(?:\s+${DESCRIPTION})?\s*$$ -> Record
   ^\s*$$
   ^. -> Error
diff --git a/tests/arista_eos/show_interfaces_description/arista_eos_show_interfaces_description.yml b/tests/arista_eos/show_interfaces_description/arista_eos_show_interfaces_description.yml
@@ -1,82 +1,82 @@
 ---
 parsed_sample:
-  - port: "Et1"
-    status: "admin down"
+  - description: "ThiS iS a TeSt DeScriPtiON"
+    port: "Et1"
     protocol: "down"
-    descrip: "ThiS iS a TeSt DeScriPtiON"
-  - port: "Et2"
-    status: "up"
+    status: "admin down"
+  - description: "ThiS iS a TeSt DeScriPtiON"
+    port: "Et2"
     protocol: "up"
-    descrip: "ThiS iS a TeSt DeScriPtiON"
-  - port: "Et3"
     status: "up"
+  - description: "ThiS iS a TeSt DeScriPtiON"
+    port: "Et3"
     protocol: "up"
-    descrip: "ThiS iS a TeSt DeScriPtiON"
-  - port: "Et4"
     status: "up"
+  - description: "ThiS iS a TeSt DeScriPtiON"
+    port: "Et4"
     protocol: "up"
-    descrip: "ThiS iS a TeSt DeScriPtiON"
-  - port: "Et5"
-    status: "admin down"
+    status: "up"
+  - description: "ThiS iS a TeSt DeScriPtiON"
+    port: "Et5"
     protocol: "down"
-    descrip: "ThiS iS a TeSt DeScriPtiON"
-  - port: "Et6"
     status: "admin down"
+  - description: "ThiS iS a TeSt DeScriPtiON"
+    port: "Et6"
     protocol: "down"
-    descrip: "ThiS iS a TeSt DeScriPtiON"
-  - port: "Et7"
     status: "admin down"
+  - description: "ThiS iS a TeSt DeScriPtiON"
+    port: "Et7"
     protocol: "down"
-    descrip: "ThiS iS a TeSt DeScriPtiON"
-  - port: "Et8"
     status: "admin down"
+  - description: "ThiS iS a TeSt DeScriPtiON"
+    port: "Et8"
     protocol: "down"
-    descrip: "ThiS iS a TeSt DeScriPtiON"
-  - port: "Et9"
-    status: "up"
+    status: "admin down"
+  - description: "ThiS iS a TeSt DeScriPtiON"
+    port: "Et9"
     protocol: "up"
-    descrip: "ThiS iS a TeSt DeScriPtiON"
-  - port: "Et9.999"
-    status: "down"
-    protocol: "lowerlayerdown"
-    descrip: ""
-  - port: "Et10"
     status: "up"
+  - description: ""
+    port: "Et9.999"
+    protocol: "lowerlayerdown"
+    status: "down"
+  - description: "ThiS iS a TeSt DeScriPtiON"
+    port: "Et10"
     protocol: "up"
-    descrip: "ThiS iS a TeSt DeScriPtiON"
-  - port: "Et11"
     status: "up"
+  - description: "ThiS iS a TeSt DeScriPtiON"
+    port: "Et11"
     protocol: "up"
-    descrip: "ThiS iS a TeSt DeScriPtiON"
-  - port: "Et12"
     status: "up"
+  - description: "ThiS iS a TeSt DeScriPtiON"
+    port: "Et12"
     protocol: "up"
-    descrip: "ThiS iS a TeSt DeScriPtiON"
-  - port: "Et13"
-    status: "down"
+    status: "up"
+  - description: "This IS a TesT DeScrIption"
+    port: "Et13"
     protocol: "notpresent"
-    descrip: "This IS a TesT DeScrIption"
-  - port: "Et14"
     status: "down"
+  - description: ""
+    port: "Et14"
     protocol: "notpresent"
-    descrip: ""
-  - port: "Ma1"
     status: "down"
+  - description: "Management"
+    port: "Ma1"
     protocol: "down"
-    descrip: "Management"
-  - port: "Po1"
-    status: "up"
+    status: "down"
+  - description: "MLAG peer link"
+    port: "Po1"
     protocol: "up"
-    descrip: "MLAG peer link"
-  - port: "Po101"
     status: "up"
+  - description: "ServerRAD"
+    port: "Po101"
     protocol: "up"
-    descrip: "ServerRAD"
-  - port: "Tu8"
-    status: "down"
-    protocol: "unknown"
-    descrip: ""
-  - port: "Vl4094"
     status: "up"
+  - description: ""
+    port: "Tu8"
+    protocol: "unknown"
+    status: "down"
+  - description: "MLAG local int"
+    port: "Vl4094"
     protocol: "up"
-    descrip: "MLAG local int"
+    status: "up"
diff --git a/tests/cisco_ios/show_interfaces_description/cisco_ios_show_interfaces_description.yml b/tests/cisco_ios/show_interfaces_description/cisco_ios_show_interfaces_description.yml
@@ -1,62 +1,62 @@
 ---
 parsed_sample:
-  - port: "Vl1"
-    status: "admin down"
+  - description: ""
+    port: "Vl1"
     protocol: "down"
-    descrip: ""
-  - port: "Vl99"
-    status: "up"
+    status: "admin down"
+  - description: "10.20.99.0_Switch_mgmt_VLAN"
+    port: "Vl99"
     protocol: "up"
-    descrip: "10.20.99.0_Switch_mgmt_VLAN"
-  - port: "Gi0/1"
-    status: "down"
+    status: "up"
+  - description: "D3 USER"
+    port: "Gi0/1"
     protocol: "down"
-    descrip: "D3 USER"
-  - port: "Gi0/2"
     status: "down"
+  - description: "D3 USER"
+    port: "Gi0/2"
     protocol: "down"
-    descrip: "D3 USER"
-  - port: "Gi0/3"
     status: "down"
+  - description: "D3 USER"
+    port: "Gi0/3"
     protocol: "down"
-    descrip: "D3 USER"
-  - port: "Gi0/4"
     status: "down"
+  - description: "D3 USER"
+    port: "Gi0/4"
     protocol: "down"
-    descrip: "D3 USER"
-  - port: "Gi0/5"
     status: "down"
+  - description: "D3 USER"
+    port: "Gi0/5"
     protocol: "down"
-    descrip: "D3 USER"
-  - port: "Gi0/6"
     status: "down"
+  - description: "D3 USER"
+    port: "Gi0/6"
     protocol: "down"
-    descrip: "D3 USER"
-  - port: "Gi0/7"
     status: "down"
+  - description: "D3 USER"
+    port: "Gi0/7"
     protocol: "down"
-    descrip: "D3 USER"
-  - port: "Gi0/8"
-    status: "up"
+    status: "down"
+  - description: "MERAKI TEST AP"
+    port: "Gi0/8"
     protocol: "up"
-    descrip: "MERAKI TEST AP"
-  - port: "Gi0/9"
-    status: "admin down"
-    protocol: "down"
-    descrip: ""
-  - port: "Gi0/10"
     status: "up"
-    protocol: "up"
-    descrip: "UPLINK TO TULCCD3S01P"
-  - port: "Gi0/10.10"
-    status: "deleted"
+  - description: ""
+    port: "Gi0/9"
     protocol: "down"
-    descrip: ""
-  - port: "Gi0/10.20"
+    status: "admin down"
+  - description: "UPLINK TO TULCCD3S01P"
+    port: "Gi0/10"
+    protocol: "up"
     status: "up"
+  - description: ""
+    port: "Gi0/10.10"
+    protocol: "down"
+    status: "deleted"
+  - description: "Carrier VLAN"
+    port: "Gi0/10.20"
     protocol: "up"
-    descrip: "Carrier VLAN"
-  - port: "Gi0/10.30"
-    status: "reset"
+    status: "up"
+  - description: "Garbage"
+    port: "Gi0/10.30"
     protocol: "down"
-    descrip: "Garbage"
+    status: "reset"