Topology API
Learn how Augtera can build your network topology using REST API
Last updated
Learn how Augtera can build your network topology using REST API
Last updated
When Augtera learns of your devices and their relationships, Augtera can visualize your full Layer 2 and Layer 3 topology. It can auto-correlate network events and Augtera anomalies using the topology, track network changes, and monitor your devices.
You can either configure the Augtera platform with a list of your devices or use the Augtera Topology REST API to share your device information. The REST API allows the platform to automatically discover your devices and enables you to manage the lifecycle of your devices in Augtera. For example, if you use the API to change the state of a device to maintenance, it will inform the Augtera platform to appropriately modify notifications and correlation.
Further, Augtera can discover the relationships between devices and the network model using autodiscovery based on either SNMP, OpenConfig, or both. It can also base it on you sharing your network information using the Augtera Topology REST API.
This document describes the REST API commands to share your network information with the Augtera platform.
The entire workflow for endpoint discovery is represented in the following graphic:
To successfully understand the workflow, here are the high-level steps:
Use a POST API call to request Augtera's SCHEMA file.
Augtera will respond with a SCHEMA file in JSON format.
Send a POST request with header type INGESTION .
Send a POST request with header type Topology to allow Augtera to learn about devices and their relationships in your network.
Augtera will respond with a success zero code. This indicates that Augtera has successfully registered your POST notifications.
At any time, to verify the success of your configuration, use a GET command to see if Augtera is tracking your requested devices.
Augtera will respond with your devices list in JSON format.
If token-based authentication is enabled, use the API TOKEN provided by Augtera to reach the Augtera Platform hosted on the public cloud. Include the token in the header along with the X-Api-Key.
Example Request
Here is a sample request.
For Augtera to begin tracking your devices, use the
http://customer1.console.augtera.com/augtera/api/v1/network API endpoint to direct information to the Augtera console. Replace customer1.console.augtera.com with your Augtera UI URL.
The Header JSON API has two request types:
SCHEMA: When your request type is specified as SCHEMA, Augtera will respond with a JSON SCHEMA. Use the following CURL command to request the SCHEMA:
curl -X POST -H "Content-Type: application/json" -d @topology.json
http://<AUGTERA_PLATFORM_URL>/augtera/api/v1/network
INGESTION: When your request type is specified as INGESTION, the response will send a topology map containing a list of devices with their parameters. Use the following CURL command:
curl -X POST -H "Content-Type: application/json" -d @topology.json
http://<AUGTERA_PLATFORM_URL>/augtera/api/v1/network
For information on the top-level mapping, refer to the following table:
header
INGESTION
Publish time
Description of a request
header
SCHEMA
Publish time
GET schema of the topology request
topology
N/A
N/A
List of entities
For Augtera to be able to manage and monitor your devices, Augtera relies on initial device discovery to start its automated device polling process. The basic workflow is as follows:
Provide a list of all monitored devices and the following information for each:
" id ": A unique Global Unique Identifier (GUID) for a device
" entity_type ": Indicate "device" as the type
" mgmt_ipv4 ": IP address of the device to poll
" device_name ": Global unique device name
"site": Indicate the location of the device
Augtera reads the deviceAdminState value to check if polling or analytics are enabled on a particular device. There are three valid states per device:
ENABLE: A device is enabled for polling and analytics.
MAINTENANCE: A device is enabled for polling, but it is disabled for analytics.
DISABLED: A device is disabled for polling and analytics. This device will be deleted from the Augtera database.
To send a POST response to Augtera to report any topological changes, use the sample CURL request:
curl -X POST -H "Content-Type: application/json" -d @topology.json
http://<augtera_platform_url>/augtera/api/v1/network
Augtera runs validation against the SCHEMA. Thetopology.json file displays validated JSON schema in the body of the text
Here is an explanation the responses:
success- True confirms that the JSON body adheres to the SCHEMA
code-Code zero (0) indicates a successful transaction
message-Displays the number of entities that were processed
For more details on different status codes and what they mean, refer to the following table.
0
Success. The transaction was successfully posted to Augtera's backend service.
1
The message request is not supported
2
Augtera's backend service is down
3
The SCHEMA validation check failed
After you have sent your POST requests to Augtera and want to verify what devices are being tracked by Augtera, use this GET request.
HTTP GET customer-platform-url/augtera/api/get_model_devices
Again, replace customer-platform-url with your Augtera platform URL.
This request helps retrieve a list of network devices that have been created by Augtera services. Use this API to verify the state created by v1/network APIs.
Augtera will respond with a list of devices that Augtera will monitor. The following graphic represents this workflow.
At any time, use the Augtera UI to view any real-time updates based on any REST API event. This data is visible from the Trends page. To view updated information, choose
eventSource ="internal_event", eventType = "v1/network" .
The UI will display information of this nature:
This section contains the field descriptions for the Entities, Relationships, and the NOS mappings.
The following table lists the entities mappings and provides a brief description for each field.
id
YES
String
Global Unique ID for the entity
entity_type
YES
String
Specify "device"
mgmt_ipv4
YES
String
IPv4 Address of the management interface
device_name
YES
String
Hostname of the device
locations.groups.site
YES
String
Site where the entity is located
status
YES
String
Administrative state (admin_state) of the device. This can be one of the following:
ENABLED
MAINTENANCE
DISABLED
status
NO
String
Operational status (oper_status) of the device. It can be one of the following:
DeviceOperReachable
DeviceOperDown
DeviceOperUnknown
device_desc
NO
String
Device version
dns_device_name
NO
String
FQDN device name
os
NO
String
Operating system of the device
entity
Required
NO/YES
String
role: If an entity is chosen, then a role must be specified
entity
NO
String
cluster: Indicate the cloud cluster that contains this device
locations.groups.type
NO
String
type: This can be one of the following:
backbone
core
locations
NO
String
type: This can be one of the following:
backbone
core
locations.groups.region
NO
String
region: For example, this region can be specified as us-east
locations.groups.pod
NO
String
pod: Indicate the datacenter pod id
locations.groups.dc
NO
String
dc: Data center name
The following table lists the relationships mapping and provides a brief description for each field.
type
YES
String
Only "INTERFACE" is supported
if_name
YES
String
Name of the interface
if_index
NO
Integer
Interface index used for SNMP Metrics or Trap
ipv4_addr
NO
String
IP address of the interface
ipv6_addr
NO
String
IPv6 address of the interface
if_speed
NO
String
Interface speed
mtu
NO
Integer
Maximum Transmission Unit (MTU) of the interface
if_descr
NO
String
SNMP interface description
if_alias
NO
String
Alias name for interface
if_admin_status
NO
String
This can be one of the following:
AdminUp
AdminDown
AdminTesting
if_oper_status
NO
String
This can be one of the following:
OperUp
OperDown
OperTesting
remote
NO
Object
The remote interface that is linked to the specified interface
remote.device_name
YES
String
The name of the device to which this remote interface belongs
remote.mgmt_ipv4
YES
String
The management IP to which this remote interface belongs
remote.if_name
YES
String
Remote interface name
remote.link_type
YES
String
This can be one of the following:
lldp
isis
remote.ipv4_addr
NO
String
Indicate the IP Address of the remote device.
This is necessary for isis link_type
The following table lists the NOS mappings and provides a brief description for each field.
site
tenant
locations.groups.site
For example, mtbb
device name
name
device_name
For example, slcar1011
device IP
ip
mgmt_ipv4
For example, 10.1.1.1
status
enabled
status.admin_state
ENABLED
status
inMaintenance
status.admin_state
MAINTENANCE
status
decommissioned
status.admin_state
DISABLED
reachability
reachable
status.oper_status
This can be one of the following:
DeviceOperReachable
DeviceOperDown
The Network Operations Service (NOS) helps Augtera learn important information that you provide regarding your devices. For information on the NOS mapping, refer to the table called .
For information on entities mapping, refer to the table called . In addition, provide information on the administrative status of your device. Indicate if a device is enabled, disabled, or in maintenance mode. Use the API to provide updates on devices that are part of the pool of polled devices. For information on the mapping relationships, refer to the table called .
