From 557320ea8a1e8c5aa402d34a31c246d3d3e95d50 Mon Sep 17 00:00:00 2001 From: Andrea Frittoli Date: Wed, 9 Aug 2017 21:08:08 +0100 Subject: [PATCH] Add docstring for validation resources Change-Id: I942326e17ff014103635ec92764c69d90f67a6a0 --- tempest/common/validation_resources.py | 121 ++++++++++++++++++++++++- 1 file changed, 120 insertions(+), 1 deletion(-) diff --git a/tempest/common/validation_resources.py b/tempest/common/validation_resources.py index 275289941e..5d62f67a41 100644 --- a/tempest/common/validation_resources.py +++ b/tempest/common/validation_resources.py @@ -20,6 +20,7 @@ LOG = logging.getLogger(__name__) def _network_service(os, use_neutron): + # Internal helper to select the right network clients if use_neutron: return os.network else: @@ -28,6 +29,36 @@ def _network_service(os, use_neutron): def create_ssh_security_group(os, add_rule=False, ethertype='IPv4', use_neutron=True): + """Create a security group for ping/ssh testing + + Create a security group to be attached to a VM using the nova or neutron + clients. If rules are added, the group can be attached to a VM to enable + connectivity validation over ICMP and further testing over SSH. + + :param os: An instance of `tempest.lib.services.clients.ServiceClients` or + of a subclass of it. Resources are provisioned using clients from `os`. + :param add_rule: Whether security group rules are provisioned or not. + Defaults to `False`. + :param ethertype: 'IPv4' or 'IPv6'. Honoured only in case neutron is used. + :param use_neutron: When True resources are provisioned via neutron, when + False resources are provisioned via nova. + :returns: A dictionary with the security group as returned by the API. + + Examples:: + + from tempest.common import validation_resources as vr + from tempest.lib import auth + from tempest.lib.services import clients + + creds = auth.get_credentials('http://mycloud/identity/v3', + username='me', project_name='me', + password='secret', domain_name='Default') + os = clients.ServiceClients(creds, 'http://mycloud/identity/v3') + # Security group for IPv4 tests + sg4 = vr.create_ssh_security_group(os, add_rule=True) + # Security group for IPv6 tests + sg6 = vr.create_ssh_security_group(os, ethertype='IPv6', add_rule=True) + """ network_service = _network_service(os, use_neutron) security_groups_client = network_service.SecurityGroupsClient() security_group_rules_client = network_service.SecurityGroupRulesClient() @@ -68,6 +99,53 @@ def create_validation_resources(os, validation_resources=None, ethertype='IPv4', use_neutron=True, floating_network_id=None, floating_network_name=None): + """Provision resources for VM ping/ssh testing + + Create resources required to be able to ping / ssh a virtual machine: + keypair, security group, security group rules and a floating IP. + Which of those resources are required may depend on the cloud setup and on + the specific test and it can be controlled via the validation_resources + dictionary. + + Provisioned resources are returned in a dictionary. + + :param os: An instance of `tempest.lib.services.clients.ServiceClients` or + of a subclass of it. Resources are provisioned using clients from `os`. + :param validation_resources: A dictionary that specifies which resources to + provision. Required keys are: 'keypair', 'security_group', + 'security_group_rules' and 'floating_ip'. + :param ethertype: 'IPv4' or 'IPv6'. Honoured only in case neutron is used. + :param use_neutron: When True resources are provisioned via neutron, when + False resources are provisioned via nova. + :param floating_network_id: The id of the network used to provision a + floating IP. Only used if a floating IP is requested and with neutron. + :param floating_network_name: The name of the floating IP pool used to + provision the floating IP. Only used if a floating IP is requested and + with nova-net. + :returns: A dictionary with the same keys as the input + `validation_resources` and the resources for values in the format + they are returned by the API. + + Examples:: + + from tempest.common import validation_resources as vr + from tempest.lib import auth + from tempest.lib.services import clients + + creds = auth.get_credentials('http://mycloud/identity/v3', + username='me', project_name='me', + password='secret', domain_name='Default') + os = clients.ServiceClients(creds, 'http://mycloud/identity/v3') + # Request keypair and floating IP + resources = dict(keypair=True, security_group=False, + security_group_rules=False, floating_ip=True) + resources = vr.create_validation_resources( + os, validation_resources=resources, use_neutron=True, + floating_network_id='4240E68E-23DA-4C82-AC34-9FEFAA24521C') + + # The floating IP to be attached to the VM + floating_ip = resources['floating_ip']['ip'] + """ # Create and Return the validation resources required to validate a VM validation_data = {} if validation_resources: @@ -106,7 +184,48 @@ def create_validation_resources(os, validation_resources=None, def clear_validation_resources(os, validation_data=None, use_neutron=True): - # Cleanup the vm validation resources + """Cleanup resources for VM ping/ssh testing + + Cleanup a set of resources provisioned via `create_validation_resources`. + In case of errors during cleanup, the exception is logged and the cleanup + process is continued. The first exception that was raised is re-raised + after the cleanup is complete. + + :param os: An instance of `tempest.lib.services.clients.ServiceClients` or + of a subclass of it. Resources are provisioned using clients from `os`. + :param validation_data: A dictionary that specifies resources to be + cleaned up in the format returned by `create_validation_resources`. + Required keys are: 'keypair', 'security_group', 'security_group_rules' + and 'floating_ip'. + :param use_neutron: When True resources are provisioned via neutron, when + False resources are provisioned via nova. + :returns: A dictionary with the same keys as the input + `validation_resources` and the resources for values in the format + they are returned by the API. + + Examples:: + + from tempest.common import validation_resources as vr + from tempest.lib import auth + from tempest.lib.services import clients + + creds = auth.get_credentials('http://mycloud/identity/v3', + username='me', project_name='me', + password='secret', domain_name='Default') + os = clients.ServiceClients(creds, 'http://mycloud/identity/v3') + # Request keypair and floating IP + resources = dict(keypair=True, security_group=False, + security_group_rules=False, floating_ip=True) + resources = vr.create_validation_resources( + os, validation_resources=resources, use_neutron=True, + floating_network_id='4240E68E-23DA-4C82-AC34-9FEFAA24521C') + + # Now cleanup the resources + try: + vr.clear_validation_resources(os, resources) + except Exception as e: + LOG.exception('Something went wrong during cleanup, ignoring') + """ has_exception = None if validation_data: if 'keypair' in validation_data: