diff options
| author |   spisarski <s.pisarski@cablelabs.com> | 2017-10-26 12:19:42 -0600 |
|---|---|---|
| committer | spisarski <s.pisarski@cablelabs.com> | 2017-10-26 12:19:42 -0600 |
| commit | b5822ef2be374cd6bf53a60a84f1c8449a90b35a (patch) | |
| tree | 8ce484f5777b38ab0de7582655809f2c6bdf18e4 /docs/how-to-use | |
| parent | 65d02af9035034b504c4e3588d30fcda68182e36 (diff) | |
Updated documentation to reflect new block storage support.
1. Updated library usaged LibraryUsage.rst
2. Added new unit tests to UnitTests.rst
3. Added new component tests to APITests.rst
4. Added new integration tests to IntegrationTests.rst
5. Updated application usage docs in VirtEnvDeploy.rst
6. Updated pydocs where inaccurate
JIRA: SNAPS-203
Change-Id: I8bee2c6cdb5f54b86abf805bc930563028df3425
Signed-off-by: spisarski <s.pisarski@cablelabs.com>
Diffstat (limited to 'docs/how-to-use')
| -rw-r--r-- | docs/how-to-use/APITests.rst | 105 | ||||
| -rw-r--r-- | docs/how-to-use/IntegrationTests.rst | 140 | ||||
| -rw-r--r-- | docs/how-to-use/LibraryUsage.rst | 184 | ||||
| -rw-r--r-- | docs/how-to-use/UnitTests.rst | 48 | ||||
| -rw-r--r-- | docs/how-to-use/VirtEnvDeploy.rst | 467 |
5 files changed, 760 insertions, 184 deletions
diff --git a/docs/how-to-use/APITests.rst b/docs/how-to-use/APITests.rst index 4a8035a..3ac272b 100644 --- a/docs/how-to-use/APITests.rst +++ b/docs/how-to-use/APITests.rst @@ -34,6 +34,12 @@ nova_utils_tests.py - NovaSmokeTests Ensures that a Nova client can be obtained as well as the proper exceptions thrown with the wrong credentials. +cinder_utils_tests.py - CinderSmokeTests +---------------------------------------- + +Ensures that a Cinder client can be obtained as well as the proper +exceptions thrown with the wrong credentials. + heat_utils_tests.py - HeatSmokeTests ------------------------------------ @@ -256,6 +262,95 @@ neutron_utils_tests.py - NeutronUtilsFloatingIpTests | test_floating_ips | 2 | Ensures that a floating IP can be created | +---------------------------------------+---------------+-----------------------------------------------------------+ +cinder_utils_tests.py - CinderUtilsQoSTests +------------------------------------------- + ++---------------------------------------+---------------+-----------------------------------------------------------+ +| Test Name | Cinder API | Description | ++=======================================+===============+===========================================================+ +| test_create_qos_both | 2 & 3 | Ensures that a QoS Spec can be created with a Consumer | +| | | value of 'both' | ++---------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_qos_front | 2 & 3 | Ensures that a QoS Spec can be created with a Consumer | +| | | value of 'front-end' | ++---------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_qos_back | 2 & 3 | Ensures that a QoS Spec can be created with a Consumer | +| | | value of 'back-end' | ++---------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_delete_qos | 2 & 3 | Ensures that a QoS Spec can be created and deleted | ++---------------------------------------+---------------+-----------------------------------------------------------+ + +cinder_utils_tests.py - CinderUtilsSimpleVolumeTypeTests +-------------------------------------------------------- + ++---------------------------------------+---------------+-----------------------------------------------------------+ +| Test Name | Cinder API | Description | ++=======================================+===============+===========================================================+ +| test_create_simple_volume_type | 2 & 3 | Tests the creation of a simple volume type with the | +| | | function cinder_utils#create_volume_type() | ++---------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_delete_volume_type | 2 & 3 | Tests the creation of a simple volume type with the | +| | | function cinder_utils#create_volume_type() then deletes | +| | | with the function cinder_utils#delete_volume_type() | ++---------------------------------------+---------------+-----------------------------------------------------------+ + +cinder_utils_tests.py - CinderUtilsAddEncryptionTests +----------------------------------------------------- + ++---------------------------------------+---------------+-----------------------------------------------------------+ +| Test Name | Cinder API | Description | ++=======================================+===============+===========================================================+ +| test_create_simple_encryption | 2 & 3 | Tests the creation of a simple volume type encryption | +| | | with the function cinder_utils#create_volume_encryption() | ++---------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_delete_encryption | 2 & 3 | Tests the creation of a simple volume type encryption | +| | | with the function cinder_utils#create_volume_encryption() | +| | | then deletes with the function | +| | | cinder_utils#delete_volume_type_encryption() | ++---------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_with_all_attrs | 2 & 3 | Tests the creation of a simple volume type encryption | +| | | with the function cinder_utils#create_volume_encryption() | +| | | where all configuration attributes have been set | ++---------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_bad_key_size | 2 & 3 | Tests to ensure that the function | +| | | cinder_utils#create_volume_encryption() raises a | +| | | BadRequest exception when the key_size attribute is -1 | ++---------------------------------------+---------------+-----------------------------------------------------------+ + +cinder_utils_tests.py - CinderUtilsVolumeTypeCompleteTests +---------------------------------------------------------- + ++---------------------------------------+---------------+-----------------------------------------------------------+ +| Test Name | Cinder API | Description | ++=======================================+===============+===========================================================+ +| test_create_with_encryption | 2 & 3 | Tests the creation of a volume type with encryption | +| | | with the function cinder_utils#create_volume_type() | ++---------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_with_qos | 2 & 3 | Tests the creation of a volume type with a QoS Spec | +| | | with the function cinder_utils#create_volume_type() | ++---------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_with_invalid_qos | 2 & 3 | Tests the creation of a volume type with an invalid QoS | +| | | Spec with the function cinder_utils#create_volume_type() | ++---------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_with_qos_and_encryption | 2 & 3 | Tests the creation of a volume type with a QoS Spec and | +| | | encryption with the function | +| | | cinder_utils#create_volume_type() | ++---------------------------------------+---------------+-----------------------------------------------------------+ + +cinder_utils_tests.py - CinderUtilsVolumeTests +---------------------------------------------- + ++---------------------------------------+---------------+-----------------------------------------------------------+ +| Test Name | Cinder API | Description | ++=======================================+===============+===========================================================+ +| test_create_simple_volume | 2 & 3 | Tests the creation of a simple volume with the function | +| | | cinder_utils#create_volume() | ++---------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_delete_volume | 2 & 3 | Tests the creation of a volume with the function | +| | | cinder_utils#create_volume() then deletion with the | +| | | function cinder_utils#delete_volume() | ++---------------------------------------+---------------+-----------------------------------------------------------+ + nova_utils_tests.py - NovaUtilsKeypairTests ------------------------------------------- @@ -295,6 +390,16 @@ nova_utils_tests.py - NovaUtilsInstanceTests | | | nova_utils.create_server() | +---------------------------------------+---------------+-----------------------------------------------------------+ +nova_utils_tests.py - NovaUtilsInstanceVolumeTests +-------------------------------------------------- + ++---------------------------------------+---------------+-----------------------------------------------------------+ +| Test Name | Nova API | Description | ++=======================================+===============+===========================================================+ +| test_add_remove_volume | 2 | Ensures that a VM instance can properly attach and detach | +| | | a volume using the nova interface | ++---------------------------------------+---------------+-----------------------------------------------------------+ + create_flavor_tests.py - CreateFlavorTests ------------------------------------------ diff --git a/docs/how-to-use/IntegrationTests.rst b/docs/how-to-use/IntegrationTests.rst index 5b4830e..5a734ef 100644 --- a/docs/how-to-use/IntegrationTests.rst +++ b/docs/how-to-use/IntegrationTests.rst @@ -229,6 +229,133 @@ create_router_tests.py - CreateRouterNegativeTests | | | create a router to an external network that does not exist| +----------------------------------------+---------------+-----------------------------------------------------------+ +create_qos_tests.py - CreateQoSTests +------------------------------------ + ++----------------------------------------+---------------+-----------------------------------------------------------+ +| Test Name | Cinder API | Description | ++========================================+===============+===========================================================+ +| test_create_qos | 2 & 3 | Tests the creation of a QoS Spec with the class | +| | | OpenStackQoS | ++----------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_delete_qos | 2 & 3 | Tests the creation of a QoS Spec with the class | +| | | OpenStackQoS, its deletion with cinder_utils.py the | +| | | the attempts to use the clean() method to ensure an | +| | | exception is not called | ++----------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_same_qos | 2 & 3 | Tests the creation of a QoS Spec with the class | +| | | OpenStackQoS then instantiates another OpenStackQoS | +| | | object with the same configuration to ensure the second | +| | | instance returns the ID of the original | ++----------------------------------------+---------------+-----------------------------------------------------------+ + +create_volume_type_tests.py - CreateSimpleVolumeTypeSuccessTests +---------------------------------------------------------------- + ++----------------------------------------+---------------+-----------------------------------------------------------+ +| Test Name | Cinder API | Description | ++========================================+===============+===========================================================+ +| test_create_volume_type | 2 & 3 | Tests the creation of a Volume Type with the class | +| | | OpenStackVolumeType | ++----------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_delete_volume_type | 2 & 3 | Tests the creation of a Volume Type with the class | +| | | OpenStackVolumeType, its deletion with cinder_utils.py, | +| | | then attempts to use the clean() method to ensure an | +| | | exception is not raised | ++----------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_same_volume_type | 2 & 3 | Tests the creation of a Volume Type with the class | +| | | OpenStackVolumeType then instantiates another | +| | | OpenStackVolumeType object with the same configuration to | +| | | ensure the second instance returns the ID of the original | ++----------------------------------------+---------------+-----------------------------------------------------------+ + +create_volume_type_tests.py - CreateSimpleVolumeTypeComplexTests +---------------------------------------------------------------- + ++-----------------------------------------+---------------+-----------------------------------------------------------+ +| Test Name | Cinder API | Description | ++=========================================+===============+===========================================================+ +| test_volume_type_with_qos | 2 & 3 | Tests the creation of a Volume Type with the class | +| | | OpenStackVolumeType with a QoSSpec | ++-----------------------------------------+---------------+-----------------------------------------------------------+ +| test_volume_type_with_encryption | 2 & 3 | Tests the creation of a Volume Type with the class | +| | | OpenStackVolumeType with encryption | ++-----------------------------------------+---------------+-----------------------------------------------------------+ +| test_volume_type_with_qos_and_encryption| 2 & 3 | Tests the creation of a Volume Type with the class | +| | | OpenStackVolumeType with encryption and QoS Spec | ++-----------------------------------------+---------------+-----------------------------------------------------------+ + +create_volume_tests.py - CreateSimpleVolumeSuccessTests +------------------------------------------------------- + ++----------------------------------------+---------------+-----------------------------------------------------------+ +| Test Name | Cinder API | Description | ++========================================+===============+===========================================================+ +| test_create_volume_simple | 2 & 3 | Tests the creation of a Volume Type with the class | +| | | OpenStackVolume | ++----------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_delete_volume | 2 & 3 | Tests the creation of a Volume with the class | +| | | OpenStackVolume, its deletion with cinder_utils.py, then | +| | | attempts to use the clean() method to ensure an | +| | | exception is not raised | ++----------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_same_volume | 2 & 3 | Tests the creation of a Volume with the class | +| | | OpenStackVolume then instantiates another | +| | | OpenStackVolume object with the same configuration to | +| | | ensure the second instance returns the ID of the original | ++----------------------------------------+---------------+-----------------------------------------------------------+ + +create_volume_tests.py - CreateSimpleVolumeFailureTests +------------------------------------------------------- + ++----------------------------------------+---------------+-----------------------------------------------------------+ +| Test Name | Cinder API | Description | ++========================================+===============+===========================================================+ +| test_create_volume_bad_size | 2 & 3 | Tests to ensure that attempting to create a volume with a | +| | | size of -1 raises a BadRequest exception | ++----------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_volume_bad_type | 2 & 3 | Tests to ensure that attempting to create a volume with a | +| | | type that does not exist raises a NotFound exception | ++----------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_volume_bad_image | 2 & 3 | Tests to ensure that attempting to create a volume with an| +| | | image that does not exist raises a BadRequest exception | ++----------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_volume_bad_zone | 2 & 3 | Tests to ensure that attempting to create a volume with an| +| | | invalid availability zone raises a BadRequest exception | ++----------------------------------------+---------------+-----------------------------------------------------------+ + +create_volume_tests.py - CreateVolumeWithTypeTests +-------------------------------------------------- + ++----------------------------------------+---------------+-----------------------------------------------------------+ +| Test Name | Cinder API | Description | ++========================================+===============+===========================================================+ +| test_bad_volume_type | 2 & 3 | Tests to ensure the creation of a Volume with the | +| | | OpenStackVolume#create() method raises a NotFound | +| | | exception when attempting to apply a VolumeType that does | +| | | not exist | ++----------------------------------------+---------------+-----------------------------------------------------------+ +| test_valid_volume_type | 2 & 3 | Tests to ensure the creation of a Volume with the | +| | | OpenStackVolume#create() method properly creates the | +| | | volume when associating with a valid VolumeType | ++----------------------------------------+---------------+-----------------------------------------------------------+ + +create_volume_tests.py - CreateVolumeWithImageTests +--------------------------------------------------- + ++----------------------------------------+---------------+-----------------------------------------------------------+ +| Test Name | Cinder API | Description | ++========================================+===============+===========================================================+ +| test_bad_image_name | 2 & 3 | Tests to ensure the creation of a Volume with the | +| | | OpenStackVolume#create() method raises a BadRequest | +| | | exception when attempting to apply an image that does not | +| | | exist | ++----------------------------------------+---------------+-----------------------------------------------------------+ +| test_valid_volume_image | 2 & 3 | Tests to ensure the creation of a Volume with the | +| | | OpenStackVolume#create() method properly creates the | +| | | volume when associating with a valid image | ++----------------------------------------+---------------+-----------------------------------------------------------+ + create_stack_tests.py - CreateStackSuccessTests ----------------------------------------------- @@ -410,6 +537,19 @@ create_instance_tests.py - InstanceSecurityGroupTests | | Neutron 2 | that has already been added to the instance | +---------------------------------------+---------------+-----------------------------------------------------------+ +create_instance_tests.py - CreateInstanceVolumeTests +---------------------------------------------------- + ++---------------------------------------+---------------+-----------------------------------------------------------+ +| Test Name | API Versions | Description | ++=======================================+===============+===========================================================+ +| test_create_instance_with_one_volume | Nova 2 | Ensures that a VM instance can have one volume attached | +| | Cinder 2 & 3 | to it | ++---------------------------------------+---------------+-----------------------------------------------------------+ +| test_create_instance_with_two_volumes | Nova 2 | Ensures that a VM instance can have two volumes attached | +| | Cinder 2 & 3 | to it | ++---------------------------------------+---------------+-----------------------------------------------------------+ + ansible_utils_tests.py - AnsibleProvisioningTests ------------------------------------------------- diff --git a/docs/how-to-use/LibraryUsage.rst b/docs/how-to-use/LibraryUsage.rst index 16cf446..9518c2b 100644 --- a/docs/how-to-use/LibraryUsage.rst +++ b/docs/how-to-use/LibraryUsage.rst @@ -30,15 +30,16 @@ attributes are listed below: - auth\_url - project\_name (aka. tenant\_name) - identity\_api\_version (for obtaining Keystone authorization token. - Versions 2.0 & v3 only validated.) -- image\_api\_version (Glance version 1 & 2 only validated) + default = 2, Versions 2.0 & v3 only validated.) +- image\_api\_version (default = 2, Glance version 1 & 2 only validated) - network\_api\_version (Neutron version 2 currently only validated) - compute\_api\_version (Nova version 2 currently only validated) - heat\_api\_version (Heat version 1 currently only validated) +- volume\_api\_version (default = 2, Heat versions 2 & 3 currently only validated) - user\_domain\_id (default='default') -- user\_domain\_name (default='default') +- user\_domain\_name (default='Default') - project\_domain\_id (default='default') -- project\_domain\_name (default='default') +- project\_domain\_name (default='Default') - interface (default='admin', used to specify the endpoint type for keystone: public, admin, internal) - cacert (default=False, expected values T|F to denote server certificate verification, else value contains the path to an HTTPS certificate) - region_name (The region name default=None) @@ -88,6 +89,8 @@ Create User - email - the user's email address (optional) - enabled - flag to determine whether or not the user should be enabled (default=True) + - roles - dict where key is the role's name and value is the name + the project to associate with the role (optional) .. code:: python @@ -114,7 +117,7 @@ Create Project - name - the project name (required) - domain - the project's domain (default='default') - description - the project's description (optional) - - enables - flag to determine whether or not the project should + - enabled - flag to determine whether or not the project should be enabled (default=True) @@ -148,6 +151,7 @@ Create Flavor if backend supports QoS extension (default=1.0) - is\_public - flag that denotes whether or not other projects can access image (default=True) + - metadata - freeform dict() for special metadata (optional) .. code:: python @@ -172,14 +176,19 @@ Create Image - image\_user - the default image user generally used by OpenStackVMInstance class for obtaining an SSH connection (required) - - img\_format - the image's format (i.e. qcow2) (required) + - img\_format or format - the image's format (i.e. qcow2) (required) - url - the download URL to obtain the image file (this or image\_file must be configured, not both) - image\_file - the location of the file to be sourced from the local filesystem (this or url must be configured, not both) + - extra\_properties - dict() object containing extra parameters to + pass when loading the image (i.e. ids of kernel and initramfs images) - nic\_config\_pb\_loc - the location of the ansible playbook that can configure additional NICs. Floating IPs are required - to perform this operation. (optional) + to perform this operation. (optional and deprecated) + - kernel\_image\_settings - the image settings for a kernel image (optional) + - ramdisk\_image\_settings - the image settings for a ramdisk image (optional) + - public - image will be created with public visibility when True (default = False) .. code:: python @@ -209,6 +218,10 @@ Create Keypair file is to be written or currently resides (optional but highly recommended to leverage or the private key will be lost forever) + - key\_size - The number of bytes for the key size when it needs to + be generated (value must be >=512, default = 1024) + - delete\_on\_clean - when True, the key files will be deleted when + OpenStackKeypair#clean() is called (default = False) .. code:: python @@ -242,6 +255,8 @@ Create Network - network\_type - the type of network (i.e. vlan\|vxlan\|flat) - physical\_network - the name of the physical network (required when network\_type is 'flat') + - segmentation\_id - the id of the segmentation (required + when network\_type is 'vlan') - subnet\_settings (list of optional snaps.openstack.create\_network.SubnetSettings objects) @@ -360,20 +375,30 @@ Create Router custom ports to internal subnets (similar to internal\_subnets with more control) - - name - - network\_name - - admin\_state\_up + - name - the port's display name + - network\_name - the name of the network on which to create the port + - admin\_state\_up - A boolean value denoting the administrative + status of the port (default = True) - project\_name - the name of the project (optional - can only be set by admin users) - - mac\_address - - ip\_addrs - - fixed\_ips - - security\_groups - - allowed\_address\_pairs - - opt\_value - - opt\_name - - device\_owner - - device\_id + - mac\_address - the port's MAC address to set (optional and + recommended not to set this configuration value) + - ip\_addrs - list of dict() objects containing two keys 'subnet_name' + and 'ip' where the value of the 'ip' entry is the expected IP + address assigned. This value gets mapped to the fixed\_ips + attribute (optional) + - fixed\_ips - dict() where the key is the subnet ID and value is the + associated IP address to assign to the port (optional) + - security\_groups - list of security group IDs (not tested) + - 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) .. code:: python @@ -389,6 +414,118 @@ Create Router # Cleanup router_creator.clean() +Create QoS Spec +--------------- + +- Volume Type - snaps.openstack.create\_qos.OpenStackQoS + + - snaps.openstack.create\_qos.QoSSettings + + - name - the volume type's name (required) + - consumer - the qos's consumer type of the enum type Consumer (required) + - specs - freeform dict() to be added as 'specs' (optional) + +.. code:: python + + from snaps.openstack.create_qos import QoSSettings, OpenStackQoS + + qos_settings = QoSSettings(name='stack-name', consumer=Consumer.front-end) + qos_creator = OpenStackQoS(os_creds, vol_type_settings) + qos_creator.create() + + # Perform logic + ... + + # Cleanup + qos_creator.clean() + +Create Volume Type +------------------ + +- Volume Type - snaps.openstack.create\_volume\_type.OpenStackVolumeType + + - snaps.openstack.create\_volume\_type.VolumeTypeSettings + + - name - the volume type's name (required) + - description - the volume type's description (optional) + - encryption - instance or config for VolumeTypeEncryptionSettings (optional) + - qos\_spec\_name - name of the QoS Spec to associate (optional) + - public - instance or config for VolumeTypeEncryptionSettings (optional) + +.. code:: python + + from snaps.openstack.create_volume_type import VolumeTypeSettings, OpenStackVolumeType + + vol_type_settings = VolumeTypeSettings(name='stack-name') + vol_type_creator = OpenStackHeatStack(os_creds, vol_type_settings) + vol_type_creator.create() + + # Perform logic + ... + + # Cleanup + vol_type_creator.clean() + +Create Volume +------------- + +- Volume - snaps.openstack.create\_volume.OpenStackVolume + + - snaps.openstack.create\_volume.VolumeSettings + + - name - the volume type's name (required) + - description - the volume type's description (optional) + - size - size of volume in GB (default = 1) + - image_name - when a glance image is used for the image source (optional) + - type\_name - the associated volume's type name (optional) + - availability\_zone - the name of the compute server on which to + deploy the volume (optional) + - multi_attach - when true, volume can be attached to more than one + server (default = False) + +.. code:: python + + from snaps.openstack.create\_volume import VolumeSettings, OpenStackVolume + + vol_settings = VolumeSettings(name='stack-name') + vol_creator = OpenStackVolume(os_creds, vol_settings) + vol_creator.create() + + # Perform logic + ... + + # Cleanup + vol_type_creator.clean() + +Create Heat Stack +----------------- + +- Heat Stack - snaps.openstack.create\_stack.OpenStackHeatStack + + - snaps.openstack.create\_stack.StackSettings + + - name - the stack's name (required) + - template - the heat template in dict() format (required when + template_path is None) + - template\_path - the location of the heat template file (required + when template is None) + - env\_values - dict() of strings for substitution of template + default values (optional) + +.. code:: python + + from snaps.openstack.create_stack import StackSettings, OpenStackHeatStack + + stack_settings = StackSettings(name='stack-name', template_path='/tmp/template.yaml') + stack_creator = OpenStackHeatStack(os_creds, stack_settings) + stack_creator.create() + + # Perform logic + ... + + # Cleanup + stack_creator.clean() + Create VM Instance ------------------ @@ -503,7 +640,12 @@ an example of this pattern as this is the only API where SNAPS is supporting more than one version) - snaps.openstack.utils.keystone\_utils - for calls to the Keystone - APIs + APIs (support for versions 2 & 3) - snaps.openstack.utils.glance\_utils - for calls to the Glance APIs + (support for versions 1 & 2) - snaps.openstack.utils.neutron\_utils - for calls to the Neutron APIs -- snaps.openstack.utils.nova\_utils - for calls to the Nova APIs + (version 2) +- snaps.openstack.utils.nova\_utils - for calls to the Nova APIs (version 2) +- snaps.openstack.utils.heat\_utils - for calls to the Heat APIs (version 1) +- snaps.openstack.utils.cinder\_utils - for calls to the Cinder APIs + (support for versions 2 & 3) diff --git a/docs/how-to-use/UnitTests.rst b/docs/how-to-use/UnitTests.rst index 5fb04db..f6f52b5 100644 --- a/docs/how-to-use/UnitTests.rst +++ b/docs/how-to-use/UnitTests.rst @@ -222,6 +222,54 @@ OutputDomainObjectTests Ensures that all required members are included when constructing a Output domain object (for Heat) +VolumeSettingsUnitTests +----------------------- + +Ensures that all required members are included when constructing a +VolumeSettings object + +VolumeDomainObjectTests +----------------------- + +Ensures that all required members are included when constructing a +Volume domain object (for Cinder) + +VolumeTypeSettingsUnitTests +--------------------------- + +Ensures that all required members are included when constructing a +VolumeTypeSettings object + +VolumeTypeDomainObjectTests +--------------------------- + +Ensures that all required members are included when constructing a +VolumeType domain object (for Cinder) + +VolumeTypeEncryptionObjectTests +------------------------------- + +Ensures that all required members are included when constructing a +VolumeTypeEncryption domain object (for Cinder) + +QoSSettingsUnitTests +-------------------- + +Ensures that all required members are included when constructing a +QoSSettings object + +QoSSpecDomainObjectTests +------------------------ + +Ensures that all required members are included when constructing a +QoSSpec domain object (for Cinder) + +VolumeDomainObjectTests +----------------------- + +Ensures that all required members are included when constructing a +Volume domain object (for Cinder) + FloatingIpSettingsUnitTests --------------------------- diff --git a/docs/how-to-use/VirtEnvDeploy.rst b/docs/how-to-use/VirtEnvDeploy.rst index dd95202..3b14842 100644 --- a/docs/how-to-use/VirtEnvDeploy.rst +++ b/docs/how-to-use/VirtEnvDeploy.rst @@ -46,183 +46,324 @@ Use launcher.py to deploy and clean up example environments. These examples are - 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". + - connections: the different connections/credentials to be used by the + launcher application + + - connection: the credentials and endpoints required to connect to an + OpenStack project/tenant + + - name: the name of the credentials for use when creating objects (required) + - 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) + - identity\_api\_version: the Keystone client version to use (default = 2) + - image\_api\_version: the Glance client version to use (default = 2) + - network\_api\_version: the Neutron client version to use (default = 2) + - compute\_api\_version: the Nova client version to use (default = 2) + - heat\_api\_version: the Heat client version to use (default = 1) + - volume\_api\_version: the Cinder client version to use (default = 2) + - user\_domain\_id: the user domain ID to use (default = 'default') + - user\_domain\_name: the user domain name to use (default = 'Default') + - project\_domain\_id: the project domain ID to use (default = 'default') + - project\_domain\_name: the project domain name to use (default = 'Default') + - interface: Used to specify the endpoint type for keystone (default = 'public') + - cacert: True for https or the certification file location (default = False) + - region\_name: the region (default = None) + - proxy\_settings: for accessing APIs hidden behind an HTTP proxy + + - host: hostname or IP of HTTP proxy host (required) + - port: port number of the HTTP proxy server (required) + - http\_host: hostname or IP of HTTPS proxy host (default = host) + - port: port number of the HTTPS proxy server (default = port) + - ssh\_proxy\_cmd: the OpenSSH command used to access the SSH port + of a VM (optional) + + - projects: the projects/tenants to create + + - project: a project/tenant to create (admin user credentials required) + + - os\_creds\_name: the connection name (default = 'default' + required or use "os\_user" below instead) + - name: the project's name (required) + - domain or domain_name: the project's domain name (default = 'Default') + - description: the description (optional) + - users: a list of users to associate to the project (optional) + - enabled: when True the project will be enabled on creation (default = True) + + - users: the users to create + + - user: a user to create (admin user credentials required) + + - os\_creds\_name: the connection name (required) + - name: the username (required) + - password: the user's password (required) + - project\_name: the user's primary project name (optional) + - domain\_name: the user's domain name (default = 'Default') + - email: the user's email address (optional) + - roles: dict where key is the role's name and value is the name + of the project to associate with the role (optional) + + - flavors: the flavors to create + + - flavor: a flavor to create (admin user credentials required) + + - os\_creds\_name: the connection name (default = 'default' + required or use "os\_user" below instead) + - name: the name (required) + - flavor\_id: the string ID (default 'auto') + - ram: the required RAM in MB (required) + - disk: the size of the root disk in GB (required) + - vcpus: the number of virtual CPUs (required) + - ephemeral: the size of the ephemeral disk in GB (default 0) + - swap: the size of the dedicated swap disk in GB (default 0) + - rxtx\_factor: the receive/transmit factor to be set on ports if + backend supports QoS extension (default 1.0) + - is\_public: denotes whether or not the flavor is public (default = True) + - metadata: freeform dict() for special metadata (optional) + + - images: describes each image to create + - image: + + - os\_creds\_name: the connection name (default = 'default' + required or use "os\_user" below instead) + - os\_user: the connection from a new user defined in template + (required or use "os\_creds\_name" above + + - name: the user's name (required) + - project\_name: the project name to use + + - name: The unique image name. If the name already exists for + your project, a new one will not be created (required) + - image\_user: the image's default sudo user (required) + - format or img\_format: the image format type (required i.e. qcow2) + - url or download\_url: The HTTP download location of the image file + (required when "image_file" below has not been configured) + - image\_file: the image file location (required when "url" has not + been configured) + - kernel\_image\_settings: the settings for a kernel image (optional) + - ramdisk\_image\_settings: the settings for a kernel image (optional) + - public: publically visibile when True (default = True) - 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) + - network: + + - os\_creds\_name: the connection name (default = 'default' + required or use "os\_user" below instead) + - os\_user: the connection from a new user defined in template + (required or use "os\_creds\_name" above + + - name: the user's name (required) + - project\_name: the project name to use + + - 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) + - physical\_network: the name of the physical network + (required when network_type is 'flat') + - segmentation\_id: the id of the segmentation + (required when network_type is 'vlan') + - 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 (default = ['8.8.8.8'] + - 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) + + - security_groups: + + - security_group: + + - os\_creds\_name: the connection name (default = 'default' + required or use "os\_user" below instead) + - os\_user: the connection from a new user defined in template + (required or use "os\_creds\_name" above + + - name: the user's name (required) + - project\_name: the project name to use + + - name: The name of the security group to be created (required) + - description: The security group's description (optional) + - project\_name: Name of the project who owns the security group (optional) + - rule\_settings: List of rules to place onto security group (optional) + + - description: the rule's description (optional) + - protocol: rule's protcol ('icmp' or 'tcp' or 'udp' or 'null') + - ethertype: rule's ethertype ('4' or '6') + - port\_range\_min: The minimum port number in the range that is + matched by the security group rule. When the protocol is 'tcp' + or 'udp', this value must be <= 'port_range_max' (optional) + - port\_range\_max: The maximum port number in the range that is + matched by the security group rule. When the protocol is 'tcp' + or 'udp', this value must be <= 'port_range_max' (optional) + - remote\_ip\_prefix: The remote IP prefix to associate with this + metering rule packet (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) + + - os\_creds\_name: the connection name (default = 'default' + required or use "os\_user" below instead) + - os\_user: the connection from a new user defined in template + (required or use "os\_creds\_name" above + + - name: the user's name (required) + - project\_name: the project name to use + + - name: The name of the router to be created (required) + - project\_name: Name of the project who owns the network (optional) + - external\_gateway: Name of the external network to which to route + (optional) + - admin\_state\_up: T\|F (default True) + - external\_fixed\_ids: Dictionary containing the IP address + parameters (optional) + - internal\_subnets: List of subnet names to which to connect this + router (optional) + + - port_settings (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 (required and must be + unique for project) + - network\_name: The name of the network on which to create + the port (optional) + - admin\_state\_up: T\|F (default True) + - project\_name: Name of the project who owns the network (optional) + - mac\_address: The port's MAC address (optional) + - ip\_addrs: A list of k/v pairs (optional) + - security\_groups: a list of names of the the security groups + to apply to the port + - opt\_value: The extra DHCP option value (optional) + - opt\_name: The extra DHCP option name (optional) - 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) + + - os\_creds\_name: the connection name (default = 'default' + required or use "os\_user" below instead) + - os\_user: the connection from a new user defined in template + (required or use "os\_creds\_name" above + + - name: the user's name (required) + - project\_name: the project name to use + + - 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) + + - os\_creds\_name: the connection name (default = 'default' + required or use "os\_user" below instead) + - os\_user: the connection from a new user defined in template + (required or use "os\_creds\_name" above + + - name: the user's name (required) + - project\_name: the project name to use + + - 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 |