Skip to content

Commit c356c2b

Browse files
allenrobelallenrobel
authored
Merge pull request #200 from allenrobel/policy-doc-update
## Pull Request Overview This PR adds documentation for policy-related example scripts to the GitHub pages site. The purpose is to provide comprehensive documentation for users to understand and use the policy management scripts effectively. Key changes: - Added navigation entries for four policy scripts in the documentation site - Created detailed documentation files for each policy script with usage examples and expected outputs
2 parents 61dcce1 + 63573bd commit c356c2b

5 files changed

Lines changed: 364 additions & 0 deletions

File tree

‎docs/scripts/policy_create.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# policy_create.py
2+
3+
## Description
4+
5+
Create one or more policies.
6+
7+
## Notes
8+
9+
1. All policy scripts use `description` as a unique key to identify a policy.
10+
11+
The implication when creating policies is that a create request will be rejected if a policy is found on the controller with the same `description` as the policy being created.
12+
13+
## Example configuration file
14+
15+
``` yaml title="config/policy_create.yaml"
16+
---
17+
config:
18+
- switch_name: LE1
19+
fabric_name: SITE1
20+
description: management vrf static route to syslog server
21+
entity_name: SWITCH
22+
entity_type: SWITCH
23+
priority: 200
24+
source: ""
25+
template_name: vrf_static_route
26+
nv_pairs:
27+
IP_PREFIX: 192.168.7.1/32
28+
NEXT_HOP_IP: 192.168.12.1
29+
VRF_NAME: management
30+
- switch_name: LE2
31+
fabric_name: SITE2
32+
description: management vrf static route to syslog server
33+
entity_name: SWITCH
34+
entity_type: SWITCH
35+
priority: 200
36+
source: ""
37+
template_name: vrf_static_route
38+
nv_pairs:
39+
IP_PREFIX: 192.168.7.1/32
40+
NEXT_HOP_IP: 192.168.12.1
41+
VRF_NAME: management
42+
```
43+
44+
## Example Usage
45+
46+
The example below uses environment variables for credentials, so requires
47+
only the `--config` argument. See [Running the Example Scripts]
48+
for details around specifying credentials from the command line, from
49+
environment variables, from Ansible Vault, or a combination of these
50+
credentials sources.
51+
52+
[Running the Example Scripts]: ../setup/running-the-example-scripts.md
53+
54+
``` bash
55+
export ND_DOMAIN=local
56+
export ND_IP4=192.168.7.7
57+
export ND_PASSWORD=MySecretPassword
58+
export ND_USERNAME=admin
59+
./policy_create.py --config config/policy_create.yaml
60+
# output not shown
61+
```
62+
63+
## Example output
64+
65+
### Success
66+
67+
``` bash title="Policies created successfully"
68+
(ndfc-python) arobel@Allen-M4 examples % ./policy_create.py --config config/s12/policy_create.yaml
69+
Created fabric SITE1, switch LE1, policy_id POLICY-76120.
70+
Created fabric SITE2, switch LE2, policy_id POLICY-76130.
71+
(ndfc-python) arobel@Allen-M4 examples %
72+
```
73+
74+
### Failure - Policy create request rejected because a policy with the same description already exists
75+
76+
``` bash title="Policy exists"
77+
(ndfc-python) arobel@Allen-M4 examples % ./policy_create.py --config config/s12/policy_create.yaml
78+
Error creating fabric SITE1, switch LE1, policy (template_name: vrf_static_route). Error detail: PolicyCreate._validate_no_policy_name_conflict: Policy ID POLICY-76120 with description 'management vrf static route to syslog server' already exists on switch LE1 in fabric SITE1. Use a unique policy description or delete the existing policy.
79+
Error creating fabric SITE2, switch LE2, policy (template_name: vrf_static_route). Error detail: PolicyCreate._validate_no_policy_name_conflict: Policy ID POLICY-76130 with description 'management vrf static route to syslog server' already exists on switch LE2 in fabric SITE2. Use a unique policy description or delete the existing policy.
80+
(ndfc-python) arobel@Allen-M4 examples %
81+
```

‎docs/scripts/policy_delete.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# policy_delete.py
2+
3+
## Description
4+
5+
Delete one or more policies.
6+
7+
## Notes
8+
9+
1. All policy scripts use `description` as a unique key to identify a policy.
10+
11+
The implication when deleting policies is that a delete request will be rejected if multiple policies on the controller have the same `description`.
12+
13+
## Example configuration file
14+
15+
``` yaml title="config/policy_delete.yaml"
16+
---
17+
config:
18+
- switch_name: LE3
19+
fabric_name: SITE3
20+
description: management vrf static route to syslog server
21+
- switch_name: LE4
22+
fabric_name: SITE4
23+
description: management vrf static route to syslog server
24+
```
25+
26+
## Example Usage
27+
28+
The example below uses environment variables for credentials, so requires
29+
only the `--config` argument. See [Running the Example Scripts]
30+
for details around specifying credentials from the command line, from
31+
environment variables, from Ansible Vault, or a combination of these
32+
credentials sources.
33+
34+
[Running the Example Scripts]: ../setup/running-the-example-scripts.md
35+
36+
``` bash
37+
export ND_DOMAIN=local
38+
export ND_IP4=192.168.7.7
39+
export ND_PASSWORD=MySecretPassword
40+
export ND_USERNAME=admin
41+
./policy_delete.py --config config/policy_delete.yaml
42+
# output not shown
43+
```
44+
45+
## Example output
46+
47+
### Success
48+
49+
``` bash title="Policies deleted successfully"
50+
(ndfc-python) arobel@Allen-M4 examples % ./policy_delete.py --config config/s12/policy_delete.yaml
51+
Deleted fabric SITE1, switch LE1, policy_id POLICY-76120
52+
Deleted fabric SITE2, switch LE2, policy_id POLICY-76130
53+
(ndfc-python) arobel@Allen-M4 examples %
54+
```
55+
56+
### Failure - Policies do not exist
57+
58+
``` bash title="Policies do not exist"
59+
(ndfc-python) arobel@Allen-M4 examples % ./policy_delete.py --config config/s12/policy_delete.yaml
60+
Error deleting policy for fabric SITE1, switch LE1, policy description 'management vrf static route to syslog server'. Error detail: PolicyDelete._set_policy_ids: fabric_name SITE1, switch_name LE1: No policies found with description 'management vrf static route to syslog server'
61+
Error deleting policy for fabric SITE2, switch LE2, policy description 'management vrf static route to syslog server'. Error detail: PolicyDelete._set_policy_ids: fabric_name SITE2, switch_name LE2: No policies found with description 'management vrf static route to syslog server'
62+
(ndfc-python) arobel@Allen-M4 examples %
63+
```
64+
65+
### Failure - Policy delete request rejected because multiple policies with the same description exist on the controller
66+
67+
``` bash title="Policy exists"
68+
(ndfc-python) arobel@Allen-M4 examples % ./policy_delete.py --config config/s12/policy_delete.yaml
69+
Error deleting policy for fabric SITE1, switch LE1, policy description 'management vrf static route to syslog server'. Error detail: PolicyDelete._set_policy_ids: Expected to find exactly one policy with description 'management vrf static route to syslog server' on switch LE1 in fabric SITE1. Found 2 policies with that description. Cannot proceed with delete operation. Manually delete the duplicate policies and try again. policy_ids: ['POLICY-76140', 'POLICY-76150'],
70+
(ndfc-python) arobel@Allen-M4 examples %
71+
```

‎docs/scripts/policy_info_switch.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# policy_info_switch.py
2+
3+
## Description
4+
5+
Retrieve all policies for one or more switches.
6+
7+
## Example configuration file
8+
9+
``` yaml title="config/policy_info_switch.yaml"
10+
---
11+
config:
12+
- switch_name: LE1
13+
fabric_name: SITE1
14+
- switch_name: LE2
15+
fabric_name: SITE2
16+
```
17+
18+
## Example Usage
19+
20+
The example below uses environment variables for credentials, so requires
21+
only the `--config` argument. See [Running the Example Scripts]
22+
for details around specifying credentials from the command line, from
23+
environment variables, from Ansible Vault, or a combination of these
24+
credentials sources.
25+
26+
[Running the Example Scripts]: ../setup/running-the-example-scripts.md
27+
28+
``` bash
29+
export ND_DOMAIN=local
30+
export ND_IP4=192.168.7.7
31+
export ND_PASSWORD=MySecretPassword
32+
export ND_USERNAME=admin
33+
./policy_info_switch.py --config config/policy_info_switch.yaml
34+
# output not shown
35+
```
36+
37+
## Example output
38+
39+
### Success
40+
41+
``` bash title="Policies retrieved successfully"
42+
(ndfc-python) arobel@Allen-M4 examples % ./policy_info_switch.py --config config/s12/policy_info_switch.yaml
43+
SITE1, LE1, policies:
44+
```
45+
46+
``` json
47+
{
48+
"autoGenerated": true,
49+
"deleted": false,
50+
"editable": true,
51+
"entityName": "SWITCH",
52+
"entityType": "SWITCH",
53+
"fabricName": "SITE1",
54+
"generatedConfig": "",
55+
"id": 21160,
56+
"ipAddress": "192.168.12.151",
57+
"modifiedOn": 1758053377477,
58+
"nvPairs": {
59+
"MARK_DELETED": "false",
60+
"POLICY_DESC": "",
61+
"POLICY_ID": "POLICY-21160",
62+
"PRIORITY": "10",
63+
"id": "0"
64+
},
65+
"policyId": "POLICY-21160",
66+
"priority": 10,
67+
"resourcesLinked": "",
68+
"serialNumber": "9WPLALSNXK6",
69+
"source": "",
70+
"statusOn": 1758053377477,
71+
"switchName": "LE1",
72+
"templateContentType": "PYTHON",
73+
"templateName": "bgp_lb_id"
74+
}
75+
```
76+
77+
etc...
78+
79+
```bash
80+
(ndfc-python) arobel@Allen-M4 examples %
81+
```
82+
83+
### Failure - Fabric does not exist
84+
85+
``` bash title="Fabric does not exist"
86+
(ndfc-python) arobel@Allen-M4 examples % ./policy_info_switch.py --config config/s12/policy_info_switch.yaml
87+
Error retrieving fabric SITE3, switch LE1, policies. Error detail: PolicyInfoSwitch._final_verification: fabric_name SITE3 does not exist on the controller.
88+
Error retrieving fabric SITE4, switch LE2, policies. Error detail: PolicyInfoSwitch._final_verification: fabric_name SITE4 does not exist on the controller.
89+
(ndfc-python) arobel@Allen-M4 examples %
90+
```
91+
92+
### Failure - Switch does not exist in fabric
93+
94+
``` bash title="Switch does not exist in fabric"
95+
(ndfc-python) arobel@Allen-M4 examples % ./policy_info_switch.py --config config/s12/policy_info_switch.yaml
96+
Error retrieving fabric SITE1, switch LE3, policies. Error detail: PolicyInfoSwitch._final_verification: switch_name LE3 not found in fabric SITE1.
97+
Error retrieving fabric SITE2, switch LE4, policies. Error detail: PolicyInfoSwitch._final_verification: switch_name LE4 not found in fabric SITE2.
98+
(ndfc-python) arobel@Allen-M4 examples %
99+
```

‎docs/scripts/policy_info_switch_generated_config.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# policy_info_switch_generated_config.py
2+
3+
## Description
4+
5+
Retrieve all policies for one or more switches and display their generated configs.
6+
7+
## Example configuration file
8+
9+
``` yaml title="config/policy_info_switch_generated_config.yaml"
10+
---
11+
config:
12+
- switch_name: LE1
13+
fabric_name: SITE1
14+
- switch_name: LE2
15+
fabric_name: SITE2
16+
```
17+
18+
## Example Usage
19+
20+
The example below uses environment variables for credentials, so requires
21+
only the `--config` argument. See [Running the Example Scripts]
22+
for details around specifying credentials from the command line, from
23+
environment variables, from Ansible Vault, or a combination of these
24+
credentials sources.
25+
26+
[Running the Example Scripts]: ../setup/running-the-example-scripts.md
27+
28+
``` bash
29+
export ND_DOMAIN=local
30+
export ND_IP4=192.168.7.7
31+
export ND_PASSWORD=MySecretPassword
32+
export ND_USERNAME=admin
33+
./policy_info_switch_generated_config.py --config config/policy_info_switch_generated_config.yaml
34+
# output not shown
35+
```
36+
37+
## Example output
38+
39+
### Success
40+
41+
``` bash title="Policies retrieved successfully"
42+
(ndfc-python) arobel@Allen-M4 examples % ./policy_info_switch_generated_config.py --config config/s12/policy_info_switch_generated_config.yaml
43+
SITE1, LE1, policies:
44+
power redundancy-mode ps-redundant
45+
copp profile strict
46+
feature dhcp
47+
ipv6 switch-packets lla
48+
feature ospf
49+
feature pim
50+
nv overlay evpn
51+
feature interface-vlan
52+
feature vn-segment-vlan-based
53+
feature lldp
54+
feature nv overlay
55+
feature bgp
56+
feature nxapi
57+
cfs eth distribute
58+
feature lacp
59+
feature ngoam
60+
username admin password 5 $5$BEJAMJ$ujNFizvgASVsw3a2RACVBgXpCOBVbmNE5Esh/vDc4ET role network-admin
61+
service dhcp
62+
ip dhcp relay
63+
ip dhcp relay information option
64+
ip dhcp relay information option vpn
65+
ipv6 dhcp relay
66+
system jumbomtu 9216
67+
route-map FABRIC-RMAP-REDIST-SUBNET permit 10
68+
match tag 12345
69+
router bgp 65001
70+
router-id 10.11.0.2
71+
router ospf UNDERLAY
72+
router-id 10.11.0.2
73+
ip pim ssm range 232.0.0.0/8
74+
ip pim rp-address 10.13.254.1 group-list 239.1.1.0/25
75+
nxapi https port 443
76+
nxapi http port 80
77+
78+
79+
snmp-server host 192.168.12.12 traps version 2c public udp-port 2162
80+
81+
82+
hostname LE1
83+
no password strength-check
84+
evpn
85+
fabric forwarding anycast-gateway-mac 2020.0000.00aa
86+
vrf context management
87+
ip route 0.0.0.0/0 192.168.12.1
88+
vrf context management
89+
ip route 0.0.0.0/0 192.168.12.1
90+
vlan 1
91+
line vty
92+
etc...
93+
```
94+
95+
### Failure - Fabric does not exist
96+
97+
``` bash title="Fabric does not exist"
98+
(ndfc-python) arobel@Allen-M4 examples % ./policy_info_switch_generated_config.py --config config/s12/policy_info_switch_generated_config.yaml
99+
Error retrieving fabric SITE8, switch LE1, policies. Error detail: PolicyInfoSwitch._final_verification: fabric_name SITE8 does not exist on the controller.
100+
(ndfc-python) arobel@Allen-M4 examples %
101+
```
102+
103+
### Failure - Switch does not exist in fabric
104+
105+
``` bash title="Switch does not exist in fabric"
106+
(ndfc-python) arobel@Allen-M4 examples % ./policy_info_switch_generated_config.py --config config/s12/policy_info_switch_generated_config.yaml
107+
Error retrieving fabric SITE1, switch LE3, policies. Error detail: PolicyInfoSwitch._final_verification: switch_name LE3 not found in fabric SITE1.
108+
(ndfc-python) arobel@Allen-M4 examples %
109+
```

‎mkdocs.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,10 @@ nav:
9696
- network_attach.py: scripts/network_attach.md
9797
- network_create.py: scripts/network_create.md
9898
- network_delete.py: scripts/network_delete.md
99+
- policy_create.py: scripts/policy_create.md
100+
- policy_delete.py: scripts/policy_delete.md
101+
- policy_info_switch.py: scripts/policy_info_switch.md
102+
- policy_info_switch_generated_config.py: scripts/policy_info_switch_generated_config.md
99103
- reachability.py: scripts/reachability.md
100104
- rest_get_request.py: scripts/rest_get_request.md
101105
- rest_post_request.py: scripts/rest_post_request.md

0 commit comments

Comments
 (0)