Bumping to 0.5.0 (#45)

* Fixing nr.types dependency issue for mkdocs * Extend templates endpoint (#42) * Adding more templates functionality * Fixing some black formatting * Add compute endpoint (#43) * Adding compute endpoint get methods * Adding some documentation around it * Added the extended templates info on the changelog * Adding snapshots funcionality (#44) * Adding snapshots funcionality * Fixing pydoc-markdown dependancy * Bumping project to 0.5.0
davidban77 · Sep 29, 2019 · d0c1125 · d0c1125
1 parent e52e907
commit d0c1125
Show file tree

Hide file tree

Showing 14 changed files with 937 additions and 14 deletions.
diff --git a/README.md b/README.md
@@ -16,6 +16,9 @@ Here are some examples where gns3fy is used in a programmatic way:
 
 - [Ansible-collection-gns3](https://galaxy.ansible.com/davidban77/gns3): Useful for CI/CD pipelines to interact with GNS3 server using Ansible. It can create/delete projects, nodes and links in an ansible playbook.
 - Terraform: Soming soon... (although it might be a Go version of it)
+- [Migrate templates between GNS3 servers](https://davidban77.github.io/gns3fy/user-guide/#migrate-templates-between-gns3-servers)
+- [Check server usage](https://davidban77.github.io/gns3fy/user-guide/#check-server-cpu-and-memory-usage) before turning up resource-hungry nodes
+- [Manipulate project snapshots](https://davidban77.github.io/gns3fy/user-guide/#create-and-list-project-snapshots) like create, delete or list the snapshots configured for the project.
 
 ## Install
 

diff --git a/docs/content/about/changelog.md b/docs/content/about/changelog.md
@@ -6,6 +6,22 @@ pip install -U gns3fy
 
 # Releases
 
+## 0.5.0
+
+**New features:**
+
+- Extended templates functionality with `create_template`, `update_template` and `delete_template`. Which can be used for migrating templates between GNS3 servers
+
+- Added compute endpoint get method from the REST API. [Compute endpoint](http://api.gns3.net/en/2.2/api/v2/controller/compute.html)
+    - `get_computes`: Retrieves attributes and characteristics of the GNS3 server compute that will run the emulations.
+    - `get_compute_images`: Lists images configured for a specific emulator on a compute.
+    - `get_compute_ports`: Lists configured and used console ports and UDP ports on a compute.
+
+- Added projects snapshots attribute and methods. [Snapshots endpoint](http://api.gns3.net/en/2.2/api/v2/controller/snapshot.html)
+    - `snapshots`: Attribute that stores snapshots names, IDs and created times of a project. Updated by the `get_snapshots` method.
+    - `get_snapshot`: Retrieves an specific snapshot information.
+    - `create_snapshot` and `delete_snapshot`: Creates/Delete an specific snapshot
+
 ## 0.4.1
 
 **Fix:**

diff --git a/docs/content/api_reference.md b/docs/content/api_reference.md
@@ -128,6 +128,50 @@ Retrieves a template from either a name or ID
 
 - `name` or `template_id`
 
+### `Gns3Connector.update_template()`
+
+```python
+def update_template(self, name=None, template_id=None, kwargs)
+```
+
+Updates a template by giving its name or UUID. For more information [API INFO]
+(http://api.gns3.net/en/2.2/api/v2/controller/template/
+templatestemplateid.html#put-v2-templates-template-id)
+
+**Required Attributes:**
+
+- `name` or `template_id`
+
+### `Gns3Connector.create_template()`
+
+```python
+def create_template(self, kwargs)
+```
+
+Creates a template by giving its attributes. For more information [API INFO]
+(http://api.gns3.net/en/2.2/api/v2/controller/template/
+templates.html#post-v2-templates)
+
+**Required Attributes:**
+
+- `name`
+- `compute_id` by default is 'local'
+- `template_type`
+
+### `Gns3Connector.delete_template()`
+
+```python
+def delete_template(self, name=None, template_id=None)
+```
+
+Deletes a template by giving its attributes. For more information [API INFO]
+(http://api.gns3.net/en/2.2/api/v2/controller/template/
+templatestemplateid.html#id16)
+
+**Required Attributes:**
+
+- `name` or `template_id`
+
 ### `Gns3Connector.get_nodes()`
 
 ```python
@@ -206,6 +250,64 @@ Deletes a project from server.
 
 - `project_id`
 
+### `Gns3Connector.get_computes()`
+
+```python
+def get_computes(self)
+```
+
+Returns a list of computes.
+
+**Returns:**
+
+List of dictionaries of the computes attributes like cpu/memory usage
+
+### `Gns3Connector.get_compute()`
+
+```python
+def get_compute(self, compute_id="local")
+```
+
+Returns a compute.
+
+**Returns:**
+
+Dictionary of the compute attributes like cpu/memory usage
+
+### `Gns3Connector.get_compute_images()`
+
+```python
+def get_compute_images(self, emulator, compute_id="local")
+```
+
+Returns a list of images available for a compute.
+
+**Required Attributes:**
+
+- `emulator`: the likes of 'qemu', 'iou', 'docker' ...
+- `compute_id` By default is 'local'
+
+**Returns:**
+
+List of dictionaries with images available for the compute for the specified
+emulator
+
+### `Gns3Connector.get_compute_ports()`
+
+```python
+def get_compute_ports(self, compute_id="local")
+```
+
+Returns ports used and configured by a compute.
+
+**Required Attributes:**
+
+- `compute_id` By default is 'local'
+
+**Returns:**
+
+Dictionary of `console_ports` used and range, as well as the `udp_ports`
+
 ## `Link` Objects
 
 GNS3 Link API object. For more information visit: [Links Endpoint API information](
@@ -868,6 +970,8 @@ Returns the Node object by searching for the `name` or the `node_id`.
 
 - `project_id`
 - `connector`
+
+**Required keyword arguments:**
 - `name` or `node_id`
 
 **NOTE:** Run method `get_nodes()` manually to refresh list of nodes if
@@ -931,3 +1035,66 @@ port)
 - `port_b`: Port name of the B side (must match the `name` attribute of the
 port)
 
+### `Project.get_snapshots()`
+
+```python
+def get_snapshots(self)
+```
+
+Retrieves list of snapshots of the project
+
+**Required Project instance attributes:**
+
+- `project_id`
+- `connector`
+
+### `Project.get_snapshot()`
+
+```python
+def get_snapshot(self, name=None, snapshot_id=None)
+```
+
+Returns the Snapshot by searching for the `name` or the `snapshot_id`.
+
+**Required Attributes:**
+
+- `project_id`
+- `connector`
+
+**Required keyword arguments:**
+- `name` or `snapshot_id`
+
+### `Project.create_snapshot()`
+
+```python
+def create_snapshot(self, name)
+```
+
+Creates a snapshot of the project
+
+**Required Project instance attributes:**
+
+- `project_id`
+- `connector`
+
+**Required keyword aguments:**
+
+- `name`
+
+### `Project.delete_snapshot()`
+
+```python
+def delete_snapshot(self, snapshot_id)
+```
+
+Deletes a snapshot of the project
+
+**Required Project instance attributes:**
+
+- `project_id`
+- `connector`
+
+**Required keyword aguments:**
+
+- `snapshot_id`
+
diff --git a/docs/content/index.md b/docs/content/index.md
@@ -9,6 +9,9 @@ Its main objective is to interact with the GNS3 server in a programatic way, so
 Here are some examples where gns3fy is used in a programmatic way:
 
 - [Ansible-collection-gns3](https://galaxy.ansible.com/davidban77/gns3): Useful for CI/CD pipelines to interact with GNS3 server using Ansible. It can create/delete projects, nodes and links in an ansible playbook.
+- [Migrate templates between GNS3 servers](user-guide.md#migrate-templates-between-gns3-servers)
+- [Check server usage](user-guide.md#check-server-cpu-and-memory-usage) before turning up resource-hungry nodes
+- [Manipulate project snapshots](user-guide.md#create-and-list-project-snapshots) like create, delete or list the snapshots configured for the project.
 
 ## Install
 

diff --git a/docs/content/user-guide.md b/docs/content/user-guide.md
@@ -525,3 +525,146 @@ Frame Relay switch  dd0f6f3a-ba58-3249-81cb-a1dd88407a47  frame_relay_switch  Tr
 ATM switch          aaa764e2-b383-300f-8a0e-3493bbfdb7d2  atm_switch          True       N/A        switch
 """
 ```
+
+### Migrate templates between GNS3 servers
+
+You may need to backup your current templates configuration of one server to another, or just want to standardize the templates used across your GNS3 server.
+
+Here is a simple script that shows an example of how to achive it with `Gns3Connector`.
+
+`migrate_gns3_templates.py`
+
+```python
+from gns3fy import Gns3Connector
+
+OLD_URL = "http://gns3server01:3080"
+NEW_URL = "http://gns3server02:3080"
+
+def main()
+    # Define the server objects
+    old_server = Gns3Connector(url=OLD_URL)
+    new_server = Gns3Connector(url=NEW_URL)
+
+    # Retrive their current templates
+    old_server_templates = old_server.get_templates()
+    new_server_templates = new_server.get_templates()
+
+    # Now pass the templates
+    for template in old_server_templates:
+        # Bypass templates already configured on new server
+        if any(template["name"] == x["name"] for x in new_server_templates):
+            print(f"Template: {template['name']} already present. Skipping...")
+            continue
+
+        # Pass template
+        new_server.create_template(**template)
+        print(f"Template: {template['name']} passed!")
+
+if __name__ == '__main__':
+    main()
+```
+
+It can produce an output similar to this:
+
+`python migrate_gns3_templates.py`
+
+```
+Template: vEOS-4.21.5F passed!
+Template: Junos vMX passed!
+Template: alpine passed!
+Template: Cloud already present. Skipping...
+Template: NAT already present. Skipping...
+Template: VPCS already present. Skipping...
+Template: Ethernet switch already present. Skipping...
+Template: Ethernet hub already present. Skipping...
+Template: Frame Relay switch already present. Skipping...
+Template: ATM switch already present. Skipping...
+Template: netautomator passed!
+Template: Cisco IOSv 15.7(3)M3 passed!
+Template: Cisco IOSvL2 15.2.1 passed!
+Template: Cisco IOSvL2 15.2(20170321:233949) passed!
+Template: Cisco IOS XRv 9000 6.5.1 passed!
+Template: Cisco IOS XRv 6.1.3 passed!
+Template: Cisco NX-OSv 7.3.0 passed!
+Template: Cisco ASAv 9.9.2 passed!
+Template: Cisco CSR1000v 16.9.4 passed!
+Template: Cumulus VX 3.7.8 passed!
+Template: Cisco NX-OSv 9000 7.0.3.I7.4 passed!
+Template: Arista vEOS 4.21.5F passed!
+```
+
+### Check server CPU and Memory usage
+
+You can use the `get_compute` method to retrieve information about the GNS3 server that is running the emulations.
+
+Here is an example of getting the CPU and Memory average usage for a period of time and use that information to determine if a hungre service router can be turned on.
+
+```python
+import time
+from gns3fy import Gns3Connector, Project
+
+server = Gns3Connector(url="http://gns3server")
+
+lab = Project(name="test_lab", connector=server)
+
+lab.get()
+
+hungry_router = lab.get_node(name="hungry_router")
+
+# Get the CPU and Memory usage and calculate its average
+cpu_usage = []
+memory_usage = []
+for index in range(5):
+    compute_attrs = server.get_compute(compute_id="local")
+    cpu_usage.append(compute_attrs.get("cpu_usage_percent"))
+    memory_usage.append(compute_attrs.get("memory_usage_percent"))
+    time.sleep(1)
+
+cpu_avg = round(sum(cpu_usage) / len(cpu_usage), 2)
+mem_avg = round(sum(memory_usage) / len(memory_usage), 2)
+
+# If CPU is less than 40% and Memory is less than 50% turnup the nodes
+if cpu_avg <= 40.0 and mem_avg <= 50.0:
+    hungry_router.start()
+    print("All good! starting hungry router")
+else:
+    print(
+        f"Hungry router does not have enough resources. CPU avg: {cpu_avg}%"
+        f" Memory avg: {mem_avg}%"
+    )
+```
+
+### Create and list project snapshots
+
+There is an attribute called `snapshots` under the `Project` instance, which stores snapshots information about that project.
+
+You can create, delete and also search for specific snapshots of a project. See the [API reference](api_reference.md#projectget_snapshots)
+
+Here is a snippet that creates and shows information about the snapshots configured on a project.
+
+```python
+from datetime import datetime
+from gns3fy import Gns3Connector, Project
+
+lab = Project(name="test3", connector=Gns3Connector(url="http://gns3server01:3080"))
+
+lab.get()
+
+# Create snapshot
+lab.create_snapshot(name="snap3")
+
+# Show configured snapshots
+for snapshot in lab.snapshots:
+    _time = datetime.utcfromtimestamp(snapshot['created_at']).strftime('%Y-%m-%d %H:%M:%S')
+    print(f"Snapshot: {snapshot['name']}, created at: {_time}")
+```
+
+It prints something similar to this:
+
+```
+Created snapshot: snap3
+
+Snapshot: snap1, created at: 2019-09-28 20:59:50
+Snapshot: snap2, created at: 2019-09-28 20:59:54
+Snapshot: snap3, created at: 2019-09-29 08:44:28
+```