Skip to content

Commit e26212a

Browse files
AndoniSanguesaAndoniSanguesa
authored
added api_wiki documentation (sonic-net#4021)
Description of PR Adds documentation on the ansible modules and class methods associated with sonic, sonic_asic, multi_asic, and ptf objects in a centralized location. Currently only the ansible modules and the sonic/sonic-asic/multi-asic class methods are documented. Since I am not running veos or using ixia, the documentation for those and other devices will be left to others or for another time. The script at docs/api_wiki/scripts/get_api_calls.py can be run to list out the undocumented methods. Summary: Type of change Bug fix Testbed and Framework(new/improvement) Test case(new/improvement) Documentation Approach What is the motivation for this PR? I constantly found myself stumbling on methods used in other tests that would have been useful in mine. Other co-workers have also expressed difficulty in figuring out how to interact with the dut/ptf or trying to figure out what the output of the API calls look like. This PR aims to address this. How did you do it? Created a script that checks the repo for all ansible modules and all methods implemented by the sonic, sonic_asic, multi_asic, and ptf classes. Other devices could be added in the future. This script lists out which methods/modules have been or haven't been documented. From there I used whatever existing documentation existed or ran the modules/methods myself to fill out the information on the docs.
1 parent 79924db commit e26212a

File tree

207 files changed

+7545
-1
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

207 files changed

+7545
-1
lines changed

‎docs/README.md

+2
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Using of pytest does not mean that ansible will no long be used. Ansible is stil
1717
* `spytest`: The SPyTest automation framework and tests for validating SONiC
1818
* `test_peporting`: For parsing, uploading and processing junit xml test reports generated by pytest. Processed test data is uploaded to Kusto for query.
1919
* `tests`: Pytest and pytest-ansible based test infrastructure code and test scripts
20+
* `api_wiki`: Information on how to communicate between localhost/dut/ptf. Useful for testwriting.
2021

2122
# Documentations
2223

@@ -25,6 +26,7 @@ Using of pytest does not mean that ansible will no long be used. Ansible is stil
2526
* [Write and run pytest](tests/README.md)
2627
* [Testplan](testplan)
2728
* [Test Reporting](/test_reporting/README.md)
29+
* [api_wiki](api_wiki/README.md)
2830
* Spytest
2931
* [Introduction](/spytest/Doc/intro.md)
3032
* [Install](/spytest/Doc/intro.md)

‎docs/api_wiki/README.md

+443
Large diffs are not rendered by default.

‎docs/api_wiki/ansible_methods/acl_facts.md

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# acl_facts
2+
3+
- [Overview](#overview)
4+
- [Examples](#examples)
5+
- [Arguments](#arguments)
6+
- [Expected Output](#expected-output)
7+
8+
## Overview
9+
Retrieves ACL information from remote host.
10+
11+
## Examples
12+
```
13+
def test_fun(duthosts, rand_one_dut_hostname):
14+
duthost = duthosts[rand_one_dut_hostname]
15+
16+
acl_facts = duthost.acl_facts()
17+
```
18+
19+
## Arguments
20+
This method takes no arguments.
21+
22+
## Expected Output
23+
A dictionary is returned containing information on the configured ACLs. The dictionary hierarchy is described below, with each indentation describing a sub-dictionary:
24+
25+
- `ansible_facts` - dictionary containing facts on ACL
26+
- `ansible_acl_facts` - Dictionary mapping ACL tables to their configurations
27+
- `{ACL_TABLE_NAME}` - Dictionary containing information on provided table
28+
- `policy_desc` - Description of the table policy
29+
- `ports` - List of the ports attached to the ACL table
30+
- `type` - type of ACL table (e.g. `L2` or `CTRLPLANE`)
31+
- `rules` - Dictionary that maps a rule name to its configuration
32+
- `{RULE_NAME}` - dictionary that maps a property of the rule to its value
33+
- `ETHER_TYPE` - Ethernet type
34+
- `PACKET_ACTION` - Whether to `DROP` or `FORWARD` a packet
35+
- `PRIORITY` - Rule priority
36+
- `bytes_count` - bytes affected by this rule
37+
- `packets_count` - packets affected by this rule
38+
- `SRC_IP` - IP that the packet is coming from
39+
- `DST_IP` - IP that the packet is going to
40+
- *There may be more key-value pairs than listed here

‎docs/api_wiki/ansible_methods/announce_routes.md

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# announce_routes
2+
3+
- [Overview](#overview)
4+
- [Examples](#examples)
5+
- [Arguments](#arguments)
6+
- [Expected Output](#expected-output)
7+
8+
## Overview
9+
Announces Routes to the exabgp processes running in the PTF container
10+
11+
This method must be run from the localhost.
12+
13+
## Examples
14+
```
15+
def test_fun(localhost):
16+
localhost.announce_routes(topo_name="t1-lag", ptf_ip: "192.168.1.10")
17+
```
18+
19+
## Arguments
20+
- `topo_name` - Name of topology in use
21+
- Required: `True`
22+
- Type: `String`
23+
- `ptf_ip` - IP for ptf container
24+
- Required: `True`
25+
- Type: `String`
26+
27+
## Expected Output
28+
Provides no meaningful output

‎docs/api_wiki/ansible_methods/bgp_facts.md

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# bgp_facts
2+
3+
- [Overview](#overview)
4+
- [Examples](#examples)
5+
- [Arguments](#arguments)
6+
- [Expected Output](#expected-output)
7+
8+
## Overview
9+
Retreives BGP information using Quagga
10+
11+
## Examples
12+
```
13+
def test_fun(duthosts, rand_one_dut_hostname):
14+
duthost = duthosts[rand_one_dut_hostname]
15+
16+
bgp_facts = duthost.bgp_facts()
17+
```
18+
19+
## Arguments
20+
- `nump_npus` - number of network processing units
21+
- Required: `False`
22+
- Type: `Integer`
23+
- Default: `1`
24+
- `instance_id` - ASIC instance id for desired ASIC (for multi-asic devies)
25+
- Required: `False`
26+
- Type: `Integer`
27+
28+
## Expected Output
29+
Returns dictionary with information on BGP configuration. The dictionary hierarchy is described below, with each indentation describing a sub-dictionary:
30+
31+
- `ansible_facts`
32+
- `bgp_statistics` - Dictionary describing general BGP stats
33+
- `ipv4_idle` - Number of ipv4 BGP neighbors in an idle state
34+
- `ipv6_idle` - Number of ipv6 BGP neighbors in an idle state
35+
- `ipv4_admin_down` - Number of ipv4 BGP neighbors with a `down` admin state
36+
- `ipv6_admin_down` - Number of ipv6 BGP neighbors with a `down` admin state
37+
- `ipv4` - Number of ipv4 BGP neighbors
38+
- `ipv6` - Number of ipv6 neighbors
39+
- `bgp_neighbors` - Dictionary that maps BGP ip to information on neighbor
40+
- `{BGP_IP}` - Dictionary that provides information on specified neighbor
41+
- `remote AS` - neighbor's remote ASN
42+
- `description` - Neighbor name
43+
- `admin` - admin status
44+
- `accepted prefixes` - number of accepted prefixes
45+
- `message statistics` - Dictionary with statistics on messages send and received
46+
- `Capability`
47+
- `rcvd` - Number of received capability messages
48+
- `sent` - Number of sent capability messages
49+
- `Notifications`
50+
- `rcvd` - Number of received notifications messages
51+
- `sent` - Number of sent notifications messages
52+
- `Route Refresh`
53+
- `rcvd` - Number of received route refresh messages
54+
- `sent` - Number of sent route refresh messages
55+
- `Keepalives`
56+
- `rcvd` - Number of received keepalive messages
57+
- `sent` - Number of sent keepalive messages
58+
- `Opens`
59+
- `rcvd` - Number of received open messages
60+
- `sent` - Number of sent open messages
61+
- `Total`
62+
- `rcvd` - Total number of received messages
63+
- `sent` - Total number of messages sent
64+
- `capabilities` - Dictioanry mapping capability message to how many times it was sent
65+
- `{CAPABILITY_MSG}` - number of times specified message was sent
66+
- `peer group` - name of peer group
67+
- `state` - state of BGP neighbor
68+
- `connections established` - Number of connections established by neighbor
69+
- `connections dropped` - Number of connections dropped by neighbor
70+
- `mrai` - Minimal route advertisement interval
71+
- `ip_version`: type of ip version for neighbor
72+
- `local AS`: local AS number
73+
- `remote routerid`

‎docs/api_wiki/ansible_methods/bgp_route.md

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# bgp_route
2+
3+
- [Overview](#overview)
4+
- [Examples](#examples)
5+
- [Arguments](#arguments)
6+
- [Expected Output](#expected-output)
7+
8+
## Overview
9+
Provides BGP routing info from Quagga using VTYSH cli.
10+
11+
## Examples
12+
```
13+
def test_fun(duthosts, rand_one_dut_hostname, tbinfo):
14+
duthost = duthosts[rand_one_dut_hostname]
15+
16+
bgp_route_neigh = duthost.bgp_route(neighbor="10.0.0.59", direction="adv")
17+
```
18+
19+
## Arguments
20+
21+
- `direction` - to restict retrieving bgp neighbor advertise or received routes
22+
- Required: `False`, unless `neighbor` argument is provided.
23+
- Choices:
24+
- `adv` - Advertising
25+
- `rec` - Receiving
26+
- Type: `String`
27+
28+
- `neighbor` - restirct retrieving routing information from bgp neighbor. bgp neighbor address is expected to follow this option
29+
- Required: `False`
30+
- Default: `None`
31+
- Type: `String`
32+
33+
- `prefix` - bgp prefix to be retrieved from show ip bgp
34+
- Required: `False`
35+
- Default: `None`
36+
- Type: `String`
37+
38+
## Expected Output
39+
Returns a dictionary containing information on the bgp route given the provided arguments.The dictionary hierarchy is described below, with each indentation describing a sub-dictionary:
40+
41+
- `ansible_facts` - Route map info
42+
- `bgp_route_neiadv` - BGP route information for advertised routes. Only present if `neighbor` and `direction='adv'` is specified.
43+
- `neighbor` - BGP IP for chosen neighbor
44+
- `{route-ip}` - IP for node in route table
45+
- `origin` - origin source for route `i` for Internal Gateway Protocol or `e` for External Gateway Protocol
46+
- `weigh` - tie breaker used to determine best path
47+
- `nexthop` - nexthop configured for neighbor
48+
- `aspath` - aspath configured for neighbor
49+

‎docs/api_wiki/ansible_methods/command.md

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# command
2+
3+
- [Overview](#overview)
4+
- [Examples](#examples)
5+
- [Arguments](#arguments)
6+
- [Expected Output](#expected-output)
7+
8+
## Overview
9+
Used to run commands via shell on remote host.
10+
11+
Environment variables like `$HOSTNAME` or operations like `*`, `<`, `>`, `|`, `;`, `&` will not work. See [shell](shell.md) to use these.
12+
13+
These [docs](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/command_module.html) were used in the creation of this page.
14+
15+
## Examples
16+
```
17+
def test_fun(duthosts, rand_one_dut_hostname):
18+
duthost = duthosts[rand_one_dut_hostname]
19+
20+
free_form_ret = duthost.command("ls -ltr")
21+
cmd_ret = duthost.command(cmd="ls -ltr")
22+
argv_ret = duthost.command(argv=["ls", "-ltr"])
23+
```
24+
25+
## Arguments
26+
- `argv` - command as list of strings containing main command and its options
27+
- Required: `True` if `cmd` or free-form argument is not provided, `False` otherwise.
28+
- Type: `List`
29+
- Element-Type: `String`
30+
- `chdir` - change into specified directory before running
31+
- Required: `False`
32+
- Type: `String`
33+
- `cmd` - The command to be run as a string with space dilineated options.
34+
- Required: `True` if `argv` or free-form argument is not provided, `False` otherwise
35+
- Type: `String`
36+
- `creates` - filename. If a matching file already exists, command _will not_ be run.
37+
- Required: `False`
38+
- Type: `String`
39+
- `removes` - filename. If matching file exists, command _will_ be run
40+
- Required: `False`
41+
- Type: `String`
42+
- `stdin` - Set the stdin command directly to the specified value
43+
- Required: `False`
44+
- Type: `String`
45+
- `stdin_add_newline` - if `True`, newline is appended to stdin data
46+
- Required: `False`
47+
- Type: `Boolean`
48+
- Default: `True`
49+
- `strip_empty_ends` - Strips empty lines from end of stdout/stderr
50+
- Required: `False`
51+
- Type: `Boolean`
52+
- Default: `True`
53+
- `warn` - Enable or disable task warnings (deprecated)
54+
- Required: `False`
55+
- Type: `Boolean`
56+
- Default: `False`
57+
58+
## Expected Output
59+
Dictionary with information on command output:
60+
61+
- `cmd` - the command executed by task
62+
- `delta` - the command execution time
63+
- `end` - The command end time
64+
- `msg` - whether the associated task was in a `changed` state
65+
- `rc` - return code for command
66+
- `start` - the command execution start time
67+
- `stderr` - The standard error as a string
68+
- `stderr_lines`- The standard error as a list of strings
69+
- `stdout` - the standard output as a string
70+
- `stdout_lines` - the standard output as a list of strings

‎docs/api_wiki/ansible_methods/config_facts.md

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# config_facts
2+
3+
- [Overview](#overview)
4+
- [Examples](#examples)
5+
- [Arguments](#arguments)
6+
- [Expected Output](#expected-output)
7+
8+
## Overview
9+
Retreives configuration facts for a device
10+
11+
## Examples
12+
```
13+
def test_fun(duthosts, rand_one_dut_hostname):
14+
duthost = duthosts[rand_one_dut_hostname]
15+
16+
config_facts = duthosts.config_facts(host=duthost.hostname, source="running")
17+
```
18+
19+
## Arguments
20+
- `host` - The device hostname that config facts are desired for
21+
- Required: `True`
22+
- Type: `String`
23+
- `source` - Whether current config or boot config is desired
24+
- Required: `True`
25+
- Type: `String`
26+
- Choices:
27+
- `running` - currently running config
28+
- `persistent` - boot config as described in `/etc/sonic/config_db.json`
29+
- `filename` - specific config file location (if not `/etc/sonic/config_db.json`)
30+
- Required: `False`
31+
- Type: `String`
32+
- `namespace` - Specify ASIC namespace is desired
33+
- Required: `False`
34+
- Type: `String`
35+
36+
## Expected Output
37+
38+
Output is too long to reasonably document on this page. Though documentation should be added on commonly used features.

‎docs/api_wiki/ansible_methods/conn_graph_facts.md

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# conn_graph_facts
2+
3+
- [Overview](#overview)
4+
- [Examples](#examples)
5+
- [Arguments](#arguments)
6+
- [Expected Output](#expected-output)
7+
8+
## Overview
9+
Retreives info on lab fannout siwtches and vlan connections.
10+
11+
## Examples
12+
```
13+
def test_fun(localhost):
14+
graph_facts = localhost.conn_graph_facts()
15+
```
16+
17+
## Arguments
18+
- `host` - the fannout switch name, the server name, or the SONiC switch name
19+
- Required: `False`
20+
- Type: `String`
21+
- `hosts` - List of hosts
22+
- Required: `False`
23+
- Type: `List`
24+
- Element-Type: `String`
25+
- `anchor` - List of hosts. When no host and hosts is provided, the anchor option must be specified with list of hosts. This option is to supply the relevant list of hosts for looking up the connection graph xml file which has all the supplied hosts. The whole graph will be returned when this option is used. This is for configuring the root fanout switch.
26+
- Required: `False`
27+
- Type: `List`
28+
- Element-Type: `String`
29+
- `filepath` - Path to the connection graph xml file. Overrides default.
30+
- Required: `False`
31+
- Type: `String`
32+
- `filename` - name of the connection graph xml file.
33+
- Required: `False`
34+
- Type: `String`
35+
36+
`host`, `hosts`, and `anchor` are mutually exclusive.
37+
38+
## Expected Output
39+
40+
- `device_info` - The device(host) type and hwsku
41+
- `device_conn` - each physical connection of the device(host)
42+
- `device_vlan_range` - all configured vlan range for the device(host)
43+
- `device_port_vlans` - detailed vlanids for each physical port and switchport mode
44+
- `server_links` - each server port vlan ids
45+
- `device_console_info` - The device's console server type, mgmtip, hwsku and protocol
46+
- `device_console_link` - The console server port connected to the device
47+
- `device_pdu_info` - The device's pdu server type, mgmtip, hwsku and protocol
48+
- `device_pdu_links` - The pdu server ports connected to the device
49+

‎docs/api_wiki/ansible_methods/console_facts.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# console_facts
2+
3+
- [Overview](#overview)
4+
- [Examples](#examples)
5+
- [Arguments](#arguments)
6+
- [Expected Output](#expected-output)
7+
8+
## Overview
9+
Retrieves console feature and status information using Quagga.
10+
11+
## Examples
12+
```
13+
def test_fun(duthosts, rand_one_dut_hostname):
14+
duthost = duthosts[rand_one_dut_hostname]
15+
16+
con_facts = duthost.console_facts()
17+
```
18+
19+
## Arguments
20+
This method takes no arguments
21+
22+
## Expected Output
23+
Was not able to get sufficient output with my testbed. If you are contributor with console enabled, consider contributing your output.

0 commit comments

Comments
 (0)