From 6b23e9a639921ed017f27bdeb904d5ddfa0bb73b Mon Sep 17 00:00:00 2001 From: ttafsir Date: Fri, 6 May 2022 23:11:28 -0400 Subject: [PATCH] 0.2.7-branch (#164) * updating black due to incompatibility with Click (#144) * Security upgrade mkdocs from 1.2.3 to 1.3.0 (#146) * update README with links to docs (#148) * Fixes KeyError due to unavailable options for dynamips (#151) * Fixes lab deletion with empty nodes (#153) * Clean up broken tests * move shared fixtures * fix failing tests * Adds pytest config * Fix tracebacks in CLI output * clean up tracebacks for lab commands * clean up tracebacks for node commands * clean up tracebacks for system commands * clean up tracebacks for user commands * Adds tempate for topo builder test * fix linting errors * clean up old files * Adds mkdoc docs * Adds docs directory * Bumped version number to 0.2.7 --- .gitignore | 1 - docs/api_reference.md | 9 +++ docs/cli_reference.md | 37 +++++++++++ docs/index.md | 90 ++++++++++++++++++++++++++ docs/requirements.in | 2 + docs/topology_builder.md | 122 ++++++++++++++++++++++++++++++++++++ src/evengsdk/cli/version.py | 2 +- 7 files changed, 261 insertions(+), 2 deletions(-) create mode 100644 docs/api_reference.md create mode 100644 docs/cli_reference.md create mode 100644 docs/index.md create mode 100644 docs/requirements.in create mode 100644 docs/topology_builder.md diff --git a/.gitignore b/.gitignore index e267ec8..0c44c64 100644 --- a/.gitignore +++ b/.gitignore @@ -133,4 +133,3 @@ dmypy.json .vscode *.old .eve-ng/ -docs diff --git a/docs/api_reference.md b/docs/api_reference.md new file mode 100644 index 0000000..f0b21aa --- /dev/null +++ b/docs/api_reference.md @@ -0,0 +1,9 @@ +# Evengsdk + +::: evengsdk.client + selection: + docstring_style: restructured-text + +::: evengsdk.api + selection: + docstring_style: restructured-text diff --git a/docs/cli_reference.md b/docs/cli_reference.md new file mode 100644 index 0000000..99949f8 --- /dev/null +++ b/docs/cli_reference.md @@ -0,0 +1,37 @@ +# CLI Reference + +This page provides documentation for our command line tools. + +## :gear: Configuration + +It is simple enough to pass the proper flags to `eve-ng` specify details for your EVE-NG host. However, you may also pass the connection details as environment variables. You can set the following `evengsdk` environment variables: + +* `EVE_NG_HOST ` - EVE-NG host name or IP address +* `EVE_NG_USERNAME` - EVE-NG username +* `EVE_NG_PASSWORD` - EVE-NG API/GUI password +* `EVE_NG_PORT` - EVE-NG API port. Default `80` +* `EVE_NG_PROTOCOL` - EVE-NG API protocol. Default `http` +* `EVE_NG_SSL_VERIFY` - Verify SSL. Default `False` +* `EVE_NG_INSECURE` - Suppress insecure warnings. Default `False` +* `EVE_NG_LAB_PATH` - EVE-NG default lab path. Ex. `/myLab.unl` + +You may set the variables and export them to your shell environment. You can also define your environment variables in a `.env` folder that will automatically be sourced. The example. below shows the contents of a `.env` file that will permit you to both source the file and automatically load the variables as needed. + +```txt +export EVE_NG_HOST=192.168.2.100 +export EVE_NG_USERNAME=admin +export EVE_NG_PASSWORD=eve +export EVE_NG_PORT=80 +export EVE_NG_PROTOCOL=http +export EVE_NG_SSL_VERIFY=False +export EVE_NG_INSECURE=True +export EVE_NG_LAB_PATH='/mylab.unl' +``` + +## :keyboard: Commands + +::: mkdocs-click + :module: evengsdk.cli.cli + :command: main + :prog_name: eve-ng + :depth: 1 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..bd54ed2 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,90 @@ +# Introduction + +`Evengsdk` is a Python library with command-line utilities to manage EVE-NG servers and network topologies. + +`Evengsdk` provides the flexibility to your EVE-NG hosts and topologies in different ways: + +* **evengsdk**: The `evengsdk` library provides a set of classes to manage EVE-NG servers and network topologies. +* **eve-ng CLI**: The eve-ng command-line utility provides a set of commands to manage EVE-NG servers and network topologies without the need to write Python code. +* **Topology Builder**: The topology builder lets you build a topology from a YAML declaration file. + +## Requirements + +Evengsdk works with both the community and PRO versions of EVE-NG. You will need a working instance of EVE-NG to use Evengsdk. + +Evengsdk requires Python 3.8 or later. + +## Installation + +You can install Evengsdk from PyPI with pip: + +```sh +pip install eve-ng +``` + +## Quick Start + +### Basic Usage + +You can interact with the EVE-NG API through the `client.api` interface + +```python +from evengsdk.client import EvengClient +from pprint import pprint + +client = EvengClient("10.246.32.254", log_file="test.log") +client.login(username="admin", password="eve") + +resp = client.api.list_node_templates() +``` + +### Build a Topology + +```python +from evengsdk.client import EvengClient + + +client = EvengClient("10.246.32.254", log_file="test.log", ssl_verify=False, protocol="https") +client.disable_insecure_warnings() # disable warnings for self-signed certificates +client.login(username="admin", password="eve") +client.set_log_level("DEBUG") + +# create a lab +lab = {"name": "test_lab", "description": "Test Lab", "path": "/"} +resp = client.api.create_lab(**lab) +if resp['status'] == "success": + print("lab created successfully.") + +# we need the lab path to create objects in the lab +lab_path = f"{lab['path']}{lab['name']}.unl" + +# create management network +mgmt_cloud = {"name": "eve-mgmt", "network_type": "pnet1"} +client.api.add_lab_network(lab_path, **mgmt_cloud) + +# create Nodes +nodes = [ + {"name": "leaf01", "template": "veos", "image": "veos-4.22.0F", "left": 50}, + {"name": "leaf02", "template": "veos", "image": "veos-4.22.0F", "left": 200}, +] +for node in nodes: + client.api.add_node(lab_path, **node) + +# connect nodes to management network +mgmt_connections = [ + {"src": "leaf01", "src_label": "Mgmt1", "dst": "eve-mgmt"}, + {"src": "leaf02", "src_label": "Mgmt1", "dst": "eve-mgmt"} +] +for link in mgmt_connections: + client.api.connect_node_to_cloud(lab_path, **link) + +# create p2p links +p2p_links = [ + {"src": "leaf01", "src_label": "Eth1", "dst": "leaf02", "dst_label": "Eth1"}, + {"src": "leaf01", "src_label": "Eth1", "dst": "leaf02", "dst_label": "Eth2"}, +] +for link in p2p_links: + client.api.connect_node_to_node(lab_path, **link) + +client.logout() +``` diff --git a/docs/requirements.in b/docs/requirements.in new file mode 100644 index 0000000..9ba6cfa --- /dev/null +++ b/docs/requirements.in @@ -0,0 +1,2 @@ +mkdocs-click +mkdocstrings diff --git a/docs/topology_builder.md b/docs/topology_builder.md new file mode 100644 index 0000000..9a737f7 --- /dev/null +++ b/docs/topology_builder.md @@ -0,0 +1,122 @@ +# Topology Builder + +The CLI application allows you to build lab topologies using a declarative model in order to quickly spin a lab and configure nodes using configuration files or jinja templates. Below is a sample topology for a 5 node leaf/spine network. + + +```yaml +--- + name: test + description: Arista VEOS leaf-spine lab + path: "/" + nodes: + - name: leaf01 + template: veos + image: veos-4.22.0F + node_type: qemu + left: 50 + top: 135 + configuration: + file: examples/configs/test_leaf01.cfg + - name: leaf02 + template: veos + image: veos-4.22.0F + node_type: qemu + left: 200 + top: 135 + configuration: + template: base.j2 + vars: + hostname: leaf02 + management_address: 10.10.10.1 + - name: leaf03 + template: veos + image: veos-4.22.0F + node_type: qemu + left: 350 + top: 135 + configuration: + template: base.j2 + vars: examples/data/leaf03.yml + - name: leaf04 + template: veos + image: veos-4.22.0F + node_type: qemu + left: 500 + top: 135 + - name: spine01 + template: veos + image: veos-4.22.0F + node_type: qemu + left: 150 + top: 474 + - name: spine02 + template: veos + image: veos-4.22.0F + node_type: qemu + left: 350 + top: 474 + networks: + - name: vCloud + network_type: pnet1 + visibility: 1 + top: 300 + left: 475 + links: + network: + - {"src": "leaf01", "src_label": "Mgmt1", "dst": "vCloud"} + - {"src": "leaf02", "src_label": "Mgmt1", "dst": "vCloud"} + - {"src": "leaf03", "src_label": "Mgmt1", "dst": "vCloud"} + - {"src": "leaf04", "src_label": "Mgmt1", "dst": "vCloud"} + - {"src": "spine01", "src_label": "Mgmt1", "dst": "vCloud"} + - {"src": "spine02", "src_label": "Mgmt1", "dst": "vCloud"} + node: + - {"src": "leaf01", "src_label": "Eth3", "dst": "spine01", "dst_label": "Eth1"} + - {"src": "leaf02", "src_label": "Eth3", "dst": "spine01", "dst_label": "Eth2"} + - {"src": "leaf03", "src_label": "Eth3", "dst": "spine01", "dst_label": "Eth3"} + - {"src": "leaf04", "src_label": "Eth3", "dst": "spine01", "dst_label": "Eth4"} + - {"src": "leaf01", "src_label": "Eth2", "dst": "spine02", "dst_label": "Eth1"} + - {"src": "leaf02", "src_label": "Eth2", "dst": "spine02", "dst_label": "Eth2"} + - {"src": "leaf03", "src_label": "Eth2", "dst": "spine02", "dst_label": "Eth3"} + - {"src": "leaf04", "src_label": "Eth2", "dst": "spine02", "dst_label": "Eth4"} + +``` + +## Device Configurations + +The topology builder allows you to create device configurations using either static files or jinja templates. The following example shows how to create a static configuration file for a leaf node. + +Below is an example of a static configuration file for a leaf node. + +```yaml + nodes: + - name: leaf01 + template: veos + image: veos-4.22.0F + node_type: qemu + left: 50 + top: 135 + configuration: + file: examples/configs/test_leaf01.cfg +``` + +Jinja templates are also used to create device configurations. The following example shows how to create a jinja template for a leaf node. In this example, the variables in the template are defined in a yaml file. However, you can also define the variables in the template directly under the `vars` key. + +```yaml + - name: leaf03 + template: veos + image: veos-4.22.0F + node_type: qemu + left: 350 + top: 135 + configuration: + template: base.j2 + vars: examples/data/leaf03.yml +``` + +To create a topology from the example above simply run the following command + +```sh +eve-ng lab create-from-topology -t examples/test_topology.yml --template-dir examples/templates +``` + +By default, the configuration tool searches for templates in `templates` directory, but you can use `--template-dir` as shown above to specify another location. diff --git a/src/evengsdk/cli/version.py b/src/evengsdk/cli/version.py index 0ef6470..29d1336 100644 --- a/src/evengsdk/cli/version.py +++ b/src/evengsdk/cli/version.py @@ -1,2 +1,2 @@ # -*- coding: utf-8 -*- -__version__ = "0.2.6" +__version__ = "0.2.7"