policy_*.py example scripts: Add documentation

docs/scripts/policy_create.md

@@ -0,0 +1,81 @@
+# policy_create.py
+
+## Description
+
+Create one or more policies.
+
+## Notes
+
+1. All policy scripts use `description` as a unique key to identify a policy.
+
+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.
+
+## Example configuration file
+
+``` yaml title="config/policy_create.yaml"
+---
+config:
+  - switch_name: LE1
+    fabric_name: SITE1
+    description: management vrf static route to syslog server
+    entity_name: SWITCH
+    entity_type: SWITCH
+    priority: 200
+    source: ""
+    template_name: vrf_static_route
+    nv_pairs:
+      IP_PREFIX: 192.168.7.1/32
+      NEXT_HOP_IP: 192.168.12.1
+      VRF_NAME: management
+  - switch_name: LE2
+    fabric_name: SITE2
+    description: management vrf static route to syslog server
+    entity_name: SWITCH
+    entity_type: SWITCH
+    priority: 200
+    source: ""
+    template_name: vrf_static_route
+    nv_pairs:
+      IP_PREFIX: 192.168.7.1/32
+      NEXT_HOP_IP: 192.168.12.1
+      VRF_NAME: management
+```
+
+## Example Usage
+
+The example below uses environment variables for credentials, so requires
+only the `--config` argument.  See [Running the Example Scripts]
+for details around specifying credentials from the command line, from
+environment variables, from Ansible Vault, or a combination of these
+credentials sources.
+
+[Running the Example Scripts]: ../setup/running-the-example-scripts.md
+
+``` bash
+export ND_DOMAIN=local
+export ND_IP4=192.168.7.7
+export ND_PASSWORD=MySecretPassword
+export ND_USERNAME=admin
+./policy_create.py --config config/policy_create.yaml
+# output not shown
+```
+
+## Example output
+
+### Success
+
+``` bash title="Policies created successfully"
+(ndfc-python) arobel@Allen-M4 examples % ./policy_create.py --config config/s12/policy_create.yaml
+Created fabric SITE1, switch LE1, policy_id POLICY-76120.
+Created fabric SITE2, switch LE2, policy_id POLICY-76130.
+(ndfc-python) arobel@Allen-M4 examples %
+```
+
+### Failure - Policy create request rejected because a policy with the same description already exists
+
+``` bash title="Policy exists"
+(ndfc-python) arobel@Allen-M4 examples % ./policy_create.py --config config/s12/policy_create.yaml
+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.
+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.
+(ndfc-python) arobel@Allen-M4 examples %
+```

docs/scripts/policy_delete.md

@@ -0,0 +1,71 @@
+# policy_delete.py
+
+## Description
+
+Delete one or more policies.
+
+## Notes
+
+1. All policy scripts use `description` as a unique key to identify a policy.
+
+The implication when deleting policies is that a delete request will be rejected if multiple policies on the controller have the same `description`.
+
+## Example configuration file
+
+``` yaml title="config/policy_delete.yaml"
+---
+config:
+  - switch_name: LE3
+    fabric_name: SITE3
+    description: management vrf static route to syslog server
+  - switch_name: LE4
+    fabric_name: SITE4
+    description: management vrf static route to syslog server
+```
+
+## Example Usage
+
+The example below uses environment variables for credentials, so requires
+only the `--config` argument.  See [Running the Example Scripts]
+for details around specifying credentials from the command line, from
+environment variables, from Ansible Vault, or a combination of these
+credentials sources.
+
+[Running the Example Scripts]: ../setup/running-the-example-scripts.md
+
+``` bash
+export ND_DOMAIN=local
+export ND_IP4=192.168.7.7
+export ND_PASSWORD=MySecretPassword
+export ND_USERNAME=admin
+./policy_delete.py --config config/policy_delete.yaml
+# output not shown
+```
+
+## Example output
+
+### Success
+
+``` bash title="Policies deleted successfully"
+(ndfc-python) arobel@Allen-M4 examples % ./policy_delete.py --config config/s12/policy_delete.yaml
+Deleted fabric SITE1, switch LE1, policy_id POLICY-76120
+Deleted fabric SITE2, switch LE2, policy_id POLICY-76130
+(ndfc-python) arobel@Allen-M4 examples %
+```
+
+### Failure - Policies do not exist
+
+``` bash title="Policies do not exist"
+(ndfc-python) arobel@Allen-M4 examples % ./policy_delete.py --config config/s12/policy_delete.yaml
+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'
+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'
+(ndfc-python) arobel@Allen-M4 examples %
+```
+
+### Failure - Policy delete request rejected because multiple policies with the same description exist on the controller
+
+``` bash title="Policy exists"
+(ndfc-python) arobel@Allen-M4 examples % ./policy_delete.py --config config/s12/policy_delete.yaml
+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'],
+(ndfc-python) arobel@Allen-M4 examples %
+```

docs/scripts/policy_info_switch.md

@@ -0,0 +1,99 @@
+# policy_info_switch.py
+
+## Description
+
+Retrieve all policies for one or more switches.
+
+## Example configuration file
+
+``` yaml title="config/policy_info_switch.yaml"
+---
+config:
+  - switch_name: LE1
+    fabric_name: SITE1
+  - switch_name: LE2
+    fabric_name: SITE2
+```
+
+## Example Usage
+
+The example below uses environment variables for credentials, so requires
+only the `--config` argument.  See [Running the Example Scripts]
+for details around specifying credentials from the command line, from
+environment variables, from Ansible Vault, or a combination of these
+credentials sources.
+
+[Running the Example Scripts]: ../setup/running-the-example-scripts.md
+
+``` bash
+export ND_DOMAIN=local
+export ND_IP4=192.168.7.7
+export ND_PASSWORD=MySecretPassword
+export ND_USERNAME=admin
+./policy_info_switch.py --config config/policy_info_switch.yaml
+# output not shown
+```
+
+## Example output
+
+### Success
+
+``` bash title="Policies retrieved successfully"
+(ndfc-python) arobel@Allen-M4 examples % ./policy_info_switch.py --config config/s12/policy_info_switch.yaml
+SITE1, LE1, policies: 
+```
+
+``` json
+{
+    "autoGenerated": true,
+    "deleted": false,
+    "editable": true,
+    "entityName": "SWITCH",
+    "entityType": "SWITCH",
+    "fabricName": "SITE1",
+    "generatedConfig": "",
+    "id": 21160,
+    "ipAddress": "192.168.12.151",
+    "modifiedOn": 1758053377477,
+    "nvPairs": {
+        "MARK_DELETED": "false",
+        "POLICY_DESC": "",
+        "POLICY_ID": "POLICY-21160",
+        "PRIORITY": "10",
+        "id": "0"
+    },
+    "policyId": "POLICY-21160",
+    "priority": 10,
+    "resourcesLinked": "",
+    "serialNumber": "9WPLALSNXK6",
+    "source": "",
+    "statusOn": 1758053377477,
+    "switchName": "LE1",
+    "templateContentType": "PYTHON",
+    "templateName": "bgp_lb_id"
+}
+```
+
+etc...
+
+```bash
+(ndfc-python) arobel@Allen-M4 examples %
+```
+
+### Failure - Fabric does not exist
+
+``` bash title="Fabric does not exist"
+(ndfc-python) arobel@Allen-M4 examples % ./policy_info_switch.py --config config/s12/policy_info_switch.yaml
+Error retrieving fabric SITE3, switch LE1, policies. Error detail: PolicyInfoSwitch._final_verification: fabric_name SITE3 does not exist on the controller.
+Error retrieving fabric SITE4, switch LE2, policies. Error detail: PolicyInfoSwitch._final_verification: fabric_name SITE4 does not exist on the controller.
+(ndfc-python) arobel@Allen-M4 examples %
+```
+
+### Failure - Switch does not exist in fabric
+
+``` bash title="Switch does not exist in fabric"
+(ndfc-python) arobel@Allen-M4 examples % ./policy_info_switch.py --config config/s12/policy_info_switch.yaml
+Error retrieving fabric SITE1, switch LE3, policies. Error detail: PolicyInfoSwitch._final_verification: switch_name LE3 not found in fabric SITE1.
+Error retrieving fabric SITE2, switch LE4, policies. Error detail: PolicyInfoSwitch._final_verification: switch_name LE4 not found in fabric SITE2.
+(ndfc-python) arobel@Allen-M4 examples %
+```

docs/scripts/policy_info_switch_generated_config.md

@@ -0,0 +1,109 @@
+# policy_info_switch_generated_config.py
+
+## Description
+
+Retrieve all policies for one or more switches and display their generated configs.
+
+## Example configuration file
+
+``` yaml title="config/policy_info_switch_generated_config.yaml"
+---
+config:
+  - switch_name: LE1
+    fabric_name: SITE1
+  - switch_name: LE2
+    fabric_name: SITE2
+```
+
+## Example Usage
+
+The example below uses environment variables for credentials, so requires
+only the `--config` argument.  See [Running the Example Scripts]
+for details around specifying credentials from the command line, from
+environment variables, from Ansible Vault, or a combination of these
+credentials sources.
+
+[Running the Example Scripts]: ../setup/running-the-example-scripts.md
+
+``` bash
+export ND_DOMAIN=local
+export ND_IP4=192.168.7.7
+export ND_PASSWORD=MySecretPassword
+export ND_USERNAME=admin
+./policy_info_switch_generated_config.py --config config/policy_info_switch_generated_config.yaml
+# output not shown
+```
+
+## Example output
+
+### Success
+
+``` bash title="Policies retrieved successfully"
+(ndfc-python) arobel@Allen-M4 examples % ./policy_info_switch_generated_config.py --config config/s12/policy_info_switch_generated_config.yaml
+SITE1, LE1, policies:
+power redundancy-mode ps-redundant
+copp profile strict
+feature dhcp
+ipv6 switch-packets lla
+feature ospf
+feature pim
+nv overlay evpn
+feature interface-vlan
+feature vn-segment-vlan-based
+feature lldp
+feature nv overlay
+feature bgp
+feature nxapi
+cfs eth distribute
+feature lacp
+feature ngoam
+username admin password 5 $5$BEJAMJ$ujNFizvgASVsw3a2RACVBgXpCOBVbmNE5Esh/vDc4ET role network-admin
+service dhcp
+ip dhcp relay
+ip dhcp relay information option
+ip dhcp relay information option vpn
+ipv6 dhcp relay
+system jumbomtu 9216
+route-map FABRIC-RMAP-REDIST-SUBNET permit 10
+  match tag 12345
+router bgp 65001
+  router-id 10.11.0.2
+router ospf UNDERLAY
+  router-id 10.11.0.2
+ip pim ssm range 232.0.0.0/8
+ip pim rp-address 10.13.254.1 group-list 239.1.1.0/25
+nxapi https port 443
+nxapi http port 80
+
+
+snmp-server host 192.168.12.12 traps version 2c public udp-port 2162
+
+
+hostname LE1
+no password strength-check
+evpn
+fabric forwarding anycast-gateway-mac 2020.0000.00aa
+vrf context management
+  ip route 0.0.0.0/0 192.168.12.1
+vrf context management
+  ip route 0.0.0.0/0 192.168.12.1
+vlan 1
+line vty
+etc...
+```
+
+### Failure - Fabric does not exist
+
+``` bash title="Fabric does not exist"
+(ndfc-python) arobel@Allen-M4 examples % ./policy_info_switch_generated_config.py --config config/s12/policy_info_switch_generated_config.yaml
+Error retrieving fabric SITE8, switch LE1, policies. Error detail: PolicyInfoSwitch._final_verification: fabric_name SITE8 does not exist on the controller.
+(ndfc-python) arobel@Allen-M4 examples %
+```
+
+### Failure - Switch does not exist in fabric
+
+``` bash title="Switch does not exist in fabric"
+(ndfc-python) arobel@Allen-M4 examples % ./policy_info_switch_generated_config.py --config config/s12/policy_info_switch_generated_config.yaml
+Error retrieving fabric SITE1, switch LE3, policies. Error detail: PolicyInfoSwitch._final_verification: switch_name LE3 not found in fabric SITE1.
+(ndfc-python) arobel@Allen-M4 examples %
+```

mkdocs.yml

@@ -96,6 +96,10 @@ nav:
       - network_attach.py: scripts/network_attach.md
       - network_create.py: scripts/network_create.md
       - network_delete.py: scripts/network_delete.md
+      - policy_create.py: scripts/policy_create.md
+      - policy_delete.py: scripts/policy_delete.md
+      - policy_info_switch.py: scripts/policy_info_switch.md
+      - policy_info_switch_generated_config.py: scripts/policy_info_switch_generated_config.md
       - reachability.py: scripts/reachability.md
       - rest_get_request.py: scripts/rest_get_request.md
       - rest_post_request.py: scripts/rest_post_request.md