Develop

README.md

@@ -1,2 +1,125 @@
-# ansible-collection-gns3
-Ansible Collection for GNS3 Server REST API using gns3fy
+# Ansible Module for GNS3
+[Ansible-Galaxy collections](https://docs.ansible.com/ansible/devel/dev_guide/collections_tech_preview.html) repository for GNS3 Server REST API using [gns3fy - see the docs](https://davidban77.github.io/gns3fy/).
+
+## Installation
+
+For the module to be used you need to have installed [gns3fy](https://github.com/davidban77/gns3fy)
+
+```
+pip install gns3fy
+```
+
+This collections is packaged under ansible-galaxy, so to install it you need [mazer from Ansible Projects](https://galaxy.ansible.com/docs/mazer/index.html):
+
+```
+mazer install davidban77.gns3
+```
+
+## Features
+
+- Open/closes projects.
+- Starts/stops all nodes inside a project, or it can be done sequentially with a delay factor.
+- Creates/Updates projects with nodes and links specified as variables in a playbook.
+- Deletes projects safely by stopping nodes, if there are any, then closing the project and finally deleting it.
+- Idempotency is present in all actions. An example could be reflected in a playbook that creates a project with nodes and links, these settings will not be executed again on a rerun (and by settings I mean projects settings, nodes and links)/
+
+
+## Modules
+
+These are the modules provided with this collection:
+
+- `gns3_version`: Retrieves GNS3 server version
+- `gns3_project`: Module to interact with GNS3 server projects
+    - It opens/closes projects and performs basic turnup/teradown operations on nodes.
+    - It*creates/updates or deletes projects, with the respective nodes and links specified
+
+## Examples
+
+Here are some examples of how to use the module.
+
+#### Get server version
+
+```yaml
+---
+- host: localhost
+  # Call the collections to use the respective modules
+  collections:
+    - davidban77.gns3
+  vars:
+    gns3_url: http://localhost
+  tasks:
+    - name: Get the server version
+    gns3_version:
+        url: "{{ gns3_url }}"
+        port: 3080
+    register: result
+
+    - debug: var=result
+```
+
+#### Manipulate GNS3 projects
+
+```yaml
+---
+# Open a GNS3 project
+- name: Start lab
+  gns3_project:
+    url: "{{ gns3_url }}"
+    state: opened
+    project_name: lab_example
+
+# Stop all nodes inside an open project
+- name: Stop nodes
+  gns3_project:
+    url: "{{ gns3_url }}"
+    state: opened
+    project_name: lab_example
+    nodes_state: stopped
+    nodes_strategy: all
+    poll_wait_time: 5
+
+# Open a GNS3 project and start nodes one by one with a delay of 10sec between them
+- name: Start nodes one by one
+  gns3_project:
+    url: "{{ gns3_url }}"
+    state: opened
+    project_name: lab_example
+    nodes_state: started
+    nodes_strategy: one_by_one
+    nodes_delay: 10
+
+# Close a GNS3 project
+- name: Stop lab
+  gns3_project:
+    url: "{{ gns3_url }}"
+    state: closed
+    project_id: "UUID-SOMETHING-1234567"
+```
+
+#### Create and delete projects
+
+```yaml
+---
+# Create a GNS3 project given nodes and links specifications
+- name: Create a project
+  gns3_project:
+    url: "{{ gns3_url }}"
+    state: present
+    project_name: new_lab
+    nodes_spec:
+        - name: alpine-1
+          node_type: docker
+          template: alpine
+        - name: alpine-2
+          node_type: docker
+          template: alpine
+    links_spec:
+        - ['alpine-1', 'eth0', 'alpine-2', 'eth1']
+
+# Delete a GNS3 project
+- name: Delete project
+  gns3_project:
+    url: "{{ gns3_url }}"
+    state: absent
+    project_name: new_lab
+```

galaxy.yml

@@ -2,7 +2,7 @@ namespace: "davidban77"
 name: "gns3"
 version: "1.0.1"
 readme: "README.md"
-description: "Module to interact with GNS3 server REST API. It is using the [gns3fy library](https://davidban77.github.io/gns3fy/)"
+description: "Module to interact with GNS3 server REST API based on gns3fy"
 authors:
     - "David Flores <[email protected]>"
 dependencies:
@@ -16,6 +16,6 @@ tags:
     - simulator
     - netops
 repository: "https://github.com/davidban77/ansible-collection-gns3"
-documentation: "https://github.com/davidban77/ansible-collection-gns3/blob/develop/README.md"
+documentation: "https://github.com/davidban77/ansible-collection-gns3/blob/master/README.md"
 homepage: "https://github.com/davidban77/ansible-collection-gns3"
 issues: "https://github.com/davidban77/ansible-collection-gns3/issues"

plugins/modules/gns3_project.py

@@ -1,30 +1,25 @@
 #!/usr/bin/env python
 
-# Copyright: (c) 2018, David Flores <[email protected]>
-# GNU General Public License v3.0+ (see COPYING or
-# https://www.gnu.org/licenses/gpl-3.0.txt)
-
 ANSIBLE_METADATA = {
-    "metadata_version": "1.1",
+    "metadata_version": "1.2",
     "status": ["preview"],
     "supported_by": "community",
 }
 
 DOCUMENTATION = """
 ---
-module: gns3
-
+module: gns3_project
 short_description: Module to interact with GNS3 server projects
-
 version_added: "2.8"
-
 description:
     - "Module to interact with GNS3 server projects. It is using the L(gns3fy library,
     https://davidban77.github.io/gns3fy/)"
     - It opens/closes projects and performs basic turnup/teradown operations on nodes.
     - It creates/updates or deletes projects, with the respective nodes and links
     specified
-
+requirements: [ gns3fy ]
+author:
+    - David Flores (@netpanda)
 options:
     url:
         description:
@@ -92,10 +87,6 @@
             'eth0', 'alpine-2', 'eth0'])"
             - "Mandatory attributes: C(node_a), C(port_a), C(node_b) and C(port_b)"
         type: list
-
-
-author:
-    - David Flores (twitter - @netpanda)
 """
 
 EXAMPLES = """
@@ -130,14 +121,14 @@
 - name: Stop lab
   gns3_project:
     url: http://localhost
-    state: stopped
+    state: closed
     project_id: "UUID-SOMETHING-1234567"
 
 # Create a GNS3 project
-- name: Create a project given an specifications file
+- name: Create a project given nodes and links specs
   gns3_project:
     url: http://localhost
-    state: create
+    state: present
     project_name: new_lab
     nodes_spec:
         - name: alpine-1
@@ -150,16 +141,44 @@
         - ('alpine-1', 'eth0', 'alpine-2', 'eth1')
 
 # Delete a GNS3 project
-- name: Test failure of the module
+- name: Delete project
   gns3_project:
     url: http://localhost
-    state: delete
+    state: absent
     project_name: new_lab
 """
 
 RETURN = """
-message:
-    description: The output message that the test module generates
+name:
+    description: Project name
+    type: str
+    returned: always
+project_id:
+    description: Project UUID
+    type: str
+    returned: always
+status:
+    description: Project status. Possible values: opened, closed
+    type: str
+    returned: always
+path:
+    description: Path of the project on the server (works only with compute=local)
+    type: str
+    returned: always
+auto_close:
+    description: Project auto close when client cut off the notifications feed
+    type: bool
+    returned: always
+auto_open:
+    description: Project open when GNS3 start
+    type: bool
+    returned: always
+auto_start:
+    description: Project start when opened
+    type: bool
+    returned: always
+filename:
+    description: Project filename
     type: str
     returned: always
 """

plugins/modules/gns3_version.py

@@ -1,26 +1,21 @@
 #!/usr/bin/env python
 
-# Copyright: (c) 2018, David Flores <[email protected]>
-# GNU General Public License v3.0+ (see COPYING or
-# https://www.gnu.org/licenses/gpl-3.0.txt)
-
 ANSIBLE_METADATA = {
-    'metadata_version': '1.1',
+    'metadata_version': '1.2',
     'status': ['preview'],
     'supported_by': 'community'
 }
 
 DOCUMENTATION = '''
 ---
-module: gns3
-
+module: gns3_version
 short_description: Retrieves GNS3 server version
-
 version_added: "2.8"
-
 description:
     - "Retrieves GNS3 server version using gns3fy"
-
+requirements: [ gns3fy ]
+author:
+    - David Flores (@netpanda)
 options:
     url:
         description:
@@ -32,15 +27,12 @@
             - TCP port to connect to server REST API
         type: int
         default: 3080
-
-author:
-    - David Flores (twitter -  @netpanda)
 '''
 
 EXAMPLES = '''
 # Retrieve the GNS3 server version
 - name: Get the server version
-  gns3:
+  gns3_version:
     url: http://localhost
     port: 3080
   register: result
@@ -49,7 +41,7 @@
 '''
 
 RETURN = '''
-local:
+local_compute:
     description: Whether this is a local server or not
     type: bool
     returned: always