Topology API
Learn how Augtera can build your network topology using REST API
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:
Topology API Workflow
To successfully understand the workflow, here are the high-level steps:
- 1.Use a POST API call to request Augtera's SCHEMA file.
- 2.Augtera will respond with a SCHEMA file in JSON format.
- 3.Send a POST request with header type INGESTION .
- 4.Send a POST request with header type Topology to allow Augtera to learn about devices and their relationships in your network.
- 5.Augtera will respond with a success zero code. This indicates that Augtera has successfully registered your POST notifications.
- 6.At any time, to verify the success of your configuration, use a GET command to see if Augtera is tracking your requested devices.
- 7.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.
curl -H "Content-Type: application/json" -H "X-Api-Key: Customer-Access-Token" \ -d @topology.json http://<AUGTERA_PLATFORM_URL>/augtera/api/v1/network
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.jsonhttp://<AUGTERA_PLATFORM_URL>/augtera/api/v1/networkINGESTION: 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.jsonhttp://<AUGTERA_PLATFORM_URL>/augtera/api/v1/networkFor information on the top-level mapping, refer to the following table:
Type | Type | Timestamp | Description |
|---|---|---|---|
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:
Topology API to Share Device Information
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 NOS Mapping.
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
For information on entities mapping, refer to the table called Entities Mapping. 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 Relationships Mapping.
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.jsonhttp://<augtera_platform_url>/augtera/api/v1/networkAugtera runs validation against the SCHEMA. The
topology.json file displays validated JSON schema in the body of the text{
"success": true,
"code": 0,
"message": "processed: 2 entities"
}
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.
Code | Description |
|---|---|
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 |
{
"header": {
"request_type": "INGESTION",
"timestamp": "2022-03-25 12:35:40",
"description": "create devices and interfaces"
},
"topology": [
{
"id": "prod:100.1.1.1",
"entity_type": "device",
"mgmt_ipv4": "100.1.1.1",
"device_name": "switch11test",
"device_desc": "Juniper ",
"dns_device_name": "switch11test.dc1.augtera.com",
"os": "nxos",
"locations": {
"groups": [
{
"site": "Brooklyn",
"type": "backbone",
"region": "us-east",
"pod": "xyz",
"dc": "1"
}
]
},
"status": {
"oper_status": "DeviceOperReachable",
"admin_state": "ENABLED"
},
"entity": {
"role": "leaf",
"cluster_name": "ija"
},
"relationships": {
"edges": [
{
"local": {
"type": "INTERFACE",
"if_name": "port-channel300",
"if_index": 1023,
"ipv4_addr": "1.2.3.4",
"ipv6_addr": "fe:80",
"if_speed": "100",
"mtu": 1500,
"bw": 100,
"if_descr": "test intf",
"if_alias": "test Alias",
"if_admin_status": "AdminUp",
"if_oper_status": "OperUp"
},
"remote": {
"device_name": "switch12test",
"mgmt_ipv4": "100.1.1.2",
"if_name": "port-channel200",
"ipv4_addr": "2.2.3.4",
"link_type": ["lldp", "isis"]
}
}
]
}
},
{
"id": "prod:100.1.1.2",
"entity_type": "device",
"device_id": "abcde3",
"device_id_type": "spine",
"device_desc": "Juniper ",
"device_name": "switch12test",
"dns_device_name": "switch12test.dc1.augtera.com",
"mgmt_ipv4": "100.1.1.2",
"os": "nxos",
"locations": {
"groups": [
{
"site": "Jersey",
"type": "backbone",
"region": "us-east",
"pod": "xyz",
"dc": "1"
}
]
},
"status": {
"oper_status": "DeviceOperReachable",
"admin_state": "ENABLED"
},
"entity": {
"role": "leaf",
"cluster_name": "ija"
},
"relationships": {
"edges": [
{
"local": {
"type": "INTERFACE",
"if_name": "port-channel200",
"if_index": 1024,
"ipv4_addr": "2.2.3.4",
"ipv6_addr": "fe:80",
"if_speed": "100",
"mtu": 1500,
"bw": 100,
"if_descr": "test intf",
"if_alias": "test Alias",
"if_admin_status": "AdminUp",
"if_oper_status": "OperUp"
},
"remote": {
"device_name": "switch11test",
"mgmt_ipv4": "100.1.1.1",
"if_name": "port-channel300",
"ipv4_addr": "1.2.3.4",
"link_type": ["lldp", "isis"]
}
}
]
}
}
]
}
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_devicesAgain, 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.
Topology API to Verify Device Configuration
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:
View Real-time Network Device Information
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.
Property | Required | Type | Description |
|---|---|---|---|
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:
|
status | NO | String | Operational status (oper_status) of the device. It can be one of the following:
|
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:
|
| | | |
locations | NO | String | type: This can be one of the following:
|
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.
Property | Required | Type | Description |
|---|---|---|---|
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:
|
if_oper_status | NO | String | This can be one of the following:
|
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:
|
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.
Property | NOS | Augtera Dimension | Description |
|---|---|---|---|
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:
|
Last modified 6mo ago