Skip to content

Introduction

Ansible modules can be used to provision and configure the DVN network in an idempotent fashion.

Installation

Our Ansible tools come as a set of Ansible modules combined with another Python module that serves as a REST API wrapper. Together, these tools combine to form 1 all-inclusive Python package called "dispersive-tools".

Soon, dispersive-tools will be available directly from the public PyPI repo. In the interim, we will provide a Python wheel package.

For 4.4.0, this is the command to install our tools (assuming you have already downloaded the file and you are running the command from the same directory):

pip install ./dispersive_tools-4.4.0-py2.py3-none-any.whl

To verify a successful install, run pip list and verify that you see dispersive-tools in the output.

As a dependency, the package will ensure that Ansible v4.0.0 or higher is installed via PIP on the host system. It is highly recommended to install Ansible via pip. If you choose not to install Ansible via pip (pip install ansible), contact a member of Dispersive support for guidance to ensure that the Ansible configuration can be adjusted to work properly.

Python Version

Our Ansible modules have been tested on Python 2.7.X and Python 3. That being said, if this is a fresh system install, it is highly recommended to install Python version 3 since version 2 has officially been end-of-lifed and will no longer received updates and supports. You can still run our Ansible modules, but you will see warning output about the deprecated status of the outdated tools.

Usage and Examples

It is common practice with Ansible playbooks to have a playbook file and a variable file (usually called vars) that will organize and store the provisioning scripts.

You can run the playbook with the vars file like this:

ansible-playbook example.yml -e @vars

For example, the vars file might look something like this:

rest_host: https://192.168.2.10:3001
rest_user: admin
rest_pass: admin

vtcs:
- callp1
- df1
- df2
- df3
deflects:
- df1
- df2
- df3

Obviously, you can update the 3 REST API variables to reflect the configuration of your actual system (pointing to service-prov with the appropriate admin credentials).

The playbook might look somethin like this:

- name: create a bunch of DVN objects via REST
  connection: local
  hosts: localhost
  gather_facts: false
  environment:
    DVNREST_URL: "{{rest_host}}"
    DVNREST_USER: "{{rest_user}}"
    DVNREST_PASSWORD: "{{rest_pass}}"
    VALIDATE_CERTS: false
  tasks:
    - name: create a new service group
      dvn_servicegroup:
        tag_id: ansible

    - name: create a few VTCs
      dvn_vtc:
        vtc_id: "{{item}}"
      with_items: "{{vtcs}}"

    - name: create a session controller
      dvn_sessioncontroller:
        callp_id: callp1
        callp_port: 6000
        vtc_id: callp1

    - name: create a deflect pool and add to service group
       dvn_deflectpool:
        pool_id: AnsiblePool
        service_groups: ["ansible"]

    - name: create some data deflects
      dvn_datadeflect:
        deflect_id: "{{item}}"
        deflect_port: 5000
        vtc_id: "{{item}}"
        deflect_pools: ["AnsiblePool"]
      with_items: "{{deflects}}"

    - name: create a client VTC and add it to a service group
      dvn_vtc:
        vtc_id: client
        service_groups: [ansible]

This playbook will do the following:

  • Ensure the system has a service group called "ansible"
  • Create 4 vtcs (using the vtcs variable defined in the vars file)
  • Create a session controller
  • Create a deflect pool
  • Create 3 data deflects (again, using the variables from the vars file)
  • Create a client VTC and add that VTC to the service group we added earlier

Configuration Variables

Our Ansible modules have a handful of configuration variables that are common to each of the modules. While these variables can be passed to or defined on each module in the playbook, it would become redundant very quickly. It is recommended to define these variables in a common location: the environment block of the playbook (see the example above). The following are all of the common configuration variables:

Variable Name Description Example
DVNREST_URL the full url (host + port) of service-prov https://192.168.1.10:3004
DVNREST_USER admin username for service-prov admin_user
DVNREST_PASSWORD password for the DVNREST_USER $ecureP@$$word
VALIDATE_CERTS if set to true (the default), then the ansible modules will only connect to service-prov in the presence of fully valid TLS certs. In a development or staging environment, it may be desireable to set this value to false false