evc_manager 1.3.14

No project description provided

AmLight Ethernet Virtual Circuit (EVC) Manager

The AmLight EVC Manager is a command line tool to help SDN operators in managing Ethernet Virtual Circuits (EVC), such as creating/deleting/changing multiple EVCs at a time. It was created to help AmLight network engineers in the daily operation of the AmLight SDN network, which currently has more than one thousands flows and more than ten OpenFlow switches in North and South America.

The AmLight EVC_Manager requires Python 3.6+

Features

The EVC Manager was created with the following major goals:

• Supporting multiple backends, such as OESS and Kytos E-Line.
• Supporting exporting EVCs to YAML or JSON files
• Supporting creating/changing/deleting multiple EVCs via YAML files
• Supporting moving EVCs out a specific link (or NNI)
• Supporting forcing circuit reprovisioning
• Supporting changing EVCs' paths
• Supporting exporting monitoring data using Zabbix LLD format for integration with Zabbix
• Supporting multiple queries:
  • Get VLANs in use in a specific UNI or NNI
  • Get EVCs using a specific UNI or NNI
  • Get EVC utilization
  • Get list of EVCs with under-provisioned paths
  • Get EVCs using backup paths
  • Get list of devices and links
  • Compare and report two EVC dumps

Current Version

The current version of EVC Manager is 1.3. The following major features are supported:

• Supporting for OESS 1.0.9 backend
• Supporting exporting all EVCs to YAML or JSON files
• Supporting creating/changing/deleting multiple EVCs via YAML files
• Supporting for EVC creation using VLAN ranges
• Supporting moving EVC out a specific link (or NNI)
• Supporting changing EVCs' paths
• Supporting multiple queries:
  • Get EVC using a specific UNI
  • Get EVC using a specific NNI
  • Get EVC using backup paths
• Supporting exporting monitoring data using Zabbix LLD format for integration with Zabbix
• Supporting for Kytos MEF E-Line backend
• Supporting forcing EVC reprovisioning
• Supporting multiple queries:
  • Get VLANs in use in a specific UNI
  • Get circuit utilization
  • Get circuit with under-provisioned paths
  • Get list of devices and links

Using the evc manager

The EVC Manager should run as a Python module and installed directly from pip repository. Before using the EVC Manager, make sure you have Python3 and PIP for your environment. Then, prepare the environment using the following steps:

Create a Python virtual environment:

python3 -m venv py3-evc_manager
source py3-evc_manager/bin/activate

Install git. Then, close the repo and install all requirements

pip install evc_manager

There are two options to run EVC Manager. As a script at the Shell or as a module in your application.

To run EVC Manager as a script, just run using the syntax below:

python3.6 -m evc_manager [-h] 
                         (-L | -A | -R | -D | -M MOVE_EVC) [-f SOURCE_FILE]
                         [-F DESTINATION_FILE] 
                         [--has-uni-device HAS_UNI_DEVICE]
                         [--has-uni-interface HAS_UNI_INTERFACE]
                         [--has-uni-tag-value HAS_UNI_TAG_VALUE]
                         [--has-uni-tag-values HAS_UNI_TAG_VALUES]
                         [--has-nni-name HAS_NNI_NAME]
                         [--has-nni-name-primary HAS_NNI_NAME_PRIMARY]
                         [--has-nni-name-backup HAS_NNI_NAME_BACKUP]
                         [--has-evc-name HAS_EVC_NAME]
                         [--has-partial-evc-name HAS_PARTIAL_EVC_NAME]
                         -u USER [-t TENANT]
                         [-p PASSWORD | -P] 
                         (-O OESS_URL | -K KYTOS_URL) 
                         [-V]
                         [-v {info,warning,debug}] 
                         [-q] 
                         [-y | -Y | -j | -z]
                         [-T TO_TABLE] 
                         [-s GEN_STATS_PER_NNI]

optional arguments:
  -h, --help            show this help message and exit
  -L, --list-evc        List all EVCs and output them using YAML
  -A, --add-evc         Add EVCs provided in the YAML file
  -R, --add-range-evcs  Add a range of EVCs provided in the YAML file
  -C, --change-evc      Change EVCs provided in the YAML file
  -D, --delete-evc      Delete all EVCs provided in the YAML file
  -M, --move-evc        Move one or all EVCs out the NNI provided.
  -X, --template        Create a template folder with YAML files to help.
  --move-from-nni MOVE_FROM_NNI
                        Move out of the provided NNI
  -f SOURCE_FILE, --source-file SOURCE_FILE
                        Source YAML file used by options -A, -R, -C, -D or -M
  -F DESTINATION_FILE, --destination-file DESTINATION_FILE
                        Destination YAML file used by options -L
  -p PASSWORD, --password PASSWORD
                        Provide pass for authentication
  -P, --prompt_password
                        Prompt pass for authentication
  -O OESS_URL, --oess-url OESS_URL
                        Use OESS backend. Provide OESS's URL
  -K KYTOS_URL, --kytos-url KYTOS_URL
                        Use Kytos E-Line backend's URL.
  -V, --version         show program's version number and exit
  -v {info,warning,debug}, --verbose {info,warning,debug}
                        Set Verbose Level (info|warning|debug)
  -q, --quiet           Set Quiet Mode
  -y, --to-yaml         Print using YAML.
  -Y, --to-yaml-minimal
                        Print using YAML but only the smallest set of mandatory attrs.
  -j, --to-json         Print using JSON.
  -z, --to_zabbix       Converts output to Zabbix LLD format
  -n, --to-screen       Print EVC's names to screen instead of to files
  -T TO_TABLE, --to_table TO_TABLE
                        Converts output to a table format. Use Syntax: Primary|Backup|Any:Circuit_Name
  -s GEN_STATS_PER_NNI, --gen_stats_per_nni GEN_STATS_PER_NNI
                        List number of EVCs per NNI-s Any: list all NNIs To filter use -s NNI[:JSON]
  -S SHORTCUT_FILE, --shortcut-file SHORTCUT_FILE
                        Use a provided shortcut file. Default is .evc_manager

filters:
  --has-uni-device HAS_UNI_DEVICE
                        Filter output based on the UNI's device
  --has-uni-interface HAS_UNI_INTERFACE
                        Filter output based on the UNI's interface
  --has-uni-tag-value HAS_UNI_TAG_VALUE
                        Filter output based on the UNI's tag value (VLAN ID)
  --has-uni-tag-values HAS_UNI_TAG_VALUES
                        Filter output based on the multiple UNI's tag value (VLAN id)
  --has-nni-name HAS_NNI_NAME
                        Filter output based on the NNI's name
  --has-nni-name-primary HAS_NNI_NAME_PRIMARY
                        Filter output when NNI's name is in primary path
  --has-nni-name-backup HAS_NNI_NAME_BACKUP
                        Filter output when NNI's name is in backup path
  --has-evc-name HAS_EVC_NAME
                        Filter output based on the EVC's name
  --has-partial-evc-name HAS_PARTIAL_EVC_NAME
                        Filter output based on the EVC's name or regex operation.If you're receiving an error, try putting your value in quotes ('')

authentication:
  -u USER, --user USER  Backend user for authentication
  -t TENANT, --tenant TENANT
                        Backend user group for authentication

To use EVC_Manager as a Python module, follow these steps. The INPUT is just an example and represents the input you mean to submit to the evc_manager (use option -h to discover all options):

from evc_manager import EvcManager, get_cli
INPUT = ['-u', 'admin',
     '-t', 'admin',
     '-p', 'sparc123',
     '-O', 'https://192.168.56.10/oess/',
     '-v', 'info',
     '-q',
     '-f', './add_evcs.yaml',
     '-A']
evc_mgr = EvcManager(get_cli(INPUT))
final_result = evc_mgr.run()
print(final_result)

Attention: Avoid using option --password with admin accounts. Your password might be stored in your Bash history!!

Setting up development for evc manager

EVC Manager is built to be installed through pip, but to develop through Git you need to follow the following steps:

1: Create and use venv

In a previous section it was advised that you create a virtual environment to install your dev dependencies. We accomplish this by doing:

python3 -m venv py3-evc_manager
source py3-evc_manager/bin/activate

2: Install poetry

Now that we have the virtual environment running, install poetry through pip:

pip install poetry

3: Install dependencies

Change your directory into evc_manager, where you should see poetry.lock and pyproject.toml. Here you need to install poetry's dependencies:

poetry install --with dev --no-root

Developing in evc manager

After installing poetry's dependencies, we can run any development related task with simple commands. Here are a list of necessary commands:

• poetry run tox

  • Runs ALL tests found in tox.ini.

• poetry run tox -e <TEST1,TEST2,TEST3,...>

  • This runs specific tests run specific tests.
  • Example:
    • poetry run tox -e unit-tests,integration-tests,coverage

• poetry run tox -p

  • This runs tests in parallel
  • Works with -e

• poetry install

  • Installs all the dependencies listed in pyproject.toml and poetry.lock

• poetry install --without <group>

  • When installing it excludes the groups you specify, such as dev.

• poetry install --with <group>

  • When installing it includes the groups you specify, such as dev.

• poetry install --no-root

  • When installing it excludes downloading the package itself

Here is the rest of the commands, but it is unlikely that these commands would be used.

• poetry add <package>

  • Adds a package (such as coverage, pytest, ...) to pyproject.toml and poetry.lock

• poetry update

  • Updates the project dependencies to their latest compatible versions

• poetry lock

  • Updates the lock file if pyproject.toml changes

EVC data modeling

To help modeling EVCs, the following data model was created:

version: 1.0
name: Circuit Name
unis: List of User-to-Network Interfaces
  - device: network device's name
    interface_name: network device's interface_name
    interface_description: network device's interface_description
    mac_addresses: list of MAC addresses connected to the network interface
      -
    tag: interface TAG type
      type: Type could be MPLS or VLAN
      value: VLAN ID or MPLS tag or [start, end] for VLAN ranges.
metrics: Circuit required metrics
  min_bw: minimum bandwidth
  max_delay: maximum delay acceptable in milliseconds
  max_hops: max number of hops
  avoid_shared: if circuit should avoid shared links
provisioning_time: when the circuit should be created
decommissioning_time: when the circuit should be terminated
requested_paths: list of paths, in a priority list. 'Any' if no physical path is required.
tenant: group name
priority: circuit priority
external_id: any external ID if needed
monitoring: monitoring requirements
  dataplane:
    trace: if data plane path tracing is required
      active: True or False
      interval: interval between tests
  controlplane:
    trace: if control plane path tracing is enough
      active: True or False
      interval: interval between tests
notification: notification requirements
  slack_channel:
    - workgroup1
      channel1
    - workgroup2
      channel2
  emails:
    - user1@email
    - user2@email
current_config: Current configuration
  backend: backend or technology being used
  current_path: # list of links being used
  is_backup: is it using a backup path?
  is_optimized: is it using under-provisioned links? (not enough BW, delay higher that required, etc.)
  to_provisioned:
  is_expired:
  is_up:
  is_active: True if between provisioning time and decommissioning time

Data models are provided on folder libs.models.

Release History

1.3.14 - 09-04-2024

• Added testing and linting for Python 3.12, 3.11, 3.10, and 3.9
• Fixed deprecated methods producing errors on Python 3.12

1.3.13 - 08-29-2024

• Added unit tests
• Fixed a bug where the paths attribute was incorrectly displaying for some EVCs