Merge pull request #119 from napalm-automation/develop

Release 0.9.0

Author: ktbyers

.gitignore

@@ -61,3 +61,5 @@ tags
 *.swp
 
 .compiled
+
+module_docs/

.travis.yml

@@ -10,15 +10,18 @@ env:
 
 install:
     - pip install pylama
-    - pip install napalm-base
+    - pip install napalm
     - pip install "ansible>=$ANSIBLE_VERSION.0,<$ANSIBLE_VERSION.99"
+    - pip install -r requirements-dev.txt
+    - pip install -e .
 
 script:
     - pylama
     - cd tests
     - ./run_tests.sh
     - ./test_changelog.sh
     - cd ..
+    - py.test
 
 deploy:
   provider: pypi

CHANGELOG.rst

@@ -1,6 +1,12 @@
 develop
 =====
 
+0.9.0
+=====
+
+    - Fix old napalm_base references
+    - Various documentation fixes
+    - Add action plugin to better support command-line arguments
 
 0.8.0
 =====

README.md

@@ -15,6 +15,16 @@ The following modules are currently available:
 - ``napalm_translate_yang``
 - ``napalm_validate``
 
+Actions
+=======
+
+Actions will only work with Ansible version 2.3 or greater.
+They provides default parameters for the hostname, username, password and timeout paramters.
+* hostname is set to the first of provider {{ hostname }}, provider {{ host }}, play-context remote_addr.
+* username is set to the first of provider {{ username }}, play-context connection_user.
+* password is set to the first of provider {{ password }}, play-context password (-k argument).
+* timeout is set to the provider {{ timeout }}, or else defaults to 60 seconds (can't be passed via command-line).
+
 Install
 =======
 
@@ -32,20 +42,27 @@ Once you have installed ``napalm-ansible`` run the command ``napalm-ansible`` an
 ```
 $ napalm-ansible
 To make sure ansible can make use of the napalm modules you will have
-to add the following configurtion to your ansible configureation
+to add the following configuration to your ansible configuration
 file, i.e. `./ansible.cfg`:
 
     [defaults]
     library = /Users/dbarroso/workspace/napalm/napalm-ansible/napalm_ansible
+    action_plugins = /Users/dbarroso/workspace/napalm/napalm-ansible/action_plugins
 
 For more details on ansible's configuration file visit:
 https://docs.ansible.com/ansible/latest/intro_configuration.html
 ```
 
+Dependencies
+=======
+* [napalm](https://github.com/napalm-automation/napalm) 2.3.0 or later
+* [ansible](https://github.com/ansible/ansible) 2.2.0.0 or later
+
+
 Examples
 =======
 
-Example to retreive facts from a device
+Example to retrieve facts from a device
 ```
  - name: get facts from device
    napalm_get_facts:
@@ -87,3 +104,11 @@ Example to get compliance report
     dev_os: "{{ dev_os }}"
     validation_file: validate.yml
 ```
+
+Example to use default connection paramters:
+```
+ - name: get facts from device
+   napalm_get_facts:
+     dev_os: "{{ os }}"
+     filter: facts,interfaces,bgp_neighbors
+```

library

@@ -1 +1 @@
-napalm_ansible
+napalm_ansible/modules

napalm_ansible/__init__.py

@@ -1,12 +1,15 @@
 import os
+import ansible
+from distutils.version import LooseVersion
 
 message = """
-To make sure ansible can make use of the napalm modules you will have
-to add the following configurtion to your ansible configureation
-file, i.e. `./ansible.cfg`:
+To ensure Ansible can use the NAPALM modules you will have
+to add the following configurtion to your Ansible configuration
+file (ansible.cfg):
 
     [defaults]
-    library = {path}
+    library = {path}/modules
+    {action_plugins}
 
 For more details on ansible's configuration file visit:
 https://docs.ansible.com/ansible/latest/intro_configuration.html
@@ -15,4 +18,9 @@
 
 def main():
     path = os.path.dirname(__file__)
-    print(message.format(path=path).strip())
+    if LooseVersion(ansible.__version__) < LooseVersion('2.3.0.0'):
+        action_plugins = ""
+    else:
+        action_plugins = "action_plugins = {path}/plugins/action".format(path=path)
+
+    print(message.format(path=path, action_plugins=action_plugins).strip())

napalm_ansible/modules/__init__.py

@@ -12,19 +12,50 @@
 requirements:
     - napalm
 options:
-   args:
+    hostname:
+        description:
+          - IP or FQDN of the device you want to connect to
+        required: False
+    username:
+        description:
+          - Username
+        required: False
+    password:
+        description:
+          - Password
+        required: False
+    args:
         description:
           - Keyword arguments to pass to the `cli` method
         required: True
+    dev_os:
+        description:
+          - OS of the device
+        required: False
+        choices: ['eos', 'junos', 'iosxr', 'fortios', 'ios', 'mock', 'nxos', 'nxos_ssh', 'panos',
+        'vyos']
+    provider:
+        description:
+          - Dictionary which acts as a collection of arguments used to define the characteristics
+            of how to connect to the device.
+            Note - hostname, username, password and dev_os must be defined in either provider
+            or local param
+            Note - local param takes precedence, e.g. hostname is preferred to provider['hostname']
+        required: False
+
 '''
 
 EXAMPLES = '''
-vars:
-  napalm_provider:
+- napalm_cli:
     hostname: "{{ inventory_hostname }}"
     username: "napalm"
     password: "napalm"
     dev_os: "eos"
+    args:
+        commands:
+            - show version
+            - show snmp chassis
+
 - napalm_cli:
     provider: "{{ napalm_provider }}"
     args:
@@ -43,11 +74,10 @@
     description: string of command output
     returned: always
     type: dict
-    sample:
-    {
+    sample: '{
         "show snmp chassis": "Chassis: 1234\n",
         "show version": "Arista vEOS\nHardware version:    \nSerial number:       \nSystem MAC address:  0800.27c3.5f28\n\nSoftware image version: 4.17.5M\nArchitecture:           i386\nInternal build version: 4.17.5M-4414219.4175M\nInternal build ID:      d02143c6-e42b-4fc3-99b6-97063bddb6b8\n\nUptime:                 1 hour and 21 minutes\nTotal memory:           1893416 kB\nFree memory:            956488 kB\n\n"  # noqa
-    }
+    }'
 '''
 
 napalm_found = False
@@ -111,8 +141,7 @@ def main():
     timeout = module.params['timeout']
     args = module.params['args']
 
-    argument_check = {'hostname': hostname, 'username': username,
-                      'dev_os': dev_os, 'password': password}
+    argument_check = {'hostname': hostname, 'username': username, 'dev_os': dev_os}
     for key, val in argument_check.items():
         if val is None:
             module.fail_json(msg=str(key) + " is required")

napalm_ansible/napalm_cli.py renamed to napalm_ansible/modules/napalm_cli.py

@@ -54,20 +54,20 @@
 '''
 
 EXAMPLES = '''
-      napalm_diff_yang:
-        first: "{{ candidate.yang_model }}"
-        second: "{{ running_config.yang_model }}"
-        models:
-            - models.openconfig_interfaces
-      register: diff
+- napalm_diff_yang:
+    first: "{{ candidate.yang_model }}"
+    second: "{{ running_config.yang_model }}"
+    models:
+     - models.openconfig_interfaces
+  register: diff
 '''
 
 RETURN = '''
 diff:
     description: "Same output as the method napalm_yang.utils.diff"
     returned: always
     type: dict
-    sample: {
+    sample: '{
             "interfaces": {
                 "interface": {
                     "both": {
@@ -81,7 +81,7 @@
                         }
                     }
                 }
-            }
+            }'
 '''
 
 

napalm_ansible/napalm_diff_yang.py renamed to napalm_ansible/modules/napalm_diff_yang.py

@@ -68,54 +68,47 @@
         default: None
     ignore_notimplemented:
         description:
-          - Ignores NotImplementedError for filters which aren't supported by the driver. Returns
-            invalid filters in a list called: not_implemented
+          - "Ignores NotImplementedError for filters which aren't supported by the driver. Returns
+            invalid filters in a list called: not_implemented"
         required: False
         default: False
         choices: [True, False]
     filter:
         description:
-            - A list of facts to retreive from a device and provided though C(ansible_facts)
+            - "A list of facts to retreive from a device and provided though C(ansible_facts)
               The list of facts available are maintained at:
                   http://napalm.readthedocs.io/en/latest/support/
-              Note- not all getters are implemented on all supported device types
+              Note- not all getters are implemented on all supported device types"
         required: False
         default: ['facts']
     args:
         description:
             - dictionary of kwargs arguments to pass to the filter. The outer key is the name of
               the getter (same as the filter)
-        requited: False
+        required: False
         default: None
 '''
 
 EXAMPLES = '''
-
-vars:
-  ios_provider:
-    hostname: "{{ inventory_hostname }}"
-    username: "napalm"
-    password: "napalm"
-    dev_os: "ios"
-
- - name: get facts from device
-   napalm_get_facts:
-     hostname={{ inventory_hostname }}
-     username={{ user }}
-     dev_os={{ os }}
-     password={{ passwd }}
-     filter=['facts']
-   register: result
-
- - name: print data
-   debug: var=result
-
- - name: Getters
-   napalm_get_facts:
-     provider: "{{ ios_provider }}"
-     filter:
-       - "lldp_neighbors_detail"
-       - "interfaces"
+- name: get facts from device
+  napalm_get_facts:
+    hostname: '{{ inventory_hostname }}'
+    username: '{{ user }}'
+    dev_os: '{{ os }}'
+    password: '{{ passwd }}'
+    filter: ['facts']
+  register: result
+
+- name: print data
+  debug:
+    var: result
+
+- name: Getters
+  napalm_get_facts:
+    provider: "{{ ios_provider }}"
+    filter:
+      - "lldp_neighbors_detail"
+      - "interfaces"
 
 - name: get facts from device
   napalm_get_facts:
@@ -212,8 +205,7 @@ def main():
     ignore_notimplemented = module.params['ignore_notimplemented']
     implementation_errors = []
 
-    argument_check = {'hostname': hostname, 'username': username,
-                      'dev_os': dev_os, 'password': password}
+    argument_check = {'hostname': hostname, 'username': username, 'dev_os': dev_os}
     for key, val in argument_check.items():
         if val is None:
             module.fail_json(msg=str(key) + " is required")