Skip to content

IP Fabric Dynamic Attributes

ipf_dynamic_attributes is included in ipfabric>=7.5.2 and designed to automate the creation and management of dynamic attributes in IP Fabric environments. It provides a flexible configuration system for defining rules, filters, and attribute mappings, enabling streamlined attribute synchronization and reporting.

The external ipf_dynamic_attributes package will be archived and all development is now included in the SDK.

Features

  • Define dynamic attribute rules using YAML, JSON, TOML or Python configuration.
  • Support for static and calculated attribute values, including regex extraction and value mapping.
  • Support for regex-based searching of device configs.
  • Flexible filtering for inventory and device data.
  • Default dry-run mode for safe testing.
  • Creates a pandas DataFrame for easy data manipulation and reporting.
  • Multiple configuration files can be merged into a single file for easier management.
  • New in 1.2.4: Support for including other YAML, JSON, TOML files in YAML configurations using pyyaml-include.

Installation

PIP

To use the dynamic_attributes functionality, you can use pip:

pip install ipfabric[dynamic_attributes]

Running

Command Line Interface (CLI)

To run the utility from the command line, you can use the following command:

> ipf_dynamic_attributes [<path_to_config_file> ...]

For full usage information, you can run -h|--help:

Command Line Help
> ipf_dynamic_attributes -h
usage: ipf_dynamic_attributes.cmd [-h] [-f {csv,json,excel}] [-o OUTFILE] [-m] [-d {true,false,0,1}] [-u {true,false,0,1}] [-i IPFABRIC_OVERRIDE] [filenames ...]

IP Fabric Dynamic Attribute.

positional arguments:
  filenames             Configuration filename(s), defaults to 'config.yml'.

options:
  -h, --help            show this help message and exit
  -f {csv,json,excel}, --format {csv,json,excel}
                        Output format for the report. Default is 'csv'. Use 'json' for JSON output.
  -o OUTFILE, --outfile OUTFILE
                        Output filename to send report instead of standard out.
  -m, --merge-only      Merge the default rule settings into rules and display the resulting file; does not run any automation.
                        This will also merge multiple configuration files into a single file.
  -d {true,false,0,1}, --dry-run-override {true,false,0,1}
                        Override 'dry_run' setting in configuration(s); defaults to null to use value(s) in the config.
                        If specifying multiple config files, all 'dry_run' values must be the same unless this flag is set.
  -u {true,false,0,1}, --update-snapshot-override {true,false,0,1}
                        Override 'update_snapshot' setting in configuration(s); defaults to null to use value(s) in the config.
                        If specifying multiple config files, all 'update_snapshot' values must be the same unless this flag is set.
  -i IPFABRIC_OVERRIDE, --ipfabric-override IPFABRIC_OVERRIDE
                        Override 'ipfabric' setting in configurations; defaults to null to use value in the config file(s).
                        If specifying multiple config files, all 'ipfabric' values must be the same unless this flag is set to the name of the file to use the IP Fabric configuration settings from.     

    This script will run the AttributeSync with the provided configuration file(s) which defaults to 'config.yml'.
    You can specify a different or multiple configuration files by passing the filename as an argument:
    ipf_dynamic_attributes mgmt-ip.yml region.yml

Printing Merged Configurations

To merge the default rule settings into the rules and display the resulting file without running any automation, you can use the -m or --merge-only option. This will also merge multiple configuration files into a single file:

ipf_dynamic_attributes -m config.yml config2.yml

Python Script

Using a single configuration file:

Example using a Python Script
from ipfabric.dynamic_attributes import AttributeSync


if __name__ == "__main__":
    sync = AttributeSync(config="config.yaml")
    report = sync.run()
    print(report.to_csv())

Using multiple configuration files:

Multiconfig File Example
import json

from ipfabric.dynamic_attributes import AttributeSync, MultiConfig
from ipfabric.dynamic_attributes.configs import IPFabric

multi = MultiConfig(
    configs=["cfgs/mgmt.yml", "cfgs/http.yml", "cfgs/region.yml"],
    dry_run_override=True,  # Does not require all configs to have the same value
    update_snapshot_override=True,  # Does not require all configs to have the same value
    ipfabric_override=IPFabric(snapshot_id="$lastLocked"),  # Does not require all configs to have the same value
)
sync = AttributeSync(config=multi)
report = sync.run()

print(json.dumps(sync.config.model_dump()))

Using the ipf_webhook_listener

First lets create a .env file with our secrets:

IPF_URL=https://demo.ipf.cx/
IPF_TOKEN=971a3b221fd09cfae12341d01eb51281
ipf_secret=5b71eecda8fcf68c3f997ce9e963ea23
# Your Dynamic Attribute config file must be an ENV if it is not named config.yml
config_file=example.yaml

Next lets create a Python file for the automation:

"""webhook_automation.py"""

import os
import dotenv
from typing import Any
from ipfabric import IPFClient
from ipfabric.dynamic_attributes import AttributeSync
from ipfabric.models import WebhookEvent

# First load the .env file
dotenv.load_dotenv(".env")  # Path to .env file

# Next get the Config File variable and load the Attribute Sync
# If there are any errors in the config file then the API will fail to start
# Initializing within the function will cause it to fail when an event occurs
SYNC = AttributeSync(config=os.getenv("config_file"))
# The Config File must be an environment variable since we are loading it here and settings are not passed to the module.


def run_dynamic_attributes(event: WebhookEvent, settings: Any, **kwargs):
    """
    The following information is passed to the function via kwargs:
        - event: The WebhookEvent instance containing the event data.
        - settings: The WebhookConfig[custom_settings] you provided in the command line via --custom_settings.

    Please ensure your function contains '**kwargs' to accept any parameters passed as they may change in future versions.
    """
    if event.test:
        # Testing Event is always passed to your function so it is your responsibility to handle it.
        print("This is a test event.")
        return

    if event.status == "completed":
        # First change Snapshot to the one received in the event:
        SYNC.config.ipfabric.snapshot_id = event.snapshotId
        # Next run the automation:
        report = SYNC.run()
        # Finally do something with the report (email, chat, log):
        print(report.to_csv())

Finally run the webhook listener:

Run IPF Webhook Listener with Custom Handlers
> ipf_webhook_listener \
--intent_method="webhook_automation.py:run_dynamic_attributes" \
--intent_scheduled_only=1
  • Because changing attributes causes recalculation we want to run after the Snapshot is completely loaded which is after an Intent Verification Webhook is received.
  • The method says to look in the webhook_automation.py file and run the run_dynamic_attributes method when an Intent Webhook is received.
    • Since no snapshot_method is provided no automation will be run after receiving a Snapshot Event.
  • We only want to run this after scheduled snapshots (default) instead of manual or modified snapshots.
    • Please note you must have IP Fabric send both Snapshot and Intent Verification Webhooks for this to properly calculate if the initiator was a scheduled snapshot.