Creating New Clean Stages

New Clean Stages can be written and contributed to add functionality if pyATS Clean does not currently meet your cleaning requirements.

The following steps outline how to create a new Clean Stage.

  1. Determine what OS and Platform the new Clean Stage is designed for

  2. Create a new python function inside the correct stages.py file

  3. Adding stage arguments and schema

  4. Add a docstring to the Clean Stage

  5. Adding the python code the stage requires

  6. Testing the new Stage

  7. Contributing the new Stage into the repository

Determine what OS and Platform the new Clean Stage is designed for

Determine if the Clean Stage will work for all OSs and Platforms (therefore, would be designated as a ‘Common’ Clean Stage vs. one written for a specific device type). This is required to determine what stages.py file the clean stage would belong in.

  • Common Clean Stages reside in the stages/stages.py file.
    For example, the Common Clean Stages belong here.
  • OS-specific Clean Stages reside in the stages/<os>/stages.py file.
    For example, the IOSXE specific Clean Stages belong here.
  • Platform-specific Clean Stages reside in the stages/<os>/<platform>/stages.py file.
    For example, the IOSXE CAT9K Clean Stages belong here.

Create a new python function inside the correct stages.py file

The function needs to be an aetest.test section. The required arguments for any Clean Stage is are section, steps, and device.

1
2
@aetest.test
def verify_running_image(section, steps, device):

Adding stage arguments and schema

The schema defines what arguments the stage can accept and what format they follow. In this example we want to pass a list of images to the stage.

1
2
3
4
5
@clean_schema({
    Optional('images'): list
})
@aetest.test
def verify_running_image(section, steps, device, images):

Add a docstring to the Clean Stage

The below code block is just an example however, the docstring should follow the same format.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
@clean_schema({
    Optional('images'): list
})
@aetest.test
def verify_running_image(section, steps, device, images):
    """ This stage verifies the currently running image is the expected image.

    Stage Schema
    ------------
    verify_running_image:
        images (list): Images that are expected to be running

    Example
    -------
    verify_running_image:
        images:
            - test_image.gbin

    """

Adding the python code the stage requires

The below code block is just an example. The code is dependant on what the stage should accomplish.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
@clean_schema({
    Optional('images'): list
})
@aetest.test
def verify_running_image(section, steps, device, images):
    """ This stage verifies the currently running image is the expected image.

    Stage Schema
    ------------
    verify_running_image:
        images (list): Images that are expected to be running

    Example
    -------
    verify_running_image:
        images:
            - test_image.gbin

    """

    log.info("Section steps:\n1- Verify the running image on the device")

    # Verify running image on the device
    with steps.start("Verify running image on device {}".\
                     format(device.name)) as step:
        try:
            device.api.verify_current_image(images=images)
        except Exception as e:
            step.failed("Unable to verify running image on device {}\n{}".\
                           format(device.name, str(e)))
        else:
            section.passed("Successfully verified running image on device {}".\
                           format(device.name))

Testing the new Stage

In order to test or even use the newly developed Clean Stage, it needs to be accessible to pyATS Clean. To do this you must execute make json from the root folder of the cloned genielibs repository.

This command will update a json file that contains the information required for pyATS Clean to find clean stages.

After running the command, you can add the clean stage to your Clean YAML file and run it as normal.

Contributing the new Stage into the repository

Once satisfied with the Clean Stage, you may commit your changes and open a pull request against the genielibs repository. We will review the pull request and once satisfied we will merge the Clean Stage.

This stage will be available in the next official release.