ansible/cloud/openstack/os_security_group_rule.py

#!/usr/bin/python

# Copyright (c) 2015 Hewlett-Packard Development Company, L.P.
# Copyright (c) 2013, Benno Joy <benno@ansible.com>
#
# This module 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.
#
# This software 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 this software.  If not, see <http://www.gnu.org/licenses/>.

try:
    import shade
    HAS_SHADE = True
except ImportError:
    HAS_SHADE = False


DOCUMENTATION = '''
---
module: os_security_group_rule
short_description: Add/Delete rule from an existing security group
extends_documentation_fragment: openstack
version_added: "2.0"
description:
   - Add or Remove rule from an existing security group
options:
   security_group:
     description:
        - Name of the security group
     required: true
   protocol:
      description:
        - IP protocol
      choices: ['tcp', 'udp', 'icmp', None]
      default: None
   port_range_min:
      description:
        - Starting port
      required: false
      default: None
   port_range_max:
      description:
        - Ending port
      required: false
      default: None
   remote_ip_prefix:
      description:
        - Source IP address(es) in CIDR notation (exclusive with remote_group)
      required: false
   remote_group:
      description:
        - ID of Security group to link (exclusive with remote_ip_prefix)
      required: false
   ethertype:
      description:
        - Must be IPv4 or IPv6, and addresses represented in CIDR must
          match the ingress or egress rules. Not all providers support IPv6.
      choices: ['IPv4', 'IPv6']
      default: IPv4
   direction:
     description:
        - The direction in which the security group rule is applied. Not
          all providers support egress.
     choices: ['egress', 'ingress']
     default: ingress
   state:
     description:
       - Should the resource be present or absent.
     choices: [present, absent]
     default: present
requirements: ["shade"]
'''

EXAMPLES = '''
# Create a security group rule
- os_security_group_rule:
    cloud: mordred
    security_group: foo
    protocol: tcp
    port_range_min: 80
    port_range_max: 80
    remote_ip_prefix: 0.0.0.0/0

# Create a security group rule for ping
- os_security_group_rule:
    cloud: mordred
    security_group: foo
    protocol: icmp
    remote_ip_prefix: 0.0.0.0/0

# Another way to create the ping rule
- os_security_group_rule:
    cloud: mordred
    security_group: foo
    protocol: icmp
    port_range_min: -1
    port_range_max: -1
    remote_ip_prefix: 0.0.0.0/0

# Create a TCP rule covering all ports
- os_security_group_rule:
    cloud: mordred
    security_group: foo
    protocol: tcp
    port_range_min: 1
    port_range_max: 65535
    remote_ip_prefix: 0.0.0.0/0

# Another way to create the TCP rule above (defaults to all ports)
- os_security_group_rule:
    cloud: mordred
    security_group: foo
    protocol: tcp
    remote_ip_prefix: 0.0.0.0/0
'''

RETURN = '''
id:
  description: Unique rule UUID.
  type: string
direction:
  description: The direction in which the security group rule is applied.
  type: string
  sample: 'egress'
ethertype:
  description: One of IPv4 or IPv6.
  type: string
  sample: 'IPv4'
port_range_min:
  description: The minimum port number in the range that is matched by
               the security group rule.
  type: int
  sample: 8000
port_range_max:
  description: The maximum port number in the range that is matched by
               the security group rule.
  type: int
  sample: 8000
protocol:
  description: The protocol that is matched by the security group rule.
  type: string
  sample: 'tcp'
remote_ip_prefix:
  description: The remote IP prefix to be associated with this security group rule.
  type: string
  sample: '0.0.0.0/0'
security_group_id:
  description: The security group ID to associate with this security group rule.
  type: string
'''


def _ports_match(protocol, module_min, module_max, rule_min, rule_max):
    """
    Capture the complex port matching logic.

    The port values coming in for the module might be -1 (for ICMP),
    which will work only for Nova, but this is handled by shade. Likewise,
    they might be None, which works for Neutron, but not Nova. This too is
    handled by shade. Since shade will consistently return these port
    values as None, we need to convert any -1 values input to the module
    to None here for comparison.

    For TCP and UDP protocols, None values for both min and max are
    represented as the range 1-65535 for Nova, but remain None for
    Neutron. Shade returns the full range when Nova is the backend (since
    that is how Nova stores them), and None values for Neutron. If None
    values are input to the module for both values, then we need to adjust
    for comparison.
    """

    # Check if the user is supplying -1 for ICMP.
    if protocol == 'icmp':
        if module_min and int(module_min) == -1:
            module_min = None
        if module_max and int(module_max) == -1:
            module_max = None

    # Check if user is supplying None values for full TCP/UDP port range.
    if protocol in ['tcp', 'udp'] and module_min is None and module_max is None:
        if (rule_min and int(rule_min) == 1
                and rule_max and int(rule_max) == 65535):
            # (None, None) == (1, 65535)
            return True

    # Sanity check to make sure we don't have type comparison issues.
    if module_min:
        module_min = int(module_min)
    if module_max:
        module_max = int(module_max)
    if rule_min:
        rule_min = int(rule_min)
    if rule_max:
        rule_max = int(rule_max)

    return module_min == rule_min and module_max == rule_max


def _find_matching_rule(module, secgroup):
    """
    Find a rule in the group that matches the module parameters.
    :returns: The matching rule dict, or None if no matches.
    """
    protocol = module.params['protocol']
    remote_ip_prefix = module.params['remote_ip_prefix']
    ethertype = module.params['ethertype']
    direction = module.params['direction']

    for rule in secgroup['security_group_rules']:
        if (protocol == rule['protocol']
                and remote_ip_prefix == rule['remote_ip_prefix']
                and ethertype == rule['ethertype']
                and direction == rule['direction']
                and _ports_match(protocol,
                                 module.params['port_range_min'],
                                 module.params['port_range_max'],
                                 rule['port_range_min'],
                                 rule['port_range_max'])):
            return rule
    return None


def _system_state_change(module, secgroup):
    state = module.params['state']
    if secgroup:
        rule_exists = _find_matching_rule(module, secgroup)
    else:
        return False

    if state == 'present' and not rule_exists:
        return True
    if state == 'absent' and rule_exists:
        return True
    return False


def main():
    argument_spec = openstack_full_argument_spec(
        security_group   = dict(required=True),
        # NOTE(Shrews): None is an acceptable protocol value for
        # Neutron, but Nova will balk at this.
        protocol         = dict(default=None,
                                choices=[None, 'tcp', 'udp', 'icmp']),
        port_range_min   = dict(required=False, type='int'),
        port_range_max   = dict(required=False, type='int'),
        remote_ip_prefix = dict(required=False, default=None),
        # TODO(mordred): Make remote_group handle name and id
        remote_group     = dict(required=False, default=None),
        ethertype        = dict(default='IPv4',
                                choices=['IPv4', 'IPv6']),
        direction        = dict(default='ingress',
                                choices=['egress', 'ingress']),
        state            = dict(default='present',
                                choices=['absent', 'present']),
    )

    module_kwargs = openstack_module_kwargs(
        mutually_exclusive=[
            ['remote_ip_prefix', 'remote_group'],
        ]
    )

    module = AnsibleModule(argument_spec,
                           supports_check_mode=True,
                           **module_kwargs)

    if not HAS_SHADE:
        module.fail_json(msg='shade is required for this module')

    state = module.params['state']
    security_group = module.params['security_group']
    changed = False

    try:
        cloud = shade.openstack_cloud(**module.params)
        secgroup = cloud.get_security_group(security_group)

        if module.check_mode:
            module.exit_json(changed=_system_state_change(module, secgroup))

        if state == 'present':
            if not secgroup:
                module.fail_json(msg='Could not find security group %s' %
                                 security_group)

            rule = _find_matching_rule(module, secgroup)
            if not rule:
                rule = cloud.create_security_group_rule(
                    secgroup['id'],
                    port_range_min=module.params['port_range_min'],
                    port_range_max=module.params['port_range_max'],
                    protocol=module.params['protocol'],
                    remote_ip_prefix=module.params['remote_ip_prefix'],
                    remote_group_id=module.params['remote_group'],
                    direction=module.params['direction'],
                    ethertype=module.params['ethertype']
                )
                changed = True
            module.exit_json(changed=changed, rule=rule, id=rule['id'])

        if state == 'absent' and secgroup:
            rule = _find_matching_rule(module, secgroup)
            if rule:
                cloud.delete_security_group_rule(rule['id'])
                changed = True

            module.exit_json(changed=changed)

    except shade.OpenStackCloudException as e:
        module.fail_json(msg=e.message)

# this is magic, see lib/ansible/module_common.py
from ansible.module_utils.basic import *
from ansible.module_utils.openstack import *

if __name__ == '__main__':
    main()