Ansible Module for GNS3

Ansible-Galaxy collections repository for GNS3 Server REST API using gns3fy - see the docs.

Installation

For the module to be used you need to have installed gns3fy

pip install gns3fy

This collections is packaged under ansible-galaxy, so to install it you need mazer from Ansible Projects:

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.
Creates/Deletes/Restores snapshots of projects.
Retrieves information about available emulators on the GNS3 server compute, as well as available images, console ports, version, etc..
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. (TO BE DEPRECATED with the gns3_facts module)
gns3_facts: Retrieves the compute(s) information of a GNS3 server
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
gns3_project_file: Updates/creates a file on a project directory.
gns3_snapshot: Module that interacts with snapshots of a project on GNS3 server.
gns3_node: Module to operate a node in a GNS3 server project.
gns3_node_file: Updates/creates a file on a node directory.
gns3_nodes_inventory: Retrieves GNS3 a project nodes console information.

Examples: using the module

Here are some examples of how to use the module.

Get server version

---
- host: localhost
  # Call the collections to use the respective modules
  collections:
    - davidban77.gns3
  vars:
    gns3_url: http://localhost
  tasks:
    - name: Get the server facts
      gns3_facts:
        url: "{{ gns3_url }}"
        port: 3080
        get_images: all
        get_compute_ports: yes
      register: result

    - debug: var=result

Get nodes_inventory information from a project

---
- 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_nodes_inventory:
        url: "{{ gns3_url }}"
        project_name: lab_example
      register: result

    - debug: var=result

Manipulate GNS3 projects

---
# 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

---
# 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
          template: alpine
        - name: alpine-2
          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

Examples: using the roles

There are also some convinient roles that you can use to manage your labs. Here is an example playbook:

main.yml

- hosts: localhost
  tasks:
    - import_role:
        name: create_lab
      when: execute == "create"
    - import_role:
        name: delete_lab
      when: execute == "delete"

This way you can call and switch the behaviour of the playbook:

Create the lab

ansible-playbook main.yml -e execute=create

Or delete the lab

ansible-playbook main.yml -e execute=delete

Here is the example variable file which specifies the naming convention used. You can see that the variable names come from the module itself with only gns3_

---
gns3_url: "http://dev_gns3server"
gns3_project_name: test_ansible
gns3_nodes_spec:
    - name: veos-1
      template: "vEOS-4.21.5F"
    - name: veos-2
      template: "vEOS-4.21.5F"
    - name: ios-1
      template: "IOU-15.4"
    - name: ios-2
      template: "IOU-15.4"
gns3_nodes_strategy: one_by_one
gns3_links_spec:
    - ["veos-1", "Ethernet1", "veos-2", "Ethernet1"]
    - ["veos-1", "Ethernet2", "ios-1", "Ethernet1/0"]
    - ["veos-2", "Ethernet2", "ios-2", "Ethernet1/0"]
    - ["ios-1", "Ethernet1/2", "ios-2", "Ethernet1/2"]

More examples

For more examples like create an /etc/network/interfaces file for an alpine docker node to configure its network interfaces, or restore a project to an specific snapshot, you can go to the test/playbooks directory.

fpieters/ansible-collection-gns3