Complexity and Documentation

Complexity

The complexity of networks has dramatically increased. Multiple factors have all stressed the capabilities of both the engineers who design and the operators who run the network. These include Virtual Route Forwarders (VRFs), QoS, wireless connectivity, cloud connectivity, and Virtual Private Network (VPN). First-Hop Redundancy Protocols (FHRP) such as Hot-Standby Router Protocol (HSRP), Virtual Switching Systems (VSS), and security and identity services such as 802.1x also demand attention.

Abstracting important data from the network configurations allows operators to see the network devices as a collection of human-readable variables and dynamic templates. This drastically simplifies network design. Human-readability of the intended configuration for a device also reduces the technical requirements needed to understand how a device is configured. Also, the knowledge required to execute commands and understand how a device is configured is abstracted. This is because the device information is presented as a human-readable data model.

Documentation

Network documentation is extremely important, especially during times of crisis, however, it is often overlooked during day-to-day operations. Changes may or may not be reflected in the documentation. Files may be scattered across a variety of sources such as local drives, Microsoft SharePoint sites, or network shares. Meanwhile, outdated documentation is often of little value to an organization. Documentation that does exist is often represented as complex Visio diagrams, large Excel spreadsheets, or text files that do not interact with the network dynamically.

Documentation should be considered a key component, and advantage, of the network automation solution. The scope of automation is not limited to making changes. Part of the repository master branch should be a folder structure containing both the dynamic documentation Ansible playbooks and folders for the generated output artifacts.

Automated documentation is built directly into the CI/CD pipeline, creating comma-separated values (.csv), Markdown (.md), or text files. These files are then incorporated into Git commits and pull requests, becoming part of the code base and repository. These artifacts include the intended, automatically generated, configuration files as well as the data model variables manipulated to express the information in different formats.

For example, it is possible to automatically generate the following documentation for each device, based on data model variables:

• VLANs
• VRFs
• Routing protocol configuration information
• Static routes
• Interface information:
  • Up/Down
  • Mode — Access or Trunk
  • VLAN(s)
• Port-channels information:
  • Member ports
  • IP Addresses
• Access Control Lists (ACL)

In fact, any information represented in a data model can be transformed into dynamic documentation files. This allows for desired information about any device on the network to be automatically generated at build time. The history for these documentation files is included as the source and version controls. When adding or removing code, the resulting documentation updates are automatically performed reflecting the changes.