add a10_server_axapi3 module (#3239)

* add a10_server_axapi3 module

* added return documentation

* modified a10_server_axapi3.py per feedback

* fixed line 60 s/action/operation/

* modified a10_server_axapi3.py per feedback

* modified a10_server_axapi3.py per feedback

* corrected YAML format error in documentation

* removed slp_server_ip and slp_server check in code since the arguments are labeled as required, per feedback

* 	modified:   a10_server.py
	modified:   a10_service_group.py
	modified:   a10_virtual_server.py

Changed main() block, restricted import to only functions used.

* removed space for main() to be last line

* removed invalid lines

* Modified Documentations for a10_server.py, a10_service_group.py, a10_virtual_server.py

* Take out alias:[] and choices:[] in Documentation from a10_service_group.py and a10_virtual_server.py since they are now the default

* deleted a10_server.py, a10_service_group.py, a10_virtual_server.py

* deleted 'version_last_modified' line in Documentation across a10_server.py, a10_service_group.py and a10_virtual_server.py as they were added in error, change validate_certs version_added in a10_server.py

* added newline after main()

* added newline after main() for a10_server_axapi3.py

lib/ansible/modules/extras/network/a10/a10_server.py

@@ -3,7 +3,8 @@
 
 """
 Ansible module to manage A10 Networks slb server objects
-(c) 2014, Mischa Peters <mpeters@a10networks.com>
+(c) 2014, Mischa Peters <mpeters@a10networks.com>,
+2016, Eric Chou <ericc@a10networks.com>
 
 This file is part of Ansible
 
@@ -25,26 +26,28 @@ DOCUMENTATION = '''
 ---
 module: a10_server
 version_added: 1.8
-short_description: Manage A10 Networks AX/SoftAX/Thunder/vThunder devices
+short_description: Manage A10 Networks AX/SoftAX/Thunder/vThunder devices' server object.
 description:
-    - Manage slb server objects on A10 Networks devices via aXAPI
+    - Manage SLB (Server Load Balancer) server objects on A10 Networks devices via aXAPIv2.
-author: "Mischa Peters (@mischapeters)"
+author: "Eric Chou (@ericchou) 2016, Mischa Peters (@mischapeters) 2014"
+notes:
+    - Requires A10 Networks aXAPI 2.1.
 extends_documentation_fragment: a10
 options:
   server_name:
     description:
-      - SLB server name.
+      - The SLB (Server Load Balancer) server name.
     required: true
     aliases: ['server']
   server_ip:
     description:
-      - SLB server IP address.
+      - The SLB server IPv4 address.
     required: false
     default: null
     aliases: ['ip', 'address']
   server_status:
     description:
-      - SLB virtual server status.
+      - The SLB virtual server status.
     required: false
     default: enabled
     aliases: ['status']
@@ -59,13 +62,25 @@ options:
     default: null
   state:
     description:
-      - Create, update or remove slb server.
+      - This is to specify the operation to create, update or remove SLB server.
     required: false
     default: present
     choices: ['present', 'absent']
+  validate_certs:
+    description:
+      - If C(no), SSL certificates will not be validated. This should only be used
+        on personally controlled devices using self-signed certificates.
+    required: false
+    version_added: 2.3
+    default: 'yes'
+    choices: ['yes', 'no']
 
 '''
 
+RETURN = '''
+#
+'''
+
 EXAMPLES = '''
 # Create a new server
 - a10_server: 
@@ -253,10 +268,12 @@ def main():
     axapi_call(module, session_url + '&method=session.close')
     module.exit_json(changed=changed, content=result)
 
-# standard ansible module imports
+# ansible module imports
-from ansible.module_utils.basic import *
+import json
-from ansible.module_utils.urls import *
+from ansible.module_utils.basic import AnsibleModule
-from ansible.module_utils.a10 import *
+from ansible.module_utils.urls import url_argument_spec
+from ansible.module_utils.a10 import axapi_call, a10_argument_spec, axapi_authenticate, axapi_failure, axapi_get_port_protocol, axapi_enabled_disabled
+
 
 if __name__ == '__main__':
     main()

lib/ansible/modules/extras/network/a10/a10_server_axapi3.py

@@ -0,0 +1,252 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+"""
+Ansible module to manage A10 Networks slb server objects
+(c) 2014, Mischa Peters <mpeters@a10networks.com>, 2016, Eric Chou <ericc@a10networks.com>
+
+This file is part of Ansible
+
+Ansible is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+Ansible is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+"""
+
+DOCUMENTATION = '''
+---
+module: a10_server_axapi3
+version_added: 2.3
+short_description: Manage A10 Networks AX/SoftAX/Thunder/vThunder devices
+description:
+    - Manage SLB (Server Load Balancer) server objects on A10 Networks devices via aXAPIv3.
+author: "Eric Chou (@ericchou) based on previous work by Mischa Peters (@mischapeters)"
+extends_documentation_fragment: a10
+options:
+  server_name:
+    description:
+      - The SLB (Server Load Balancer) server name.
+    required: true
+    aliases: ['server']
+  server_ip:
+    description:
+      - The SLB (Server Load Balancer) server IPv4 address.
+    required: true
+    aliases: ['ip', 'address']
+  server_status:
+    description:
+      - The SLB (Server Load Balancer) virtual server status.
+    required: false
+    default: enable
+    aliases: ['action']
+    choices: ['enable', 'disable']
+  server_ports:
+    description:
+      - A list of ports to create for the server. Each list item should be a dictionary which specifies the C(port:)
+        and C(protocol:).
+    required: false
+    default: null
+  operation:
+    description:
+      - Create, Update or Remove SLB server. For create and update operation, we use the IP address and server
+        name specified in the POST message. For delete operation, we use the server name in the request URI.
+    required: false
+    default: create
+    choices: ['create', 'update', 'remove']
+  validate_certs:
+    description:
+      - If C(no), SSL certificates will not be validated. This should only be used
+        on personally controlled devices using self-signed certificates.
+    required: false
+    default: 'yes'
+    choices: ['yes', 'no']
+
+'''
+
+RETURN = '''
+#
+'''
+
+EXAMPLES = '''
+# Create a new server
+- a10_server: 
+    host: a10.mydomain.com
+    username: myadmin
+    password: mypassword
+    server: test
+    server_ip: 1.1.1.100
+    validate_certs: false
+    server_status: enable
+    write_config: yes
+    operation: create
+    server_ports:
+      - port-number: 8080
+        protocol: tcp
+        action: enable
+      - port-number: 8443
+        protocol: TCP
+
+'''
+
+VALID_PORT_FIELDS = ['port-number', 'protocol', 'action']
+
+def validate_ports(module, ports):
+    for item in ports:
+        for key in item:
+            if key not in VALID_PORT_FIELDS:
+                module.fail_json(msg="invalid port field (%s), must be one of: %s" % (key, ','.join(VALID_PORT_FIELDS)))
+
+        # validate the port number is present and an integer
+        if 'port-number' in item:
+            try:
+                item['port-number'] = int(item['port-number'])
+            except:
+                module.fail_json(msg="port-number entries in the port definitions must be integers")
+        else:
+            module.fail_json(msg="port definitions must define the port-number field")
+
+        # validate the port protocol is present, no need to convert to the internal API integer value in v3
+        if 'protocol' in item:
+            protocol = item['protocol']
+            if not protocol:
+                module.fail_json(msg="invalid port protocol, must be one of: %s" % ','.join(AXAPI_PORT_PROTOCOLS))
+            else:
+                item['protocol'] = protocol
+        else:
+            module.fail_json(msg="port definitions must define the port protocol (%s)" % ','.join(AXAPI_PORT_PROTOCOLS))
+
+        # 'status' is 'action' in AXAPIv3
+        # no need to convert the status, a.k.a action, to the internal API integer value in v3
+        # action is either enabled or disabled
+        if 'action' in item:
+            action = item['action']
+            if action not in ['enable', 'disable']:
+                module.fail_json(msg="server action must be enable or disable")
+        else:
+            item['action'] = 'enable'
+
+
+def main():
+    argument_spec = a10_argument_spec()
+    argument_spec.update(url_argument_spec())
+    argument_spec.update(
+        dict(
+            operation=dict(type='str', default='create', choices=['create', 'update', 'delete']),
+            server_name=dict(type='str', aliases=['server'], required=True),
+            server_ip=dict(type='str', aliases=['ip', 'address'], required=True),
+            server_status=dict(type='str', default='enable', aliases=['action'], choices=['enable', 'disable']),
+            server_ports=dict(type='list', aliases=['port'], default=[]),
+        )
+    )
+
+    module = AnsibleModule(
+        argument_spec=argument_spec,
+        supports_check_mode=False
+    )
+
+    host = module.params['host']
+    username = module.params['username']
+    password = module.params['password']
+    operation = module.params['operation']
+    write_config = module.params['write_config']
+    slb_server = module.params['server_name']
+    slb_server_ip = module.params['server_ip']
+    slb_server_status = module.params['server_status']
+    slb_server_ports = module.params['server_ports']
+
+    axapi_base_url = 'https://{}/axapi/v3/'.format(host)
+    axapi_auth_url = axapi_base_url + 'auth/'
+    signature = axapi_authenticate_v3(module, axapi_auth_url, username, password)
+
+    # validate the ports data structure
+    validate_ports(module, slb_server_ports)
+
+
+    json_post = {
+        "server-list": [
+            {
+                "name": slb_server,
+                "host": slb_server_ip
+            }
+        ]
+    }
+
+    # add optional module parameters
+    if slb_server_ports:
+        json_post['server-list'][0]['port-list'] = slb_server_ports
+
+    if slb_server_status:
+        json_post['server-list'][0]['action'] = slb_server_status
+
+    slb_server_data = axapi_call_v3(module, axapi_base_url+'slb/server/', method='GET', body='', signature=signature)
+
+    # for empty slb server list
+    if axapi_failure(slb_server_data):
+        slb_server_exists = False
+    else:
+        slb_server_list = [server['name'] for server in slb_server_data['server-list']]
+        if slb_server in slb_server_list:
+            slb_server_exists = True
+        else:
+            slb_server_exists = False
+
+    changed = False
+    if operation == 'create':
+        if slb_server_exists == False:
+            result = axapi_call_v3(module, axapi_base_url+'slb/server/', method='POST', body=json.dumps(json_post), signature=signature)
+            if axapi_failure(result):
+                module.fail_json(msg="failed to create the server: %s" % result['response']['err']['msg'])
+            changed = True
+        else:
+            module.fail_json(msg="server already exists, use state='update' instead")
+            changed = False
+        # if we changed things, get the full info regarding result
+        if changed:
+            result = axapi_call_v3(module, axapi_base_url + 'slb/server/' + slb_server, method='GET', body='', signature=signature)
+        else:
+            result = slb_server_data
+    elif operation == 'delete':
+        if slb_server_exists:
+            result = axapi_call_v3(module, axapi_base_url + 'slb/server/' + slb_server, method='DELETE', body='', signature=signature)
+            if axapi_failure(result):
+                module.fail_json(msg="failed to delete server: %s" % result['response']['err']['msg'])
+            changed = True
+        else:
+            result = dict(msg="the server was not present")
+    elif operation == 'update':
+        if slb_server_exists:
+            result = axapi_call_v3(module, axapi_base_url + 'slb/server/', method='PUT', body=json.dumps(json_post), signature=signature)
+            if axapi_failure(result):
+                module.fail_json(msg="failed to update server: %s" % result['response']['err']['msg'])
+            changed = True
+        else:
+            result = dict(msg="the server was not present")
+
+    # if the config has changed, save the config unless otherwise requested
+    if changed and write_config:
+        write_result = axapi_call_v3(module, axapi_base_url+'write/memory/', method='POST', body='', signature=signature)
+        if axapi_failure(write_result):
+            module.fail_json(msg="failed to save the configuration: %s" % write_result['response']['err']['msg'])
+
+    # log out gracefully and exit
+    axapi_call_v3(module, axapi_base_url + 'logoff/', method='POST', body='', signature=signature)
+    module.exit_json(changed=changed, content=result)
+
+
+import json
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.urls import url_argument_spec
+from ansible.module_utils.a10 import axapi_call_v3, a10_argument_spec, axapi_authenticate_v3, axapi_failure
+
+
+if __name__ == '__main__':
+    main()
+    

lib/ansible/modules/extras/network/a10/a10_service_group.py

@@ -3,7 +3,8 @@
 
 """
 Ansible module to manage A10 Networks slb service-group objects
-(c) 2014, Mischa Peters <mpeters@a10networks.com>
+(c) 2014, Mischa Peters <mpeters@a10networks.com>,
+Eric Chou <ericc@a10networks.com>
 
 This file is part of Ansible
 
@@ -25,30 +26,31 @@ DOCUMENTATION = '''
 ---
 module: a10_service_group
 version_added: 1.8
-short_description: Manage A10 Networks devices' service groups
+short_description: Manage A10 Networks AX/SoftAX/Thunder/vThunder devices' service groups.
 description:
-    - Manage slb service-group objects on A10 Networks devices via aXAPI
+    - Manage SLB (Server Load Balancing) service-group objects on A10 Networks devices via aXAPIv2.
-author: "Mischa Peters (@mischapeters)"
+author: "Eric Chou (@ericchou) 2016, Mischa Peters (@mischapeters) 2014"
 notes:
-    - When a server doesn't exist and is added to the service-group the server will be created
+    - Requires A10 Networks aXAPI 2.1.
+    - When a server doesn't exist and is added to the service-group the server will be created.
 extends_documentation_fragment: a10
 options:
   service_group:
     description:
-      - SLB service-group name.
+      - The SLB (Server Load Balancing) service-group name
     required: true
     default: null
     aliases: ['service', 'pool', 'group']
   service_group_protocol:
     description:
-      - SLB service-group protocol.
+      - The SLB service-group protocol of TCP or UDP.
     required: false
     default: tcp
     aliases: ['proto', 'protocol']
     choices: ['tcp', 'udp']
   service_group_method:
     description:
-      - SLB service-group loadbalancing method.
+      - The SLB service-group load balancing method, such as round-robin or weighted-rr.
     required: false
     default: round-robin
     aliases: ['method']
@@ -60,9 +62,20 @@ options:
         specify the C(status:). See the examples below for details.
     required: false
     default: null
+  validate_certs:
+    description:
+      - If C(no), SSL certificates will not be validated. This should only be used
+        on personally controlled devices using self-signed certificates.
+    required: false
+    default: 'yes'
+    choices: ['yes', 'no']
 
 '''
 
+RETURN = '''
+#
+'''
+
 EXAMPLES = '''
 # Create a new service-group
 - a10_service_group: 
@@ -294,9 +307,11 @@ def main():
     module.exit_json(changed=changed, content=result)
 
 # standard ansible module imports
-from ansible.module_utils.basic import *
+import json
-from ansible.module_utils.urls import *
+from ansible.module_utils.basic import AnsibleModule
-from ansible.module_utils.a10 import *
+from ansible.module_utils.urls import url_argument_spec
+from ansible.module_utils.a10 import axapi_call, a10_argument_spec, axapi_authenticate, axapi_failure, axapi_enabled_disabled
+
 
 if __name__ == '__main__':
     main()

lib/ansible/modules/extras/network/a10/a10_virtual_server.py

@@ -3,7 +3,8 @@
 
 """
 Ansible module to manage A10 Networks slb virtual server objects
-(c) 2014, Mischa Peters <mpeters@a10networks.com>
+(c) 2014, Mischa Peters <mpeters@a10networks.com>,
+Eric Chou <ericc@a10networks.com>
 
 This file is part of Ansible
 
@@ -25,27 +26,29 @@ DOCUMENTATION = '''
 ---
 module: a10_virtual_server
 version_added: 1.8
-short_description: Manage A10 Networks devices' virtual servers
+short_description: Manage A10 Networks AX/SoftAX/Thunder/vThunder devices' virtual servers.
 description:
-    - Manage slb virtual server objects on A10 Networks devices via aXAPI
+    - Manage SLB (Server Load Balancing) virtual server objects on A10 Networks devices via aXAPIv2.
-author: "Mischa Peters (@mischapeters)"
+author: "Eric Chou (@ericchou) 2016, Mischa Peters (@mischapeters) 2014"
+notes:
+    - Requires A10 Networks aXAPI 2.1.
 extends_documentation_fragment: a10
 options:
   virtual_server:
     description:
-      - SLB virtual server name.
+      - The SLB (Server Load Balancing) virtual server name.
     required: true
     default: null
     aliases: ['vip', 'virtual']
   virtual_server_ip:
     description:
-      - SLB virtual server IP address.
+      - The SLB virtual server IPv4 address.
     required: false
     default: null
     aliases: ['ip', 'address']
   virtual_server_status:
     description:
-      - SLB virtual server status.
+      - The SLB virtual server status, such as enabled or disabled.
     required: false
     default: enable
     aliases: ['status']
@@ -57,9 +60,20 @@ options:
         specify the C(service_group:) as well as the C(status:). See the examples
         below for details. This parameter is required when C(state) is C(present).
     required: false
+  validate_certs:
+    description:
+      - If C(no), SSL certificates will not be validated. This should only be used
+        on personally controlled devices using self-signed certificates.
+    required: false
+    default: 'yes'
+    choices: ['yes', 'no']
 
 '''
 
+RETURN = '''
+#
+'''
+
 EXAMPLES = '''
 # Create a new virtual server
 - a10_virtual_server: 
@@ -248,9 +262,11 @@ def main():
     module.exit_json(changed=changed, content=result)
 
 # standard ansible module imports
-from ansible.module_utils.basic import *
+import json
-from ansible.module_utils.urls import *
+from ansible.module_utils.basic import AnsibleModule
-from ansible.module_utils.a10 import *
+from ansible.module_utils.urls import url_argument_spec
+from ansible.module_utils.a10 import axapi_call, a10_argument_spec, axapi_authenticate, axapi_failure, axapi_enabled_disabled, axapi_get_vport_protocol
+
 
 if __name__ == '__main__':
     main()