Triggers
Triggers perform a specific action, or a sequence of actions, on a device to alter its state and/or configuration. As examples, actions may include adding/removing parts of a configuration, flapping protocols/interfaces, or performing high availability (HA) events such as rebooting a device. The important part to understand is that triggers are what alter the device during testing.
The pyATS library (Genie) has many prebuilt triggers available for Cisco IOS/IOS XE, NX-OS, and IOS XR. All prebuilt triggers are documented, describing what happens when the trigger is initiated and what keys/values to include in the trigger datafile specifically for that trigger. For example, the TriggerShutNoShutBgpNeighbors trigger performs the following workflow:
Learn BGP Ops object and verify it has “established” neighbors. If there aren’t any “established” neighbors, skip the trigger.
Shut the BGP neighbor that was learned from step 1 with the BGP Conf object.
Verify the state of the learned neighbor(s) in step 2 is “down.”
Unshut the BGP neighbor(s).
Learn BGP Ops again and verify it is the same as the BGP Ops snapshot in step 1.
As you might recall from earlier in this chapter, the Genie Ops object represents a device/feature’s operational state via a Python object, and the Genie Conf object represents a feature, as a Python object, that can be configured on a device. The focus of the Conf object is what feature you want to apply on the device, not how to apply it per device (OS) platform. This allows a network engineer to focus on the network features being tested and not on the low-level details of how the configuration is applied.
Now that there’s a general understanding of what triggers do, let’s check out how they can be configured using a trigger datafile.
Trigger Datafile
As with other features of the pyATS library (Genie), to run triggers, there needs to be a datafile—more specifically, a trigger datafile (trigger_datafile.yaml). The pyATS library provides a default trigger datafile found in the same location as all the other default datafiles, discussed earlier in the chapter. However, if you want to customize any specific trigger settings, such as what devices or group of devices to run on during testing (any device besides uut), or to run a custom trigger, you’ll need to create your own trigger datafile. A complete example can be found at the end of the chapter that includes both triggers and verifications, but let’s focus now on just triggers in a brief example. Example 9-11 shows a custom trigger file that flaps the OSPF process on the targeted devices (iosv-0 and iosv01). Example 9-12 shows how to include the appropriate trigger and trigger datafile in the list of arguments to gRun.
Example 9-11 Trigger Datafile – ex0912_trigger_datafile.yaml
extends: "%CALLABLE{genie.libs.sdk.genie_yamls.datafile(trigger)}"
# Custom trigger - created in Example 9-14
TriggerShutNoShutOspf:
# source imports the custom trigger, just as you would any other Python class
source:
class: ex0915_custom_trigger.ShutNoShutOspf
devices: ["iosv-0", "iosv-1"]
Example 9-12 gRun – Triggers and Trigger Datafile
from genie.harness.main import gRun
def main():
gRun(
trigger_uids=["TriggerShutNoShutOspf"],
trigger_datafile="ex0912_trigger_datafile.yaml"
)
Trigger Cluster
The last neat trigger feature to cover is the ability to execute a group of multiple triggers and verifications in one cluster trigger. First, a trigger datafile must be created with the list of triggers and verifications, the order in which to run them, and a list of testbed devices to run them against. Example 9-13 shows a trigger datafile configured for a trigger cluster and the accompanying test results if it was run.
Example 9-13 Trigger Cluster
TriggerCombined:
sub_verifications: ['Verify_BgpVrfAllAll']
sub_triggers: [ 'TriggerSleep', 'TriggerShutNoShutBgp']
sub_order: ['TriggerSleep', 'Verify_BgpVrfAllAll',
'TriggerSleep','TriggerShutNoShutBgp','Verify_BgpVrfAllAll']
devices: ['uut']
-- TriggerCombined.uut PASSED
|-- TriggerSleep_sleep.1 PASSED
|-- TestcaseVerificationOps_verify.2 PASSED
|-- TriggerSleep_sleep.3 PASSED
|-- TriggerShutNoShutBgp_verify_prerequisite.4 PASSED
| |-- Step 1: Learning 'Bgp' Ops PASSED
| |-- Step 2: Verifying requirements PASSED
| '-- Step 3: Merge requirements PASSED
|-- TriggerShutNoShutBgp_shut.5 PASSED
| '-- Step 1: Configuring 'Bgp' PASSED
|-- TriggerShutNoShutBgp_verify_shut.6 PASSED
| '-- Step 1: Verifying 'Bgp' state with ops.bgp.bgp.Bgp PASSED
|-- TriggerShutNoShutBgp_unshut.7 PASSED
| '-- Step 1: Unconfiguring 'Bgp' PASSED
|-- TriggerShutNoShutBgp_verify_initial_state.8 PASSED
| '-- Step 1: Verifying ops 'Bgp' is back to original state PASSED
'-- TestcaseVerificationOps_verify.9 PASSED
You may notice that the triggers have accompanying local verifications that run before and after the trigger is run to ensure the action was actually taken against the device. This is the true power of triggers. One of the biggest reasons people are skeptical about network automation is due to the lack of trust. Did this automation script/test really do what it’s supposed to do? Triggers provide that verification out of the box through global and local verifications.
What if we wanted to build our own trigger with verifications? In the next section, you’ll see how to do just that!
Writing a Trigger
The pyATS library (Genie) provides the ability to write your own triggers. A trigger is simply a Python class that has multiple tests in it that either configure, verify, or unconfigure the configuration or device feature you’re trying to test.
To begin, your custom trigger must inherit from a base Trigger class. This base class contains common setup and cleanup tasks that help identify any unexpected changes to testbed devices not currently under testing (for example, a device rebooting). For our custom trigger, we are going to shut and unshut OSPF. Yes, this trigger already exists in the library, but it serves as a great example when you’re beginning to create custom triggers. The workflow is going to look like this:
Check that OSPF is configured and running.
Shut down the OSPF process.
Verify that OSPF is shut down.
Unshut the OSPF process.
Verify OSPF is up and running.
In Examples 9-14 and 9-15, you’ll see the code to create the custom OSPF trigger and the associated job file, running it with gRun. To run the job file, you’ll need the following files:
ex0915_custom_trigger.py
ex0916_custom_trigger_job.py
ex0915_custom_trigger_datafile.yaml
testbed2.yaml
The testbed2.yaml file has two IOSv routers, named “iosv-0” and “iosv-1,” running OSPF. The file ex0915_custom_trigger_datafile.yaml is used to map the custom OSPF triggers and the testbed devices:
# ex0915_custom_trigger_datafile.yaml
extends: "%CALLABLE{genie.libs.sdk.genie_yamls.datafile(trigger)}"
# Custom trigger
TriggerMyShutNoShutOspf:
# source imports the custom trigger
source:
class: ex0915_custom_trigger.MyShutNoShutOspf
devices: ["iosv-0", "iosv-1"]
Example 9-14 Custom Trigger and Job File
import time
import logging
from pyats import aetest
from genie.harness.base import Trigger
from genie.metaparser.util.exceptions import SchemaEmptyParserError
log = logging.getLogger()
class MyShutNoShutOspf(Trigger):
"""Shut and unshut OSPF process. Verify both actions."""
@aetest.setup
def prerequisites(self, uut):
"""Check whether OSPF is configured and running."""
# Checks if OSPF is configured. If not, skip this trigger
try:
output = uut.parse("show ip ospf")
except SchemaEmptyParserError:
self.failed(f"OSPF is not configured on device {uut.name}")
# Extract the OSPF process ID
self.ospf_id = list(output["vrf"]["default"]["address_family"] ["ipv4"]["instance"].keys())[0]
# Checks if the OSPF process is enabled
ospf_enabled = output["vrf"]["default"]["address_family"] ["ipv4"]["instance"][self.ospf_id]["enable"]
if not ospf_enabled:
self.skipped(f"OSPF is not enabled on device {uut.name}")
@aetest.test
def ShutOspf(self, uut):
"""Shutdown the OSPF process"""
uut.configure(f"router ospf {self.ospf_id}\n shutdown")
time.sleep(5)
@aetest.test
def verify_ShutOspf(self, uut):
"""Verify ShutOspf worked"""
output = uut.parse("show ip ospf")
ospf_enabled = output["vrf"]["default"]["address_family"] ["ipv4"]["instance"][self.ospf_id]["enable"]
if ospf_enabled:
self.failed(f"OSPF is enabled on device {uut.name}")
@aetest.test
def NoShutOspf(self, uut):
"""Unshut the OSPF process"""
uut.configure(f"router ospf {self.ospf_id}\n no shutdown")
@aetest.test
def verify_NoShutOspf(self, uut):
"""Verify NoShutOspf worked"""
output = uut.parse("show ip ospf")
ospf_enabled = output["vrf"]["default"]["address_family"] ["ipv4"]["instance"][self.ospf_id]["enable"]
if not ospf_enabled:
self.failed(f"OSPF is enabled on device {uut.name}")
Example 9-15 Running a Custom Trigger – ex0915_custom_trigger_job.py
from genie.harness.main import gRun
def main():
gRun(
trigger_uids=["TriggerMyShutNoShutOspf"],
trigger_datafile="ex0915_custom_trigger_datafile.yaml",
)
# Running the job using 'pyats run job' command
# pyats run job ex0916_custom_trigger_job.py --testbed-file testbed2.yaml
Figure 9-3 shows some sample job output.
x)
Figure 9.3 Job Results