|
| 1 | +# Implementing custom validators |
| 2 | + |
| 3 | +With custom validators, you can implement business logic in Python. Schema-enforcer will automatically |
| 4 | +load your plugins from the `validator_directory` and run them against your host data. |
| 5 | + |
| 6 | +The validator plugin provides two base classes: ModelValidation and JmesPathModelValidation. The former can be used |
| 7 | +when you want to implement all logic and the latter can be used as a shortcut for jmespath validation. |
| 8 | + |
| 9 | +## BaseValidation |
| 10 | + |
| 11 | +Use this class to implement arbitrary validation logic in Python. In order to work correctly, your Python script must meet |
| 12 | +the following criteria: |
| 13 | + |
| 14 | +1. Exist in the `validator_directory` dir. |
| 15 | +2. Include a subclass of the BaseValidation class to correctly register with schema-enforcer. |
| 16 | +3. Ensure you call `super().__init__()` in your class `__init__` if you override. |
| 17 | +4. Provide a class method in your subclass with the following signature: |
| 18 | +`def validate(data: dict, strict: bool):` |
| 19 | + |
| 20 | + * Data is a dictionary of variables on a per-host basis. |
| 21 | + * Strict is set to true when the strict flag is set via the CLI. You can use this to offer strict validation behavior |
| 22 | + or ignore it if not needed. |
| 23 | + |
| 24 | +The name of your class will be used as the schema-id for mapping purposes. You can override the default schema ID |
| 25 | +by providing a class-level `id` variable. |
| 26 | + |
| 27 | +Helper functions are provided to add pass/fail results: |
| 28 | + |
| 29 | +``` |
| 30 | +def add_validation_error(self, message: str, **kwargs): |
| 31 | + """Add validator error to results. |
| 32 | + Args: |
| 33 | + message (str): error message |
| 34 | + kwargs (optional): additional arguments to add to ValidationResult when required |
| 35 | + """ |
| 36 | +
|
| 37 | +def add_validation_pass(self, **kwargs): |
| 38 | + """Add validator pass to results. |
| 39 | + Args: |
| 40 | + kwargs (optional): additional arguments to add to ValidationResult when required |
| 41 | + """ |
| 42 | +``` |
| 43 | +In most cases, you will not need to provide kwargs. However, if you find a use case that requires updating other fields |
| 44 | +in the ValidationResult, you can send the key/value pairs to update the result directly. This is for advanced users only. |
| 45 | + |
| 46 | +## JmesPathModelValidation |
| 47 | + |
| 48 | +Use this class for basic validation using [jmespath](https://jmespath.org/) expressions to query specific values in your data. In order to work correctly, your Python script must meet |
| 49 | +the following criteria: |
| 50 | + |
| 51 | +1. Exist in the `validator_directory` dir. |
| 52 | +2. Include a subclass of the JmesPathModelValidation class to correctly register with schema-enforcer. |
| 53 | +3. Provide the following class level variables: |
| 54 | + |
| 55 | + * `top_level_properties`: Field for mapping of validator to data |
| 56 | + * `id`: Schema ID to use for reporting purposes (optional - defaults to class name) |
| 57 | + * `left`: Jmespath expression to query your host data |
| 58 | + * `right`: Value or a compiled jmespath expression |
| 59 | + * `operator`: Operator to use for comparison between left and right hand side of expression |
| 60 | + * `error`: Message to report when validation fails |
| 61 | + |
| 62 | +### Supported operators: |
| 63 | + |
| 64 | +The class provides the following operators for basic use cases: |
| 65 | + |
| 66 | +``` |
| 67 | +"gt": int(left) > int(right), |
| 68 | +"gte": int(left) >= int(right), |
| 69 | +"eq": left == right, |
| 70 | +"lt": int(left) < int(right), |
| 71 | +"lte": int(left) <= int(right), |
| 72 | +"contains": right in left, |
| 73 | +``` |
| 74 | + |
| 75 | +If you require additional logic or need to compare other types, use the BaseValidation class and create your own validate method. |
| 76 | + |
| 77 | +### Examples: |
| 78 | + |
| 79 | +#### Basic |
| 80 | +``` |
| 81 | +from schema_enforcer.schemas.validator import JmesPathModelValidation |
| 82 | +
|
| 83 | +class CheckInterface(JmesPathModelValidation): # pylint: disable=too-few-public-methods |
| 84 | + top_level_properties = ["interfaces"] |
| 85 | + id = "CheckInterface" # pylint: disable=invalid-name |
| 86 | + left = "interfaces.*[@.type=='core'][] | length([?@])" |
| 87 | + right = 2 |
| 88 | + operator = "gte" |
| 89 | + error = "Less than two core interfaces" |
| 90 | +``` |
| 91 | + |
| 92 | +#### With compiled jmespath expression |
| 93 | +``` |
| 94 | +import jmespath |
| 95 | +from schema_enforcer.schemas.validator import JmesPathModelValidation |
| 96 | +
|
| 97 | +
|
| 98 | +class CheckInterfaceIPv4(JmesPathModelValidation): # pylint: disable=too-few-public-methods |
| 99 | + top_level_properties = ["interfaces"] |
| 100 | + id = "CheckInterfaceIPv4" # pylint: disable=invalid-name |
| 101 | + left = "interfaces.*[@.type=='core'][] | length([?@])" |
| 102 | + right = jmespath.compile("interfaces.* | length([[email protected]=='core'][].ipv4)") |
| 103 | + operator = "eq" |
| 104 | + error = "All core interfaces do not have IPv4 addresses" |
| 105 | +``` |
| 106 | + |
| 107 | +## Running validators |
| 108 | + |
| 109 | +Custom validators are run with `schema-enforcer validate` and `schema-enforcer ansible` commands. |
| 110 | + |
| 111 | +You map validators to keys in your data with `top_level_properties` in your subclass or with `schema_enforcer_schema_ids` |
| 112 | +in your data. Schema-enforcer uses the same process to map custom validators and schemas. Refer to the "Mapping Schemas" documentation |
| 113 | +for more details. |
| 114 | + |
| 115 | +### Example - top_level_properties |
| 116 | + |
| 117 | +The CheckInterface validator has a top_level_properties of "interfaces": |
| 118 | + |
| 119 | +``` |
| 120 | +class CheckInterface(JmesPathModelValidation): # pylint: disable=too-few-public-methods |
| 121 | + top_level_properties = ["interfaces"] |
| 122 | +``` |
| 123 | + |
| 124 | +With automapping enabled, this validator will apply to any host with a top-level `interfaces` key in the Ansible host_vars data: |
| 125 | + |
| 126 | +``` |
| 127 | +--- |
| 128 | +hostname: "az-phx-pe01" |
| 129 | +pair_rtr: "az-phx-pe02" |
| 130 | +interfaces: |
| 131 | + MgmtEth0/0/CPU0/0: |
| 132 | + ipv4: "172.16.1.1" |
| 133 | + Loopback0: |
| 134 | + ipv4: "192.168.1.1" |
| 135 | + ipv6: "2001:db8:1::1" |
| 136 | + GigabitEthernet0/0/0/0: |
| 137 | + ipv4: "10.1.0.1" |
| 138 | + ipv6: "2001:db8::" |
| 139 | + peer: "az-phx-pe02" |
| 140 | + peer_int: "GigabitEthernet0/0/0/0" |
| 141 | + type: "core" |
| 142 | + GigabitEthernet0/0/0/1: |
| 143 | + ipv4: "10.1.0.37" |
| 144 | + ipv6: "2001:db8::12" |
| 145 | + peer: "co-den-p01" |
| 146 | + peer_int: "GigabitEthernet0/0/0/2" |
| 147 | + type: "core" |
| 148 | +``` |
| 149 | + |
| 150 | +### Example - manual mapping |
| 151 | + |
| 152 | +Alternatively, you can manually map a validator in your Ansible host vars or other data files. |
| 153 | + |
| 154 | +``` |
| 155 | +schema_enforcer_automap_default: false |
| 156 | +schema_enforcer_schema_ids: |
| 157 | + - "CheckInterface" |
| 158 | +``` |
0 commit comments