bigip_selfip.py

#!/usr/bin/python
# -*- coding: utf-8 -*-
#
# Copyright 2016 F5 Networks Inc.
#
# 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/>.

ANSIBLE_METADATA = {
    'status': ['preview'],
    'supported_by': 'community',
    'metadata_version': '1.0'
}

DOCUMENTATION = '''
---
module: bigip_selfip
short_description: Manage Self-IPs on a BIG-IP system.
description:
  - Manage Self-IPs on a BIG-IP system.
version_added: "2.2"
options:
  address:
    description:
      - The IP addresses for the new self IP. This value is ignored upon update
        as addresses themselves cannot be changed after they are created.
  allow_service:
    description:
      - Configure port lockdown for the Self IP. By default, the Self IP has a
        "default deny" policy. This can be changed to allow TCP and UDP ports
        as well as specific protocols. This list should contain C(protocol):C(port)
        values.
  name:
    description:
      - The self IP to create.
    required: True
    default: Value of C(address)
  netmask:
    description:
      - The netmask for the self IP. When creating a new Self IP, this value
        is required.
  state:
    description:
      - The state of the variable on the system. When C(present), guarantees
        that the Self-IP exists with the provided attributes. When C(absent),
        removes the Self-IP from the system.
    default: present
    choices:
      - absent
      - present
  traffic_group:
    description:
      - The traffic group for the Self IP addresses in an active-active,
        redundant load balancer configuration. When creating a new Self IP, if
        this value is not specified, the default of C(/Common/traffic-group-local-only)
        will be used.
  vlan:
    description:
      - The VLAN that the new self IPs will be on. When creating a new Self
        IP, this value is required.
  route_domain:
    description:
        - The route domain id of the system. When creating a new Self IP, if
          this value is not specified, a default value of C(0) will be used.
    version_added: 2.3
notes:
  - Requires the f5-sdk Python package on the host. This is as easy as pip
    install f5-sdk.
  - Requires the netaddr Python package on the host.
extends_documentation_fragment: f5
requirements:
  - netaddr
  - f5-sdk
author:
  - Tim Rupp (@caphrim007)
'''

EXAMPLES = '''
- name: Create Self IP
  bigip_selfip:
      address: "10.10.10.10"
      name: "self1"
      netmask: "255.255.255.0"
      password: "secret"
      server: "lb.mydomain.com"
      user: "admin"
      validate_certs: "no"
      vlan: "vlan1"
  delegate_to: localhost

- name: Create Self IP with a Route Domain
  bigip_selfip:
      server: "lb.mydomain.com"
      user: "admin"
      password: "secret"
      validate_certs: "no"
      name: "self1"
      address: "10.10.10.10"
      netmask: "255.255.255.0"
      vlan: "vlan1"
      route_domain: "10"
      allow_service: "default"
  delegate_to: localhost

- name: Delete Self IP
  bigip_selfip:
      name: "self1"
      password: "secret"
      server: "lb.mydomain.com"
      state: "absent"
      user: "admin"
      validate_certs: "no"
  delegate_to: localhost

- name: Allow management web UI to be accessed on this Self IP
  bigip_selfip:
      name: "self1"
      password: "secret"
      server: "lb.mydomain.com"
      state: "absent"
      user: "admin"
      validate_certs: "no"
      allow_service:
          - "tcp:443"
  delegate_to: localhost

- name: Allow HTTPS and SSH access to this Self IP
  bigip_selfip:
      name: "self1"
      password: "secret"
      server: "lb.mydomain.com"
      state: "absent"
      user: "admin"
      validate_certs: "no"
      allow_service:
          - "tcp:443"
          - "tpc:22"
  delegate_to: localhost

- name: Allow all services access to this Self IP
  bigip_selfip:
      name: "self1"
      password: "secret"
      server: "lb.mydomain.com"
      state: "absent"
      user: "admin"
      validate_certs: "no"
      allow_service:
          - all
  delegate_to: localhost

- name: Allow only GRE and IGMP protocols access to this Self IP
  bigip_selfip:
      name: "self1"
      password: "secret"
      server: "lb.mydomain.com"
      state: "absent"
      user: "admin"
      validate_certs: "no"
      allow_service:
          - gre:0
          - igmp:0
  delegate_to: localhost

- name: Allow all TCP, but no other protocols access to this Self IP
  bigip_selfip:
      name: "self1"
      password: "secret"
      server: "lb.mydomain.com"
      state: "absent"
      user: "admin"
      validate_certs: "no"
      allow_service:
          - tcp:0
  delegate_to: localhost
'''

RETURN = '''
allow_service:
    description: Services that allowed via this Self IP
    returned: changed
    type: list
    sample: ['igmp:0','tcp:22','udp:53']
address:
    description: The address for the Self IP
    returned: created
    type: string
    sample: "192.0.2.10"
name:
    description: The name of the Self IP
    returned:
        - created
        - changed
        - deleted
    type: string
    sample: "self1"
netmask:
    description: The netmask of the Self IP
    returned:
        - changed
        - created
    type: string
    sample: "255.255.255.0"
traffic_group:
    description: The traffic group that the Self IP is a member of
    return:
        - changed
        - created
    type: string
    sample: "traffic-group-local-only"
vlan:
    description: The VLAN set on the Self IP
    return:
        - changed
        - created
    type: string
    sample: "vlan1"
'''

import re

from ansible.module_utils.f5_utils import AnsibleF5Client
from ansible.module_utils.f5_utils import AnsibleF5Parameters
from ansible.module_utils.f5_utils import F5ModuleError
from ansible.module_utils.f5_utils import defaultdict
from ansible.module_utils.f5_utils import iteritems

try:
    from ansible.module_utils.f5_utils import HAS_F5SDK
    from ansible.module_utils.f5_utils import iControlUnexpectedHTTPError
except ImportError:
    HAS_F5SDK = False

try:
    from netaddr import IPNetwork, AddrFormatError, IPAddress
    HAS_NETADDR = True
except ImportError:
    HAS_NETADDR = False


class Parameters(AnsibleF5Parameters):
    api_map = {
        'trafficGroup': 'traffic_group',
        'allowService': 'allow_service'
    }

    updatables = [
        'traffic_group', 'allow_service', 'vlan', 'route_domain', 'netmask'
    ]

    returnables = [
        'traffic_group', 'allow_service', 'vlan', 'route_domain', 'netmask'
    ]

    api_attributes = [
        'trafficGroup', 'allowService', 'vlan', 'address'
    ]

    def __init__(self, params=None):
        self._values = defaultdict(lambda: None)
        self._values['__warnings'] = []
        if params:
            self.update(params=params)

    def update(self, params=None):
        if params:
            for k, v in iteritems(params):
                if self.api_map is not None and k in self.api_map:
                    map_key = self.api_map[k]
                else:
                    map_key = k

                # Handle weird API parameters like `dns.proxy.__iter__` by
                # using a map provided by the module developer
                class_attr = getattr(type(self), map_key, None)
                if isinstance(class_attr, property):
                    # There is a mapped value for the api_map key
                    if class_attr.fset is None:
                        # If the mapped value does not have
                        # an associated setter
                        self._values[map_key] = v
                    else:
                        # The mapped value has a setter
                        setattr(self, map_key, v)
                else:
                    # If the mapped value is not a @property
                    self._values[map_key] = v

    def to_return(self):
        result = {}
        for returnable in self.returnables:
            result[returnable] = getattr(self, returnable)
        result = self._filter_params(result)
        return result

    def api_params(self):
        result = {}
        for api_attribute in self.api_attributes:
            if self.api_map is not None and api_attribute in self.api_map:
                result[api_attribute] = getattr(self, self.api_map[api_attribute])
            else:
                result[api_attribute] = getattr(self, api_attribute)
        result = self._filter_params(result)
        return result

    @property
    def address(self):
        address = "{0}%{1}/{2}".format(
            self.ip, self.route_domain, self.netmask
        )
        return address

    @address.setter
    def address(self, value):
        self._values['ip'] = value

    @property
    def ip(self):
        if self._values['ip'] is None:
            return None
        try:
            ip = str(IPAddress(self._values['ip']))
            return ip
        except AddrFormatError:
            raise F5ModuleError(
                'The provided address is not a valid IP address'
            )

    @property
    def traffic_group(self):
        if self._values['traffic_group'] is None:
            return None
        if self._values['traffic_group'].startswith('/'):
            return self._values['traffic_group']
        else:
            return '/{0}/{1}'.format(self.partition, self._values['traffic_group'])

    @property
    def route_domain(self):
        if self._values['route_domain'] is None:
            return None
        result = int(self._values['route_domain'])
        return result

    @property
    def netmask(self):
        if self._values['netmask'] is None:
            return None
        try:
            address = '0.0.0.0/'+self._values['netmask']
            ip = IPNetwork(address)
            result = ip.prefixlen
        except (AddrFormatError, ValueError):
            try:
                result = int(self._values['netmask'])
            except ValueError:
                raise F5ModuleError(
                    'The provided netmask is neither in IP or CIDR format'
                )
        if 0 < result < 33:
            return result
        raise F5ModuleError(
            'The provided netmask must be a valid IP or CIDR master'
        )

    @property
    def allow_service(self):
        """Verifies that a supplied service string has correct format

        The string format for port lockdown is PROTOCOL:PORT. This method
        will verify that the provided input matches the allowed protocols
        and the port ranges before submitting to BIG-IP.

        The only allowed exceptions to this rule are the following values

          * all
          * default
          * none

        These are special cases that are handled differently in the API.
        "all" is set as a string, "default" is set as a one item list, and
        "none" removes the key entirely from the REST API.

        :raises F5ModuleError:
        """
        if self._values['allow_service'] is None:
            return None
        result = []
        allowed_protocols = [
            'eigrp', 'egp', 'gre', 'icmp', 'igmp', 'igp', 'ipip',
            'l2tp', 'ospf', 'pim', 'tcp', 'udp'
        ]
        special_protocols = [
            'all', 'none', 'default'
        ]
        for svc in self._values['allow_service']:
            if svc in special_protocols:
                result = [svc]
                break
            elif svc in allowed_protocols:
                result.append(svc)
            else:
                tmp = svc.split(':')
                if tmp[0] not in allowed_protocols:
                    raise F5ModuleError(
                        "The provided protocol '%s' is invalid" % (tmp[0])
                    )
                try:
                    port = int(tmp[1])
                except Exception:
                    raise F5ModuleError(
                        "The provided port '%s' is not a number" % (tmp[1])
                    )

                if port < 0 or port > 65535:
                    raise F5ModuleError(
                        "The provided port '{0}' must be between 0 and 65535".format(port)
                    )
                else:
                    result.append(svc)
        return set(result)

    @property
    def vlan(self):
        if self._values['vlan'] is None:
            return None
        if self._values['vlan'].startswith('/' + self.partition):
            return self._values['vlan']
        else:
            return '/{0}/{1}'.format(self.partition, self._values['vlan'])


class ApiParameters(Parameters):
    api_map = {}

    @property
    def address(self):
        if self.ip and self.route_domain and self.netmask:
            return '{0}%{1}/{2}'.format(self.ip, self.route_domain, self.netmask)
        elif self.ip and self.netmask:
            return '{0}/{1}'.format(self.ip, self.netmask)

    @address.setter
    def address(self, value):
        pattern = '^(?P<ip>[0-9A-Fa-f:.]+)%?(?P<rd>\d+)?\/(?P<nm>\d+)$'
        matches = re.match(pattern, value)
        if not matches:
            raise F5ModuleError(
                "The specified address is malformed. Please see documentation."
            )
        try:
            ip = matches.group('ip')
            self._values['ip']= str(IPAddress(ip))
        except AddrFormatError:
            raise F5ModuleError(
                'The provided address is not a valid IP address'
            )
        self._values['route_domain'] = matches.group('rd')
        self._values['netmask'] = matches.group('nm')

    @property
    def allow_service(self):
        return self._values['allow_service']

    @property
    def trafficGroup(self):
        return self.traffic_group

    @trafficGroup.setter
    def trafficGroup(self, value):
        self._values['traffic_group'] = value

    @property
    def allowService(self):
        return self._values['allow_service']

    @allowService.setter
    def allowService(self, value):
        if value == 'all':
            self._values['allow_service'] = set(['all'])
        else:
            self._values['allow_service'] = set([str(x) for x in value])


class ModuleManager(object):
    def __init__(self, client):
        self.client = client
        self.have = None
        self.want = Parameters(self.client.module.params)
        self.changes = ApiParameters()

    def _set_changed_options(self):
        changed = {}
        for key in Parameters.returnables:
            if getattr(self.want, key) is not None:
                changed[key] = getattr(self.want, key)
        if changed:
            self.changes = Parameters(changed)

    def _update_changed_options(self):
        diff = Difference(self.want, self.have)
        updatables = ApiParameters.updatables
        changed = dict()
        for k in updatables:
            change = diff.compare(k)
            if change is None:
                continue
            else:
                if k in ['netmask', 'route_domain']:
                    changed['address'] = change
                else:
                    changed[k] = change
        if changed:
            self.changes = ApiParameters(changed)
            return True
        return False

    def exec_module(self):
        changed = False
        result = dict()
        state = self.want.state

        try:
            if state == "present":
                changed = self.present()
            elif state == "absent":
                changed = self.absent()
        except iControlUnexpectedHTTPError as e:
            raise F5ModuleError(str(e))

        changes = self.changes.to_return()
        result.update(**changes)
        result.update(dict(changed=changed))
        return result

    def present(self):
        if self.exists():
            changed = self.update()
        else:
            changed = self.create()
        return changed

    def absent(self):
        changed = False
        if self.exists():
            changed = self.remove()
        return changed

    def should_update(self):
        result = self._update_changed_options()
        if result:
            return True
        return False

    def read_current_from_device(self):
        resource = self.client.api.tm.net.selfips.selfip.load(
            name=self.want.name,
            partition=self.want.partition
        )
        result = resource.attrs
        params = ApiParameters(result)
        return params

    def update(self):
        self.have = self.read_current_from_device()
        if not self.should_update():
            return False
        if self.client.check_mode:
            return True
        self.update_on_device()
        return True

    def update_on_device(self):
        params = self.changes.api_params()
        resource = self.client.api.tm.net.selfips.selfip.load(
            name=self.want.name,
            partition=self.want.partition
        )
        resource.modify(**params)

    def create(self):
        if self.want.address is None or self.want.netmask is None:
            raise F5ModuleError(
                'An address and a netmask must be specified'
            )
        if self.want.vlan is None:
            raise F5ModuleError(
                'A VLAN name must be specified'
            )
        if self.want.traffic_group is None:
            self.want.update({'traffic_group': '/Common/traffic-group-local-only'})
        if self.want.route_domain is None:
            self.want.update({'route_domain': 0})

        if self.want.check_mode:
            return True
        self.create_on_device()
        if self.exists():
            return True
        else:
            raise F5ModuleError("Failed to create the Self IP")

    def create_on_device(self):
        params = self.want.api_params()
        self.client.api.tm.net.selfips.selfip.create(
            name=self.want.name,
            partition=self.want.partition,
            **params
        )

    def remove(self):
        if self.client.check_mode:
            return True
        self.remove_from_device()
        if self.exists():
            raise F5ModuleError("Failed to delete the Self IP")
        return True

    def remove_from_device(self):
        resource = self.client.api.tm.net.selfips.selfip.load(
            name=self.want.name,
            partition=self.want.partition
        )
        resource.delete()

    def exists(self):
        result = self.client.api.tm.net.selfips.selfip.exists(
            name=self.want.name,
            partition=self.want.partition
        )
        return result


class Difference(object):
    def __init__(self, want, have=None):
        self.want = want
        self.have = have

    def compare(self, param):
        try:
            result = getattr(self, param)
            return result
        except AttributeError:
            return self.__default(param)

    def __default(self, param):
        attr1 = getattr(self.want, param)
        try:
            attr2 = getattr(self.have, param)
            if attr1 != attr2:
                return attr1
        except AttributeError:
            return attr1

    @property
    def allow_service(self):
        """Returns services formatted for consumption by f5-sdk update

        The BIG-IP endpoint for services takes different values depending on
        what you want the "allowed services" to be. It can be any of the
        following

            - a list containing "protocol:port" values
            - the string "all"
            - a null value, or None

        This is a convenience function to massage the values the user has
        supplied so that they are formatted in such a way that BIG-IP will
        accept them and apply the specified policy.

        :param services: The services to format. This is always a Python set
        :return:
        """
        if self.want.allow_service is None:
            return None
        result = list(self.want.allow_service)
        if self.want.allow_service == self.have.allow_service:
            return None
        elif result[0] == 'none' and self.have.allow_service is None:
            return None
        elif result[0] == 'all':
            return 'all'
        elif result[0] == 'none':
            return []
        else:
            return list(result)

    @property
    def netmask(self):
        if self.want.netmask is None:
            return None
        try:
            address = IPNetwork(self.have.ip)
            if self.want.route_domain is not None:
                nipnet = "{0}%{1}/{2}".format(address.ip, self.want.route_domain, self.want.netmask)
                cipnet = "{0}%{1}/{2}".format(address.ip, self.want.route_domain, self.have.netmask)
            elif self.have.route_domain is not None:
                nipnet = "{0}%{1}/{2}".format(address.ip, self.have.route_domain, self.want.netmask)
                cipnet = "{0}%{1}/{2}".format(address.ip, self.have.route_domain, self.have.netmask)
            else:
                nipnet = "{0}/{1}".format(address.ip, self.want.netmask)
                cipnet = "{0}/{1}".format(address.ip, self.have.netmask)
            if nipnet != cipnet:
                return nipnet
        except AddrFormatError:
            raise F5ModuleError(
                'The provided address/netmask value was invalid'
            )

    @property
    def route_domain(self):
        if self.want.route_domain is None:
            return None
        try:
            address = IPNetwork(self.have.ip)

            if self.want.netmask is not None:
                nipnet = "{0}%{1}/{2}".format(address.ip, self.want.route_domain, self.want.netmask)
                cipnet = "{0}%{1}/{2}".format(address.ip, self.have.route_domain, self.want.netmask)
            elif self.have.netmask is not None:
                nipnet = "{0}%{1}/{2}".format(address.ip, self.want.route_domain, self.have.netmask)
                cipnet = "{0}%{1}/{2}".format(address.ip, self.have.route_domain, self.have.netmask)

            if nipnet != cipnet:
                return nipnet
        except AddrFormatError:
            raise F5ModuleError(
                'The provided address/netmask value was invalid'
            )

    @property
    def traffic_group(self):
        if self.want.traffic_group == self.have.traffic_group:
            return None
        return self.want.traffic_group


class ArgumentSpec(object):
    def __init__(self):
        self.supports_check_mode = True
        self.argument_spec = dict(
            address=dict(),
            allow_service=dict(type='list'),
            name=dict(required=True),
            netmask=dict(),
            traffic_group=dict(),
            vlan=dict(),
            route_domain=dict()
        )
        self.f5_product_name = 'bigip'


def main():
    if not HAS_F5SDK:
        raise F5ModuleError("The python f5-sdk module is required")

    if not HAS_NETADDR:
        raise F5ModuleError("The python netaddr module is required")

    spec = ArgumentSpec()

    client = AnsibleF5Client(
        argument_spec=spec.argument_spec,
        supports_check_mode=spec.supports_check_mode,
        f5_product_name=spec.f5_product_name
    )

    try:
        mm = ModuleManager(client)
        results = mm.exec_module()
        client.module.exit_json(**results)
    except F5ModuleError as e:
        client.module.fail_json(msg=str(e))

if __name__ == '__main__':
    main()