awx/awx/network_ui/CONTRIBUTING.md

Network UI

See awx/ui/client/src/network-ui/CONTRIBUTING.md for the introduction to the Network UI client-side development.

Server-Side Development

This document covers the Network UI server-side development.

The Network UI is a UX driven feature to provide a graphical user experience that fits well into the network engineer's normal workflow. Their normal workflow includes a diagram drawn in a graphical drawing program, a spreadsheet, and the command line interface of their network gear. Network architects design the network on the graphical diagram and then hand off the architecture to network operators who implement the architecture on the network using spreadsheets to manage their data and manually converting the data into CLI commands using their networking expertise and expertise with their physical gear.

The server-side code supports the persistence needed to provide this graphical user experience of architecting a network and using that information along with additional information (stored in vars files) to configure the network devices using the CLI or NETCONF using Ansible playbooks and roles.

Network UI Data Schema

For the 3.3 release the persistence needed includes the position information of the devices on the virtual canvas and the type of the devices as well as information about the interfaces on the devices and the links connecting those interfaces.

These requirements determine the database schema needed for the network UI which requires these models: Topology, Device, Interface, Link, Client, and TopologyInventory.

This diagram shows the relationships between the models in the Network UI schema.

The models are:

• Device - a host, switch, router, or other networking device
• Interface - a connection point on a device for a link
• Link - a physical connection between two devices to their respective interfaces
• Topology - a collection of devices and links
• TopologyInventory - a mapping between topologies and Tower inventories
• Client - a UI client session

Network UI Websocket Protocol

Persistence for the network UI canvas state is implemented using an asynchronous websocket protocol to send information from the client to the server and vice-versa. This two-way communication was chosen to support future features for streaming data to the canvas, broadcast messaging between clients, and for interaction performance on the UI.

Messages

JSON messages are passed over the /network_ui/topology websocket between the test client and the test server. The protocol that is used for all messages is in ABNF (RFC5234):

message_type    =  'DeviceMove' / 'DeviceCreate' / 'DeviceDestroy' / 'DeviceLabelEdit' / 'DeviceSelected' / 'DeviceUnSelected' / 'InterfaceCreate' / 'InterfaceLabelEdit' / 'LinkLabelEdit' / 'LinkCreate' / 'LinkDestroy' / 'LinkSelected' / 'LinkUnSelected' / 'MultipleMessage' / 'Snapshot'
message_data    = '{' 'msg_type' ': ' message_type ', ' key-value *( ', ' key-value ) '}'
message         = '[ id , ' posint ']' / '[ topology_id , ' posint ']' / '[' message_type ', ' message_data ']'

See https://github.com/AndyA/abnfgen/blob/master/andy/json.abnf for the rest of the JSON ABNF.

See designs/messages.yml for the allowable keys and values for each message type.

Initially when the websocket is first opened the server will send four messages to the client. These are:

• the client id using the id message type.
• the topology id using the topology message type.
• a Topology record containing data for the canvas itself.
• a Snapshot message containing all the data of the data on the canvas.

As the user interacts with the canvas messages will be generated by the client and the network_ui.consumers.Persistence class will update the models that represent the canvas.

Persistence

The class awx.network_uiconsumers.Persistence provides persistence for the Network UI canvas. It does so by providing message handlers that handle storage of the canvas change events into the database. Each event has a message handle with name onX where X is the name of the message type. The handlers use the filter/values_list, filter/values, filter/update, and filter/delete patterns to update the data in the database quickly with a constant O(1) number of queries per event often with only one query needed. With filter/update and filter/delete all the work is done in the database and Python never needs to instaniate and garbage collect the model objects.

Bulk operations (filter/values) in send_snapshot are used to produce a constant number of queries produce a snapshot when the canvas is first loaded. This method avoids creating the model objects since it only produces dicts that are JSON serializable which are bundled together for the Snapshot message type.

This method of persistence uses Django as a database query-compiler for transforms from the event types to the database types. Using Django in this way is very performant since Python does very little work processing the data and when possible the data never leaves the database.

Client Tracking

Each user session to the network UI canvas is tracked with the Client model. Multiple clients can view and interact with the network UI canvas at a time. They will see each other's edits to the canvas in real time. This works by broadcasting the canvas change events to all clients viewing the same topology.

    # Send to all clients editing the topology
    Group("topology-%s" % message.channel_session['topology_id']).send({"text": message['text']})

API

There is no user accessible API for this feature in the 3.3 release.