Getting Started with the App

This document provides a step-by-step tutorial on how to get the App going and how to use it.

Install the App

To install the App, please follow the instructions detailed in the Installation Guide.

First steps with the App

After you have installed the app and set up the device with Nornir within Nautobot, you need to configure the app to run the validation rules.

The Operational Compliance app when installed only has the data structures for the validation rules, but no validation rules are defined. You need to define the validation rules that you want to run.

The main components of the app are, in the order that they are configured:

• Validation Rules: The core building blocks of the app, defining the rule type, description, and rule options (what to match in the comparison).
• Command Parsers: These are the commands that are run on the devices to gather the data for the validation rules, defining platform specific commands to run, JMESPath expressions for data extraction, and are associated with an existing validation rule.
• Validation Rule Groups: Associate one or more validation rules with a group, and define the order in which the commands are run.
• Collect Command Output: Run a validation rule or a validation rule group on the devices to gather the device data.
• Compare Command Outputs: Compare the data from two command outputs to determine if the validation rule passed or failed.

The high level steps to configure the app are:

1. Create a validation rule
2. Create a command parser
3. Create a validation rule group
4. Run collect command output twice with the same validation rule group to get two sets of data to compare
5. Run compare command outputs to compare the two sets of data

Quick Start

If you want to get started quickly, you can use the following script to create a validation rule, command parser, and validation rule group for an IOS device. It will create a validation rule for the device facts, and a command parser for the show version command. It will then create a validation rule group with the command parser, and enable the jobs so that the rules can be run.

from nautobot_operational_compliance.models import ValidationRule, CommandParser, ValidationRuleGroup, ValidationRuleTypeChoices, ParserTypeChoices
from nautobot.dcim.models import Platform
from nautobot.extras.models import Job

def create_operational_compliance_rules():
    """Create operational compliance rules for the Catalyst 8000."""

    # Get the platform
    ios_platform = Platform.objects.get(name="cisco_ios")

    # Create validation rule group
    validation_rule_group, _ = ValidationRuleGroup.objects.get_or_create(
        name="Catalyst 8000 Operational Compliance Rules",
        defaults={"description": "Operational compliance rules for Catalyst 8000 router"}
    )

    # Define rules for Catalyst 8000
    validation_rules_data = {
        "Device Facts": {
            "desc": "Gather device facts using NAPALM",
            "rule_type": ValidationRuleTypeChoices.EXACT_MATCH,
            "commands": [[ios_platform, "*", ParserTypeChoices.NAPALM, "get_facts"]],
        },
        "OS Version": {
            "desc": "Check OS version information",
            "rule_type": ValidationRuleTypeChoices.EXACT_MATCH,
            "commands": [[ios_platform, "[*].version", ParserTypeChoices.TEXTFSM, "show version"]],
        },
    }

    for rule_name, rule_details in validation_rules_data.items():
        validation_rule, created = ValidationRule.objects.get_or_create(
            name=rule_name,
            defaults={
                "rule_type": rule_details["rule_type"],
                "description": rule_details["desc"],
                "rule_options": rule_details.get("options"),
            }
        )

        if created:
            print(f"Created validation rule: {rule_name}")
        else:
            print(f"Validation rule already exists: {rule_name}")

        # Create command parsers
        for command in rule_details["commands"]:
            try:
                command_parser, created = CommandParser.objects.get_or_create(
                    parser=command[2],
                    path=command[1],
                    validation_rule=validation_rule,
                    command=command[3],
                    platform=command[0],
                )

                if created:
                    print(f"  Created command: {command[3]}")
            except Exception as e:
                print(f"  Error creating command {command[3]}: {e}")

        # Add validation rule to group
        validation_rule_group.validation_rules.add(validation_rule)

    print(f"Created validation rule group: {validation_rule_group.name}")

    return validation_rule_group


def enable_jobs():
    """Enable all operational compliance jobs."""
    Job.objects.filter(module_name__startswith="nautobot_operational_compliance.jobs").update(enabled=True)

Even though the script populates some sample data for the rules, command parsers and validation rule groups, you will still need to run the collection jobs yourself. These sample rules also do not have any validation rule options defined, so they will be very simple comparisons.

What are the next steps?

You can check out the Use Cases section for more examples.