summaryrefslogtreecommitdiffstats
path: root/docs/how-to-use
diff options
context:
space:
mode:
authorSteven Pisarski <s.pisarski@cablelabs.com>2017-02-17 16:57:08 +0000
committerGerrit Code Review <gerrit@opnfv.org>2017-02-17 16:57:08 +0000
commit7aaba119cdca72819108ea1e94a6a7fc0224e079 (patch)
treefbad6efcf69745ac524de9a08c3296743b988dcc /docs/how-to-use
parent906f2bd9f82de261b2871e7877b0694da4331091 (diff)
parentc5301a7a2e890fed97ffe04b40ccbe331e7f4a0b (diff)
Merge "Converted existing markdown documentation to RST format. Removed MD versions. Moved examples directory up one under repo root Moved RST files under docs/how-to-use"
Diffstat (limited to 'docs/how-to-use')
-rw-r--r--docs/how-to-use/APITests.rst261
-rw-r--r--docs/how-to-use/IntegrationTests.rst290
-rw-r--r--docs/how-to-use/Testing.rst44
-rw-r--r--docs/how-to-use/UnitTests.rst91
-rw-r--r--docs/how-to-use/VirtEnvDeploy.rst275
-rw-r--r--docs/how-to-use/index.rst26
6 files changed, 987 insertions, 0 deletions
diff --git a/docs/how-to-use/APITests.rst b/docs/how-to-use/APITests.rst
new file mode 100644
index 0000000..599325f
--- /dev/null
+++ b/docs/how-to-use/APITests.rst
@@ -0,0 +1,261 @@
+SNAPS OpenStack API Testing
+===========================
+
+Tests designated as component tests extend the snaps.openstack.tests.OSComponentTestCase class and must be exercised
+with OpenStack credentials for all as well as an external network for many. When leveraging the unit\_test\_suite.py
+application, the -e argument and -n arguments will suffice. When attempting to execute these tests within your IDE
+of choice (tested on IntelliJ), you will need to edit the [repo\_dir]/snaps/openstack/tests/conf/os\_env.yaml file as well
+as ensuring that your run configuration's working directory is set to [repo\_dir]/snaps.
+
+The Test Classes
+================
+
+glance_utils_tests.py - GlanceSmokeTests
+----------------------------------------
+
+Ensures that a Glance client can be obtained as well as the proper
+exceptions thrown with the wrong credentials.
+
+keystone_utils_tests.py - KeystoneSmokeTests
+--------------------------------------------
+
+Ensures that a Keystone client can be obtained as well as the proper
+exceptions thrown with the wrong credentials.
+
+neutron_utils_tests.py - NeutronSmokeTests
+------------------------------------------
+
+Ensures that a Neutron client can be obtained as well as the proper
+exceptions thrown with the wrong credentials.
+
+nova_utils_tests.py - NovaSmokeTests
+------------------------------------
+
+Ensures that a Nova client can be obtained as well as the proper
+exceptions thrown with the wrong credentials.
+
+keystone_utils_tests.py - KeystoneUtilsTests
+--------------------------------------------
+
++----------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Keystone API | Description |
++==================================+===============+===========================================================+
+| test_create_user_minimal | 2 & 3 | Tests the creation of a user with minimal configuration |
+| | | settings via the utility functions |
++----------------------------------+---------------+-----------------------------------------------------------+
+| test_create_project_minimal | 2 & 3 | Tests the creation of a project with minimal configuration|
+| | | settings via the utility functions |
++----------------------------------+---------------+-----------------------------------------------------------+
+
+create_user_tests.py - CreateUserSuccessTests
+---------------------------------------------
++----------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Keystone API | Description |
++==================================+===============+===========================================================+
+| test_create_user | 2 & 3 | Tests the creation of a user with minimal configuration |
+| | | settings via the utility functions |
++----------------------------------+---------------+-----------------------------------------------------------+
+
+create_project_tests.py - CreateProjectSuccessTests
+---------------------------------------------------
+
++----------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Keystone API | Description |
++==================================+===============+===========================================================+
+| test_create_user_minimal | 2 & 3 | Tests the creation of a user via the OpenStackUser class |
++----------------------------------+---------------+-----------------------------------------------------------+
+| test_create_user_2x | 2 & 3 | Tests the creation of a user a second time via the |
+| | | OpenStackUser class to ensure it is only created once |
++----------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_user | 2 & 3 | Tests the creation and deletion of a user via the |
+| | | OpenStackUser class to ensure that clean will not raise |
+| | | an exception |
++----------------------------------+---------------+-----------------------------------------------------------+
+
+create_project_tests.py - CreateProjectUserTests
+------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Keystone API | Description |
++=======================================+===============+===========================================================+
+| test_create_project_sec_grp_one_user | 2 & 3 | Tests the creation of an OpenStack object to a project |
+| | | with a new users and to create a security group |
+| | | |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_project_sec_grp_two_users | 2 & 3 | Tests the creation of an OpenStack object to a project |
+| | | with two new users and to create a security group under |
+| | | each |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+glance_utils_tests.py - GlanceUtilsTests
+------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Glance API | Description |
++=======================================+===============+===========================================================+
+| test_create_image_minimal_url | 1 | Tests the glance_utils.create_image() function with a URL |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_image_minimal_file | 1 | Tests the glance_utils.create_image() function with a file|
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+neutron_utils_tests.py - NeutronUtilsNetworkTests
+-------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Neutron API | Description |
++=======================================+===============+===========================================================+
+| test_create_network | 2 | Ensures neutron_utils.create_network() properly creates a |
+| | | network |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_network_empty_name | 2 | Ensures neutron_utils.create_network() raises an exception|
+| | | when the network name is an empty string |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_network_null_name | 2 | Ensures neutron_utils.create_network() raises an exception|
+| | | when the network name is None |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+neutron_utils_tests.py - NeutronUtilsSubnetTests
+------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Neutron API | Description |
++=======================================+===============+===========================================================+
+| test_create_subnet | 2 | Ensures neutron_utils.create_subnet() can properly create |
+| | | an OpenStack subnet object |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_subnet_null_name | 2 | Ensures neutron_utils.create_subnet() raises an exception |
+| | | when the subnet name is None |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_subnet_empty_name | 2 | Ensures neutron_utils.create_subnet() raises an exception |
+| | | when the subnet name is an empty string |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_subnet_null_cidr | 2 | Ensures neutron_utils.create_subnet() raises an exception |
+| | | when the subnet CIDR is None |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_subnet_empty_cidr | 2 | Ensures neutron_utils.create_subnet() raises an exception |
+| | | when the subnet CIDR is an empty string |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+neutron_utils_tests.py - NeutronUtilsRouterTests
+------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Neutron API | Description |
++=======================================+===============+===========================================================+
+| test_create_router_simple | 2 | Ensures neutron_utils.create_router() can properly create |
+| | | a simple OpenStack router object |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_with_public_inter | 2 | Ensures neutron_utils.create_router() can properly create |
+| face | | an OpenStack router object with an interface to the |
+| | | external network |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_empty_name | 2 | Ensures neutron_utils.create_router() raises an exception |
+| | | when the name is an empty string |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_null_name | 2 | Ensures neutron_utils.create_router() raises an exception |
+| | | when the name is None |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_add_interface_router | 2 | Ensures neutron_utils.add_interface_router() properly adds|
+| | | an interface to another subnet |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_add_interface_router_null_router | 2 | Ensures neutron_utils.add_interface_router() raises an |
+| | | exception when the router object is None |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_add_interface_router_null_subnet | 2 | Ensures neutron_utils.add_interface_router() raises an |
+| | | exception when the subnet object is None |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_port | 2 | Ensures neutron_utils.create_port() can properly create an|
+| | | OpenStack port object |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_port_empty_name | 2 | Ensures neutron_utils.create_port() raises an exception |
+| | | when the port name is an empty string |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_port_null_name | 2 | Ensures neutron_utils.create_port() raises an exception |
+| | | when the port name is None |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_port_null_network_object | 2 | Ensures neutron_utils.create_port() raises an exception |
+| | | when the network object is None |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_port_null_ip | 2 | Ensures neutron_utils.create_port() raises an exception |
+| | | when the assigned IP value is None |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_port_invalid_ip | 2 | Ensures neutron_utils.create_port() raises an exception |
+| | | when the assigned IP value is invalid |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_port_invalid_ip_to_subnet | 2 | Ensures neutron_utils.create_port() raises an exception |
+| | | when the assigned IP value is not part of CIDR |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+neutron_utils_tests.py - NeutronUtilsSecurityGroupTests
+-------------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Neutron API | Description |
++=======================================+===============+===========================================================+
+| test_create_delete_simple_sec_grp | 2 | Ensures that a security group can be created |
+| | | (neutron_utils.create_security_group() and deleted via |
+| | | neutron_utils.delete_security_group() |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_sec_grp_no_name | 2 | Ensures that neutron_utils.create_security_group() raises |
+| | | an exception when attempting to create a security group |
+| | | without a name |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_sec_grp_no_rules | 2 | Ensures that neutron_utils.create_security_group() can |
+| | | create a security group without any rules |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_sec_grp_one_rule | 2 | Ensures that neutron_utils.create_security_group_rule() |
+| | | can add a rule to a security group |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+nova_utils_tests.py - NovaUtilsKeypairTests
+-------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Nova API | Description |
++=======================================+===============+===========================================================+
+| test_create_keypair | 2 | Ensures that a keypair can be properly created via |
+| | | nova_utils.upload_keypair() with a public_key object |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_keypair | 2 | Ensures that a keypair can be properly deleted via |
+| | | nova_utils.delete_keypair() |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_key_from_file | 2 | Ensures that a keypair can be properly created via |
+| | | nova_utils.upload_keypair_file() |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_floating_ips | 2 | Ensures that a floating IP can be properly created via |
+| | | nova_utils.create_floating_ip() [note: this test should |
+| | | be moved to a new class] |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+nova_utils_tests.py - NovaUtilsFlavorTests
+------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Nova API | Description |
++=======================================+===============+===========================================================+
+| test_create_flavor | 2 | Ensures that a flavor can be properly created via |
+| | | nova_utils.create_flavor() |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_flavor | 2 | Ensures that a flavor can be properly deleted via |
+| | | nova_utils.delete_flavor() |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_flavor_tests.py - CreateFlavorTests
+------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Nova API | Description |
++=======================================+===============+===========================================================+
+| test_create_flavor | 2 | Ensures that the OpenStackFlavor class's create() method |
+| | | creates an OpenStack flavor object |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_flavor_existing | 2 | Ensures that the OpenStackFlavor class's create() will not|
+| | | create a flavor with the same name more than once |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_clean_flavor | 2 | Ensures that the OpenStackFlavor class's clean() method |
+| | | will delete the flavor object |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_flavor | 2 | Ensures that the OpenStackFlavor class's clean() method |
+| | | will not raise an exception when called and the object no |
+| | | longer exists |
++---------------------------------------+---------------+-----------------------------------------------------------+
diff --git a/docs/how-to-use/IntegrationTests.rst b/docs/how-to-use/IntegrationTests.rst
new file mode 100644
index 0000000..983c165
--- /dev/null
+++ b/docs/how-to-use/IntegrationTests.rst
@@ -0,0 +1,290 @@
+SNAPS OpenStack Integration Testing
+===================================
+
+These tests are ones designed to be run within their own dynamically created project along with a newly generated user
+account and generally require other OpenStack object creators.
+
+The Test Classes
+================
+
+create_security_group_tests.py - CreateSecurityGroupTests
+---------------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | API Versions | Description |
++=======================================+===============+===========================================================+
+| test_create_group_without_rules | Keysone 2 & 3 | Ensures the OpenStackSecurityGroup class can create a |
+| | Neutron 2 | security group without any rules |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_group | Keysone 2 & 3 | Ensures the OpenStackSecurityGroup class clean() method |
+| | Neutron 2 | will not raise an exception should the group be deleted by|
+| | | some other process |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_group_with_one_simple_rule| Keysone 2 & 3 | Ensures the OpenStackSecurityGroup class can create a |
+| | Neutron 2 | security group with a single rule |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_group_with_several_rules | Keysone 2 & 3 | Ensures the OpenStackSecurityGroup class can create a |
+| | Neutron 2 | security group with several rules |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_add_rule | Keysone 2 & 3 | Ensures the OpenStackSecurityGroup#add_rule() method |
+| | Neutron 2 | properly creates and associates the new rule |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_remove_rule_by_id | Keysone 2 & 3 | Ensures the OpenStackSecurityGroup#remove_rule() method |
+| | Neutron 2 | properly deletes and disassociates the old rule via its ID|
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_remove_rule_by_setting | Keysone 2 & 3 | Ensures the OpenStackSecurityGroup#remove_rule() method |
+| | Neutron 2 | properly deletes and disassociates the old rule via its |
+| | | setting object |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_image_tests.py - CreateImageSuccessTests
+-----------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Glance API | Description |
++=======================================+===============+===========================================================+
+| test_create_image_clean_url | 1 | Ensures the OpenStackImage class can create an image from |
+| | | a download URL location |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_image_clean_file | 1 | Ensures the OpenStackImage class can create an image from |
+| | | a locally sourced image file |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_image | 1 | Ensures the OpenStackImage.clean() method deletes an image|
+| | | and does not raise an exception on subsequent calls to the|
+| | | clean() method |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_same_image | 1 | Ensures the OpenStackImage.create() method does not create|
+| | | another image when one already exists with the same name |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_image_tests.py - CreateImageNegativeTests
+------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Glance API | Description |
++=======================================+===============+===========================================================+
+| test_none_image_name | 1 | Ensures OpenStackImage.create() results in an Exception |
+| | | being raised when the ImageSettings.name attribute has |
+| | | not been set |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_bad_image_url | 1 | Ensures OpenStackImage.create() results in an Exception |
+| | | being raised when the download URL is invalid |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_bad_image_file | 1 | Ensures OpenStackImage.create() results in an Exception |
+| | | being raised when the image file does not exist |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_none_proj_name | 1 | Ensures OpenStackImage.create() results in an Exception |
+| | | being raised when the credentials project name is None |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_none_auth_url | 1 | Ensures OpenStackImage.create() results in an Exception |
+| | | being raised when the credentials URL is None |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_none_password | 1 | Ensures OpenStackImage.create() results in an Exception |
+| | | being raised when the credentials password is None |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_none_user | 1 | Ensures OpenStackImage.create() results in an Exception |
+| | | being raised when the credentials user is None |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_keypairs_tests.py - CreateKeypairsTests
+----------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Nova API | Description |
++=======================================+===============+===========================================================+
+| test_create_keypair_only | 2 | Ensures that a keypair object can be created simply by |
+| | | only configuring a name |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_keypair | 2 | Ensures that a keypair object is deleted via |
+| | | OpenStackKeypair.clean() and subsequent calls do not |
+| | | result in exceptions |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_keypair_save_pub_only | 2 | Ensures that a keypair object can be created when the only|
+| | | the public key is cached to disk |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_keypair_save_both | 2 | Ensures that a keypair object can be created when both the|
+| | | public and private keys are cached to disk |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_keypair_from_file | 2 | Ensures that a keypair object can be created with an |
+| | | existing public key file |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_network_tests.py - CreateNetworkSuccessTests
+---------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Neutron API | Description |
++=======================================+===============+===========================================================+
+| test_create_network_without_router | 2 | Ensures that a network can be created via the |
+| | | OpenStackNetwork class without any routers |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_network | 2 | Ensures that a router can be deleted via the |
+| | | OpenStackNetwork.clean() method |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_network_with_router | 2 | Ensures that a network can be created via the |
+| | | OpenStackNetwork class with a router |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_networks_same_name | 2 | Ensures that the OpenStackNetwork.create() method will not|
+| | | create a network with the same name |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_router_tests.py - CreateRouterSuccessTests
+-------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Neutron API | Description |
++=======================================+===============+===========================================================+
+| test_create_router_vanilla | 2 | Ensures that a router can be created via the |
+| | | OpenStackRouter class with minimal settings |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_router | 2 | Ensures that a router can be deleted via the |
+| | | OpenStackRouter.clean() method |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_admin_state_false | 2 | Ensures that a router can created with |
+| | | admin_state_up = False |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_admin_state_True | 2 | Ensures that a router can created with |
+| | | admin_state_up = True |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_private_network | 2 | Ensures that a router port can be created against a |
+| | | private network |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_external_network | 2 | Ensures that a router can be created that is connected to |
+| | | both external and private internal networks |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_router_tests.py - CreateRouterNegativeTests
+--------------------------------------------------
+
++----------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | Neutron API | Description |
++========================================+===============+===========================================================+
+| test_create_router_noname | 2 | Ensures that an exception is raised when attempting to |
+| | | create a router without a name |
++----------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_invalid_gateway_name| 2 | Ensures that an exception is raised when attempting to |
+| | | create a router to an external network that does not exist|
++----------------------------------------+---------------+-----------------------------------------------------------+
+
+create_instance_tests.py - CreateInstanceSimpleTests
+----------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | API Versions | Description |
++=======================================+===============+===========================================================+
+| test_create_delete_instance | Nova 2 | Ensures that the OpenStackVmInstance.clean() method |
+| | Neutron 2 | deletes the instance |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_instance_tests.py - SimpleHealthCheck
+--------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | API Versions | Description |
++=======================================+===============+===========================================================+
+| test_check_vm_ip_dhcp | Nova 2 | Tests the creation of an OpenStack instance with a single |
+| | Neutron 2 | port and it's assigned IP address |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_instance_tests.py - CreateInstanceSingleNetworkTests
+-----------------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | API Versions | Description |
++=======================================+===============+===========================================================+
+| test_single_port_static | Nova 2 | Ensures that an instance with a single port/NIC with a |
+| | Neutron 2 | static IP can be created |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_ssh_client_fip_before_active | Nova 2 | Ensures that an instance can be reached over SSH when the |
+| | Neutron 2 | floating IP is assigned prior to the VM becoming ACTIVE |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_ssh_client_fip_after_active | Nova 2 | Ensures that an instance can be reached over SSH when the |
+| | Neutron 2 | floating IP is assigned after to the VM becoming ACTIVE |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_instance_tests.py - CreateInstancePortManipulationTests
+--------------------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | API Versions | Description |
++=======================================+===============+===========================================================+
+| test_set_custom_valid_ip_one_subnet | Nova 2 | Ensures that an instance's can have a valid static IP is |
+| | Neutron 2 | properly assigned |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_set_custom_invalid_ip_one_subnet | Nova 2 | Ensures that an instance's port with an invalid static IP |
+| | Neutron 2 | raises an exception |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_set_custom_valid_mac | Nova 2 | Ensures that an instance's port can have a valid MAC |
+| | Neutron 2 | address properly assigned |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_set_custom_invalid_mac | Nova 2 | Ensures that an instance's port with an invalid MAC |
+| | Neutron 2 | address raises and exception |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_set_custom_mac_and_ip | Nova 2 | Ensures that an instance's port with a valid static IP and|
+| | Neutron 2 | MAC are properly assigned |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_set_allowed_address_pairs | Nova 2 | Ensures the configured allowed_address_pairs is properly |
+| | Neutron 2 | set on a VMs port |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_set_allowed_address_pairs_bad_mac| Nova 2 | Ensures the port cannot be created when a bad MAC address |
+| | Neutron 2 | format is used in the allowed_address_pairs port attribute|
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_set_allowed_address_pairs_bad_ip | Nova 2 | Ensures the port cannot be created when a bad IP address |
+| | Neutron 2 | format is used in the allowed_address_pairs port attribute|
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_instance_tests.py - CreateInstanceOnComputeHost
+------------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | API Versions | Description |
++=======================================+===============+===========================================================+
+| test_deploy_vm_to_each_compute_node | Nova 2 | Tests to ensure that one can fire up an instance on each |
+| | Neutron 2 | active compute node |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_instance_tests.py - CreateInstancePubPrivNetTests
+--------------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | API Versions | Description |
++=======================================+===============+===========================================================+
+| test_dual_ports_dhcp | Nova 2 | Ensures that a VM with two ports/NICs can have its second |
+| | Neutron 2 | NIC configured via SSH/Ansible after startup |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_instance_tests.py - InstanceSecurityGroupTests
+-----------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | API Versions | Description |
++=======================================+===============+===========================================================+
+| test_add_security_group | Nova 2 | Ensures that a VM instance can have security group added |
+| | Neutron 2 | to it while its running |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_add_invalid_security_group | Nova 2 | Ensures that a VM instance does not accept the addition of|
+| | Neutron 2 | a security group that no longer exists |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_remove_security_group | Nova 2 | Ensures that a VM instance accepts the removal of a |
+| | Neutron 2 | security group |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_remove_security_group_never_added| Nova 2 | Ensures that a VM instance does not accept the removal of |
+| | Neutron 2 | a security group that was never added in the first place |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_add_same_security_group | Nova 2 | Ensures that a VM instance does not add a security group |
+| | Neutron 2 | that has already been added to the instance |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+ansible_utils_tests.py - AnsibleProvisioningTests
+-------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name | API Versions | Description |
++=======================================+===============+===========================================================+
+| test_apply_simple_playbook | Nova 2 | Ensures that an instance assigned with a floating IP will |
+| | Neutron 2 | apply a simple Ansible playbook |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_apply_template_playbook | Nova 2 | Ensures that an instance assigned with a floating IP will |
+| | Neutron 2 | apply a Ansible playbook containing Jinga2 substitution |
+| | | values |
++---------------------------------------+---------------+-----------------------------------------------------------+
diff --git a/docs/how-to-use/Testing.rst b/docs/how-to-use/Testing.rst
new file mode 100644
index 0000000..586974a
--- /dev/null
+++ b/docs/how-to-use/Testing.rst
@@ -0,0 +1,44 @@
+Running Unit Test Suite
+=======================
+
+These tests are written in Python and require an that it is setup before running the tests.
+See `install directions <index.md>`__ for Python installation instructions.
+
+Start by cloning the snaps-provisioning repository
+--------------------------------------------------
+
+``git clone https://gerrit.cablelabs.com/snaps-provisioning``
+
+Install Library
+---------------
+
+``pip install -e <path to repo>/``
+
+Execute the tests
+-----------------
+
+| ``cd <path to repo> python snaps/unit_test_suite.py -e [path to RC file] -n [external network name]``
+| \* All Supported Arguments
+| \* -e [required - The path to the OpenStack RC file]
+| \* -n [required - The name of the external network to use for routers
+ and floating IPs]
+| \* -p [optional - the proxy settings if required. Format :
+| \* -s [optional - the proxy command used for SSH connections]
+| \* -l [(default INFO) The log level]
+| \* -k [optional - When set, tests project and user creation. Use only
+ if host running tests has access to the cloud's admin network]
+| \* -f [optional - When set, will not execute tests requiring Floating
+ IPS]
+| \* -u [optional - When set, the unit tests will be executed]
+
+Test descriptions
+=================
+
+`Unit Testing <UnitTests.rst>`__ - Tests that do not require a connection to OpenStack
+--------------------------------------------------------------------------------------
+
+`OpenStack API Tests <APITests.rst>`__ - Tests many individual OpenStack API calls
+----------------------------------------------------------------------------------
+
+`Integration Tests <IntegrationTests.rst>`__ - Tests OpenStack object creation in a context. These tests will be run within a custom project as a specific user.
+----------------------------------------------------------------------------------------------------------------------------------------------------------------
diff --git a/docs/how-to-use/UnitTests.rst b/docs/how-to-use/UnitTests.rst
new file mode 100644
index 0000000..efd6426
--- /dev/null
+++ b/docs/how-to-use/UnitTests.rst
@@ -0,0 +1,91 @@
+SNAPS Unit Testing
+==================
+
+| Tests designated as Unit tests extend the unittest.TestCase class and
+ can be exercised without any external resources
+| other than the filesystem. Most of these tests simply ensure that the
+ configuration settings classes check their
+| constructor arguments properly.
+
+The Test Classes
+================
+
+FileUtilsTests
+--------------
+
+- testFileIsDirectory - ensures that the expected path is a directory
+- testFileNotExist - ensures that a file that does not exist returns
+ False
+- testFileExists - ensures that a file that does exist returns True
+- testDownloadBadUrl - ensures that an Exception is thrown when
+ attempting to download a file with a bad URL
+- testCirrosImageDownload - ensures that the Cirros image can be
+ downloaded
+- testReadOSEnvFile - ensures that an OpenStack RC file can be properly
+ parsed
+
+SecurityGroupRuleSettingsUnitTests
+----------------------------------
+
+Ensures that all required members are included when constructing a
+SecurityGroupRuleSettings object
+
+SecurityGroupSettingsUnitTests
+------------------------------
+
+Ensures that all required members are included when constructing a
+SecuirtyGroupSettings object
+
+ImageSettingsUnitTests
+----------------------
+
+Ensures that all required members are included when constructing a
+ImageSettings object
+
+KeypairSettingsUnitTests
+------------------------
+
+Ensures that all required members are included when constructing a
+KeypairSettings object
+
+UserSettingsUnitTests
+---------------------
+
+Ensures that all required members are included when constructing a
+UserSettings object
+
+ProjectSettingsUnitTests
+------------------------
+
+Ensures that all required members are included when constructing a
+ProjectSettings object
+
+NetworkSettingsUnitTests
+------------------------
+
+Ensures that all required members are included when constructing a
+NetworkSettings object
+
+SubnetSettingsUnitTests
+-----------------------
+
+Ensures that all required members are included when constructing a
+SubnetSettings object
+
+PortSettingsUnitTests
+---------------------
+
+Ensures that all required members are included when constructing a
+PortSettings object
+
+FloatingIpSettingsUnitTests
+---------------------------
+
+Ensures that all required members are included when constructing a
+FloatingIpSettings object
+
+VmInstanceSettingsUnitTests
+---------------------------
+
+Ensures that all required members are included when constructing a
+VmInstanceSettings object
diff --git a/docs/how-to-use/VirtEnvDeploy.rst b/docs/how-to-use/VirtEnvDeploy.rst
new file mode 100644
index 0000000..7f55f0c
--- /dev/null
+++ b/docs/how-to-use/VirtEnvDeploy.rst
@@ -0,0 +1,275 @@
+Overview
+========
+
+The main purpose of this project is to enable one to describe a virtual environment in a YAML file and enable the
+user to deploy it to an OpenStack cloud in a repeatable manner. There are also options to un-deploy that same
+environment by leveraging the original YAML file.
+
+To deploy/clean virtual environments
+====================================
+
+- Clone Repository
+
+ - git clone https://gerrit.cablelabs.com/snaps-provisioning
+
+- Install Library
+
+ - pip install -e /
+
+- Deploy
+
+ - cd
+ - python snaps/deploy\_venv.py -e -d
+ - Working example:
+
+::
+
+ python deploy_venv.py -e <path to repo>/examples/complex-network/deploy-complex-network.yaml -d
+
+- Clean
+
+ - python deploy\_venv.py -e -c
+ - Working example (cleanup of a previously deployed virtual
+ environment where the VM has Yardstick installed):
+
+::
+
+ python deploy_venv.py -e <path to repo>/examples/complex-network/deploy-complex-network.yaml -c
+
+Environment Configuration YAML File
+===================================
+
+The configuration file used to deploy and provision a virtual environment has been designed to describe the required
+images, networks, SSH public and private keys, associated VMs, as well as any required post deployment provisioning
+tasks.
+
+\*\*\* Please note that many of the more esoteric optional supported
+attributes still have not been fully tested. ***
+*** Some of the nested bullets are being hidden by GitLabs, please see
+doc/VirtEnvDeploy.md.\*\*\*
+
+- openstack: the top level tag that denotes configuration for the
+ OpenStack components
+
+ - connection: - contains the credentials and endpoints required to
+ connect with OpenStack
+ - username: - the project's user (required)
+ - password: - the tentant's user password (required)
+ - auth\_url: - the URL to the OpenStack APIs (required)
+ - project\_name: - the name of the OpenStack project for the user
+ (required)
+ - http\_proxy: - the {{ host }}:{{ port }} of the proxy server the
+ HTTPPhotoman01(optional)
+ - images: - describes each image
+ - image:
+
+ - name: The unique image name. If the name already exists for
+ your project, a new one will not be created (required)
+ - format: The format type of the image i.e. qcow2 (required)
+ - download\_url: The HTTP download location of the image file
+ (required)
+ - nic\_config\_pb\_loc: The file location relative to the CWD
+ (python directory) to the Ansible Playbook used to configure
+ VMs with more than one port. VMs get their first NIC configured
+ for free while subsequent ones are not. This value/script will
+ only be leveraged when necessary. Centos has been supported
+ with
+ "provisioning/ansible/centos-network-setup/configure\_host.yml".
+
+ - networks:
+ - network:
+
+ - name: The name of the network to be created. If one already
+ exists, a new one will not be created (required)
+ - admin\_state\_up: T\|F (default True)
+ - shared: (optional)
+ - project\_name: Name of the project who owns the network. Note:
+ only administrative users can specify projects other than their
+ own (optional)
+ - external: T\|F whether or not network is external (default
+ False)
+ - network\_type: The type of network to create. (optional)
+ - subnets:
+ - subnet:
+
+ - name: The name of the network to be created. If one already
+ exists, a new one will not be created. Note: although
+ OpenStack allows for multiple subnets to be applied to any
+ given network, we have not included support as our current
+ use cases does not utilize this functionality (required)
+ - cidr: The subnet mask value (required)
+ - dns\_nameservers: A list of IP values used for DNS
+ resolution (default: 8.8.8.8)
+ - ip\_version: 4\|6 (default: 4)
+ - project\_name: Name of the project who owns the network.
+ Note: only administrative users can specify projects other
+ than their own (optional)
+ - start: The start address for allocation\_pools (optional)
+ - end: The ending address for allocation\_pools (optional)
+ - gateway\_ip: The IP address to the gateway (optional)
+ - enable\_dhcp: T\|F (optional)
+ - dns\_nameservers: List of DNS server IPs
+ - host\_routes: A list of host route dictionaries (optional)
+ i.e.:
+ ``yaml "host_routes":[ { "destination":"0.0.0.0/0", "nexthop":"123.456.78.9" }, { "destination":"192.168.0.0/24", "nexthop":"192.168.0.1" } ]``
+ - destination: The destination for a static route (optional)
+ - nexthop: The next hop for the destination (optional)
+ - ipv6\_ra\_mode: Valid values: "dhcpv6-stateful",
+ "dhcpv6-stateless", and "slaac" (optional)
+ - ipv6\_address\_mode: Valid values: "dhcpv6-stateful",
+ "dhcpv6-stateless", and "slaac" (optional)
+
+ - routers:
+
+ - router:
+ - name: The name of the router to be created. If one already
+ exists, a new one will not be created (required)
+ - project\_name: Name of the project who owns the network. Note:
+ only administrative users can specify projects other than their
+ own (optional)
+ - internal\_subnets: A list of subnet names on which the router
+ will be placed (optional)
+ - external\_gateway: A dictionary containing the external gateway
+ parameters: "network\_id", "enable\_snat",
+ "external\_fixed\_ips" (optional)
+ - interfaces: A list of port interfaces to create to other
+ subnets (optional)
+
+ - port (Leverages the same class/structure as port objects on
+ VM instances. See port definition below for a
+ full accounting of the port attributes. The ones listed
+ below are generally used for routers)
+
+ - name: The name given to the new port (must be unique for
+ project) (required)
+ - network\_name: The name of the new port's network
+ (required)
+ - ip\_addrs: A list of k/v pairs (optional)
+ - subnet\_name: the name of a subnet that is on the port's
+ network
+ - ip: An IP address of the associated subnet to assign to
+ the new port (optional but generally required for router
+ interfaces)
+
+ - keypairs:
+
+ - keypair:
+ - name: The name of the keypair to be created. If one already
+ exists, a new one will not be created but simply loaded from
+ its configured file location (required)
+ - public\_filepath: The path to where the generated public key
+ will be stored if it does not exist (optional but really
+ required for provisioning purposes)
+ - private\_filepath: The path to where the generated private key
+ will be stored if it does not exist (optional but really
+ required for provisioning purposes)
+
+ - instances:
+
+ - instance:
+ - name: The unique instance name for project. (required)
+ - flavor: Must be one of the preconfigured flavors (required)
+ - imageName: The name of the image to be used for deployment
+ (required)
+ - keypair\_name: The name of the keypair to attach to instance
+ (optional but required for NIC configuration and Ansible
+ provisioning)
+ - sudo\_user: The name of a sudo\_user that is attached to the
+ keypair (optional but required for NIC configuration and
+ Ansible provisioning)
+ - vm\_boot\_timeout: The number of seconds to block waiting for
+ an instance to deploy and boot (default 900)
+ - vm\_delete\_timeout: The number of seconds to block waiting for
+ an instance to be deleted (default 300)
+ - ssh\_connect\_timeout: The number of seconds to block waiting
+ for an instance to achieve an SSH connection (default 120)
+ - ports: A list of port configurations (should contain at least
+ one)
+ - port: Denotes the configuration of a NIC
+
+ - name: The unique port name for project (required)
+ - network\_name: The name of the network to which the port is
+ attached (required)
+ - ip\_addrs: Static IP addresses to be added to the port by
+ subnet (optional)
+ - subnet\_name: The name of the subnet
+ - ip: The assigned IP address (when null, OpenStack will
+ assign an IP to the port)
+ - admin\_state\_up: T\|F (default True)
+ - project\_name: The name of the project who owns the network.
+ Only administrative users can specify a the project ID other
+ than their own (optional)
+ - mac\_address: The desired MAC for the port (optional)
+ - fixed\_ips: A dictionary that allows one to specify only a
+ subnet ID, OpenStack Networking allocates an available IP
+ from that subnet to the port. If you specify both a subnet
+ ID and an IP address, OpenStack Networking tries to allocate
+ the specified address to the port. (optional)
+ - seurity\_groups: A list of security group IDs (optional)
+ - allowed\_address\_pairs: A dictionary containing a set of
+ zero or more allowed address pairs. An address pair contains
+ an IP address and MAC address. (optional)
+ - opt\_value: The extra DHCP option value (optional)
+ - opt\_name: The extra DHCP option name (optional)
+ - device\_owner: The ID of the entity that uses this port. For
+ example, a DHCP agent (optional)
+ - device\_id: The ID of the device that uses this port. For
+ example, a virtual server (optional)
+
+ - floating\_ips: list of floating\_ip configurations (optional)
+
+ - floating\_ip:
+ - name: Must be unique for VM instance (required)
+ - port\_name: The name of the port requiring access to the
+ external network (required)
+ - subnet\_name: The name of the subnet contains the IP address on
+ the port on which to create the floating IP (optional)
+ - router\_name: The name of the router connected to an external
+ network used to attach the floating IP (required)
+ - provisioning: (True\|False) Denotes whether or not this IP can
+ be used for Ansible provisioning (default True)
+
+- ansible: Each set of attributes below are contained in a list
+
+ - playbook\_location: Full path or relative to the directory in
+ which the deployment file resides (required)
+ - hosts: A list of hosts to which the playbook will be executed
+ (required)
+ - variables: Should your Ansible scripts require any substitution
+ values to be applied with Jinga2templates, the values defined here
+ will be used to for substitution
+ - tag name = substitution variable names. For instance, for any file
+ being pushed to the host being provisioned containing a value such
+ as {{ foo }}, you must specify a tag name of "foo"
+
+ - vm\_name:
+ - type: string\|port\|os\_creds\|vm-attr (note: will need to make
+ changes to deploy\_venv.py#\_\_get\_variable\_value() for
+ additional support)
+ - when type == string, an tag name "value" must exist and its
+ value will be used for template substituion
+ - when type == port, custom code has been written to extract
+ certain assigned values to the port:
+
+ - vm\_name: must correspond to a VM's name as configured in
+ this file
+ - port\_name: The name of the port from which to extract the
+ substitution values (required)
+ - port\_value: The port value. Currently only supporting
+ "mac\_address" and "ip\_address" (only the first)
+
+ - when type == os\_creds, custom code has been written to extract
+ the file's connection values:
+
+ - username: connection's user
+ - password: connection's password
+ - auth\_url: connection's URL
+ - project\_name: connection's project
+
+ - when type == vm-attr, custom code has been written to extract
+ the following attributes from the vm:
+
+ - vm\_name: must correspond to a VM's name as configured in
+ this file
+ - value -> floating\_ip: is currently the only vm-attr
+ supported
diff --git a/docs/how-to-use/index.rst b/docs/how-to-use/index.rst
new file mode 100644
index 0000000..58b67a3
--- /dev/null
+++ b/docs/how-to-use/index.rst
@@ -0,0 +1,26 @@
+*************************
+Runtime Environment Setup
+*************************
+
+- Python 2.7 (recommend leveraging a Virtual Python runtime, e.g.
+ `Virtualenv <https://virtualenv.pypa.io>`__, in your development
+ environment)
+- Development packages for python and openssl. On CentOS/RHEL:
+
+ # yum install python-devel openssl-devel
+
+On Ubuntu:
+
+::
+
+ # apt-get install python2.7-dev libssl-dev
+
+- Install SNAPS Library
+
+ - pip install -e <path to repo>/snaps/
+
+`Testing <Testing.rst>`__
+-------------------------
+
+`Virtual Environment Deployment <VirtEnvDeploy.rst>`__
+------------------------------------------------------