Refactoring of VolumeSettings to extend VolumeConfig

[snaps.git] / docs / how-to-use / LibraryUsage.rst

diff --git a/docs/how-to-use/LibraryUsage.rst b/docs/how-to-use/LibraryUsage.rst
index 36d4b9c..fc22a3d 100644 (file)
--- a/docs/how-to-use/LibraryUsage.rst
+++ b/docs/how-to-use/LibraryUsage.rst
@@ -30,16 +30,25 @@ attributes are listed below:
 -  auth\_url
 -  project\_name (aka. tenant\_name)
 -  identity\_api\_version (for obtaining Keystone authorization token.
 -  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 currently 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)
 -  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\_id (default='default')

+-  user\_domain\_name (default='Default')

 -  project\_domain\_id (default='default')
 -  project\_domain\_id (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)

 -  proxy\_settings
 
    -  host (the HTTP proxy host)
    -  port (the HTTP proxy port)
 -  proxy\_settings
 
    -  host (the HTTP proxy host)
    -  port (the HTTP proxy port)

+   -  https\_host (the HTTPS proxy host, default value of host)
+   -  https\_port (the HTTPS proxy port, default value of port)

    -  ssh\_proxy\_cmd (same as the value placed into ssh -o
       ProxyCommand='<this config value>')
 
    -  ssh\_proxy\_cmd (same as the value placed into ssh -o
       ProxyCommand='<this config value>')
 


@@ -70,7 +79,7 @@ Create User
 -----------
 -  User - snaps.openstack.create\_user.OpenStackUser
 
 -----------
 -  User - snaps.openstack.create\_user.OpenStackUser
 

-   -  snaps.openstack.create\_user.UserSettings
+   -  snaps.openstack.user.UserConfig

 
       -  name - the username (required)
       -  password - the user's password (required)
 
       -  name - the username (required)
       -  password - the user's password (required)


@@ -80,11 +89,14 @@ Create User
       -  email - the user's email address (optional)
       -  enabled - flag to determine whether or not the user should be
          enabled (default=True)
       -  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
 
 
 .. code:: python
 

-    from snaps.openstack.create_user import UserSettings, OpenStackUser
-    user_settings = UserSettings(name='username', password='password')
+    from snaps.config.user import UserConfig
+    from snaps.openstack.create_user import OpenStackUser
+    user_settings = UserConfig(name='username', password='password')

     user_creator = OpenStackUser(os_creds, user_settings)
     user_creator.create()
 
     user_creator = OpenStackUser(os_creds, user_settings)
     user_creator.create()
 


@@ -101,19 +113,20 @@ Create Project
 --------------
 -  Project - snaps.openstack.create\_project.OpenStackProject
 
 --------------
 -  Project - snaps.openstack.create\_project.OpenStackProject
 

-   -  snaps.openstack.create\_project.ProjectSettings
+   -  snaps.openstack.project.ProjectConfig

 
       -  name - the project name (required)
       -  domain - the project's domain (default='default')
       -  description - the project's description (optional)
 
       -  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)
 
 
 .. code:: python
 
          be enabled (default=True)
 
 
 .. code:: python
 

-    from snaps.openstack.create_project import ProjectSettings, OpenStackProject
-    project_settings = ProjectSettings(name='username', password='password')
+    from snaps.openstack.project import ProjectConfig
+    from snaps.openstack.create_project import OpenStackProject
+    project_settings = ProjectConfig(name='username', password='password')

     project_creator = OpenStackProject(os_creds, project_settings)
     project_creator.create()
 
     project_creator = OpenStackProject(os_creds, project_settings)
     project_creator.create()
 


@@ -127,7 +140,7 @@ Create Flavor
 -------------
 -  Flavor - snaps.openstack.create\_flavor.OpenStackFlavor
 
 -------------
 -  Flavor - snaps.openstack.create\_flavor.OpenStackFlavor
 

-   -  snaps.openstack.create\_flavor.FlavorSettings
+   -  snaps.config.flavor.FlavorConfig

 
       -  name - the flavor name (required)
       -  flavor\_id - the flavor's string ID (default='auto')
 
       -  name - the flavor name (required)
       -  flavor\_id - the flavor's string ID (default='auto')


@@ -140,11 +153,13 @@ 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)
          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
 
 
 .. code:: python
 

-    from snaps.openstack.create_flavor import FlavorSettings, OpenStackFlavor
-    flavor_settings = FlavorSettings(name='flavor-name', ram=4, disk=10, vcpus=2)
+    from snaps.config.flavor import FlavorConfig
+    from snaps.openstack.create_flavor import OpenStackFlavor
+    flavor_settings = FlavorConfig(name='flavor-name', ram=4, disk=10, vcpus=2)

     flavor_creator = OpenStackFlavor(os_creds, flavor_settings)
     flavor_creator.create()
 
     flavor_creator = OpenStackFlavor(os_creds, flavor_settings)
     flavor_creator.create()
 


@@ -158,27 +173,33 @@ Create Image
 ------------
 -  Image - snaps.openstack.create\_image.OpenStackImage
 
 ------------
 -  Image - snaps.openstack.create\_image.OpenStackImage
 

-   -  snaps.openstack.create\_image.ImageSettings
+   -  snaps.config.image.ImageConfig

 
       -  name - the image name (required)
       -  image\_user - the default image user generally used by
          OpenStackVMInstance class for obtaining an SSH connection
          (required)
 
       -  name - the image name (required)
       -  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)
       -  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
       -  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
 
 
 
 .. code:: python
 

-    from snaps.openstack.create_image import ImageSettings, OpenStackImage
-    image_settings = ImageSettings(name='image-name', image_user='ubuntu', img_format='qcow2',
-                                   url='http://uec-images.ubuntu.com/releases/trusty/14.04/ubuntu-14.04-server-cloudimg-amd64-disk1.img')
+    from snaps.openstack.create_image import OpenStackImage
+    from snaps.config.image import ImageConfig
+    image_settings = ImageConfig(name='image-name', image_user='ubuntu', img_format='qcow2',
+                                 url='http://uec-images.ubuntu.com/releases/trusty/14.04/ubuntu-14.04-server-cloudimg-amd64-disk1.img')

     image_creator = OpenStackImage(os_creds, image_settings)
     image_creator.create()
 
     image_creator = OpenStackImage(os_creds, image_settings)
     image_creator.create()
 


@@ -192,7 +213,7 @@ Create Keypair
 --------------
 -  Keypair - snaps.openstack.create\_keypair.OpenStackKeypair
 
 --------------
 -  Keypair - snaps.openstack.create\_keypair.OpenStackKeypair
 

-   -  snaps.openstack.create\_keypair.KeypairSettings
+   -  snaps.openstack.keypair.KeypairConfig

 
       -  name - the keypair name (required)
       -  public\_filepath - the file location to where the public key is
 
       -  name - the keypair name (required)
       -  public\_filepath - the file location to where the public key is


@@ -201,11 +222,16 @@ Create Keypair
          file is to be written or currently resides (optional but highly
          recommended to leverage or the private key will be lost
          forever)
          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
 
 
 .. code:: python
 

-    from snaps.openstack.create_keypair import KeypairSettings, OpenStackKeypair
-    keypair_settings = KeypairSettings(name='kepair-name', private_filepath='/tmp/priv-kp')
+    from snaps.openstack.keypair.KeypairConfig
+    from snaps.openstack.create_keypairs import OpenStackKeypair
+    keypair_settings = KeypairConfig(name='kepair-name', private_filepath='/tmp/priv-kp')

     keypair_creator = OpenStackKeypair(os_creds, keypair_settings)
     keypair_creator.create()
 
     keypair_creator = OpenStackKeypair(os_creds, keypair_settings)
     keypair_creator.create()
 


@@ -234,6 +260,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')
       -  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)
 
       -  subnet\_settings (list of optional
          snaps.openstack.create\_network.SubnetSettings objects)
 


@@ -335,7 +363,7 @@ Create Router
 
 -  Router - snaps.openstack.create\_router.OpenStackRouter
 
 
 -  Router - snaps.openstack.create\_router.OpenStackRouter
 

-   -  snaps.openstack.create\_router.RouterSettings
+   -  snaps.openstack.router.RouterConfig

 
       -  name - the router name (required)
       -  project\_name - the name of the project (optional - can only be
 
       -  name - the router name (required)
       -  project\_name - the name of the project (optional - can only be


@@ -352,26 +380,37 @@ Create Router
          custom ports to internal subnets (similar to internal\_subnets
          with more control)
 
          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)
          -  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
 
 
 .. code:: python
 

-    from snaps.openstack.create_router import RouterSettings, OpenStackRouter
+    from snaps.config.router import RouterConfig
+    from snaps.openstack.create_router import OpenStackRouter

 
 

-    router_settings = RouterSettings(name='router-name', external_gateway='external')
+    router_settings = RouterConfig(name='router-name', external_gateway='external')

     router_creator = OpenStackRouter(os_creds, router_settings)
     router_creator.create()
 
     router_creator = OpenStackRouter(os_creds, router_settings)
     router_creator.create()
 


@@ -381,6 +420,122 @@ Create Router
     # Cleanup
     router_creator.clean()
 
     # Cleanup
     router_creator.clean()
 

+Create QoS Spec
+---------------
+
+-  Volume Type - snaps.openstack.create\_qos.OpenStackQoS
+
+   -  snaps.openstack.qos.QoSConfig
+
+      -  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.qos import QoSConfig
+    from snaps.openstack.create_qos import OpenStackQoS
+
+    qos_settings = QoSConfig(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.config.volume\_type.VolumeTypeConfig
+
+      -  name - the volume type's name (required)
+      -  description - the volume type's description (optional)
+      -  encryption - instance or config for VolumeTypeEncryptionConfig (optional)
+      -  qos\_spec\_name - name of the QoS Spec to associate (optional)
+      -  public - instance or config for VolumeTypeEncryptionConfig (optional)
+
+.. code:: python
+
+    from snaps.config.volume_type import VolumeTypeConfig
+    from snaps.openstack.create_volume_type import OpenStackVolumeType
+
+    vol_type_settings = VolumeTypeConfig(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.config.volume.VolumeConfig
+
+      -  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.config.volume import VolumeConfig
+    from snaps.openstack.create\_volume import OpenStackVolume
+
+    vol_settings = VolumeConfig(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.config.stack.StackConfig
+
+      -  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.config.stack import StackConfig
+    from snaps.openstack.create_stack import OpenStackHeatStack
+
+    stack_settings = StackConfig(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
 ------------------
 
 Create VM Instance
 ------------------
 


@@ -426,10 +581,10 @@ Create VM Instance
       -  userdata - the cloud-init script to execute after VM has been
          started
 
       -  userdata - the cloud-init script to execute after VM has been
          started
 

-   -  image\_settings - see snaps.openstack.create\_image.ImageSettings
+   -  image\_settings - see snaps.config.image.ImageConfig

       above (required)
    -  keypair\_settings - see
       above (required)
    -  keypair\_settings - see

-      snaps.openstack.create\_keypairs.KeypairSettings above (optional)
+      snaps.openstack.keypair.KeypairConfig above (optional)

 
 .. code:: python
 
 
 .. code:: python
 


@@ -495,7 +650,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
 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
 -  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.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)