diff options
Diffstat (limited to 'docs/how-to-use/LibraryUsage.rst')
| -rw-r--r-- | docs/how-to-use/LibraryUsage.rst | 265 |
1 files changed, 212 insertions, 53 deletions
diff --git a/docs/how-to-use/LibraryUsage.rst b/docs/how-to-use/LibraryUsage.rst index 16cf446..3183305 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) @@ -78,7 +79,7 @@ Create User ----------- - 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) @@ -88,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) + - roles - dict where key is the role's name and value is the name + the project to associate with the role (optional) .. 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() @@ -109,19 +113,20 @@ Create Project -------------- - 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) - - 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 - 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() @@ -135,7 +140,7 @@ Create Flavor ------------- - 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') @@ -148,11 +153,17 @@ 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) + - freeform dict() for values of basic elements + (e.g. ram, vcpu, disk, etc) could be added. + As result the hard coded values of those elements will be + overwritten by the new ones (optional) .. 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() @@ -166,27 +177,33 @@ Create Image ------------ - 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) - - 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 - 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() @@ -200,7 +217,7 @@ Create Keypair -------------- - 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 @@ -209,11 +226,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) + - 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 - from snaps.openstack.create_keypairs 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() @@ -228,7 +250,7 @@ Create Network - Network - snaps.openstack.create\_network.OpenStackNetwork - - snaps.openstack.create\_network.NetworkSettings + - snaps.config_network.NetworkConfig - name - the name of the network (required) - admin\_state\_up - flag denoting the administrative status of @@ -242,8 +264,10 @@ 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) + snaps.config.network.SubnetConfig objects) - cidr - the subnet's CIDR (required) - ip\_version - 4 or 6 (default=4) @@ -267,10 +291,11 @@ Create Network .. code:: python - from snaps.openstack.create_network import NetworkSettings, SubnetSettings, OpenStackNetwork + from snaps.config.network import NetworkConfig, SubnetConfig + from snaps.openstack.create_network import OpenStackNetwork - subnet_settings = SubnetSettings(name='subnet-name', cidr='10.0.0.0/24') - network_settings = NetworkSettings(name='network-name', subnet_settings=[subnet_settings]) + subnet_settings = SubnetConfig(name='subnet-name', cidr='10.0.0.0/24') + network_settings = NetworkConfig(name='network-name', subnet_settings=[subnet_settings]) network_creator = OpenStackNetwork(os_creds, network_settings) network_creator.create() @@ -320,10 +345,12 @@ Create Security Group .. code:: python + from snaps.config.network import SubnetConfig + from snaps.config.rule import RuleConfig from snaps.openstack.create_security_group import SecurityGroupSettings, SecurityGroupRuleSettings, Direction, OpenStackSecurityGroup - rule_settings = SubnetSettings(name='subnet-name', cidr='10.0.0.0/24') - network_settings = NetworkSettings(name='network-name', subnet_settings=[subnet_settings]) + rule_settings = RuleConfig(name='subnet-name', cidr='10.0.0.0/24') + network_settings = SubnetConfig(name='network-name', subnet_settings=[subnet_settings]) sec_grp_name = 'sec-grp-name' rule_settings = SecurityGroupRuleSettings(name=sec_grp_name, direction=Direction.ingress) @@ -343,7 +370,7 @@ Create Router - 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 @@ -356,30 +383,41 @@ Create Router - internal\_subnets - list of subnet names to which this router will connect (optional) - port\_settings (list of optional - snaps.openstack.create\_router.PortSettings objects) - creates + snaps.config.network.PortConfig objects) - creates 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 - 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() @@ -389,6 +427,122 @@ Create Router # 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 ------------------ @@ -399,7 +553,7 @@ Create VM Instance - name - the name of the VM (required) - flavor - the name of the flavor (required) - port\_settings - list of - snaps.openstack.create\_network.PortSettings objects where each + snaps.config.network.PortConfig objects where each denote a NIC (see above in create router section for details) API does not require, but newer NFVIs now require VMs have at least one network @@ -434,17 +588,17 @@ Create VM Instance - 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 - snaps.openstack.create\_keypairs.KeypairSettings above (optional) + snaps.openstack.keypair.KeypairConfig above (optional) .. code:: python from snaps.openstack.create_instance import VmInstanceSettings, FloatingIpSettings, OpenStackVmInstance - from snaps.openstack.create_network import PortSettings + from snaps.config.network import PortConfig - port_settings = PortSettings(name='port-name', network_name=network_settings.name) + port_settings = PortConfig(name='port-name', network_name=network_settings.name) floating_ip_settings = FloatingIpSettings(name='fip1', port_name=port_settings.name, router_name=router_settings.name) instance_settings = VmInstanceSettings(name='vm-name', flavor='flavor_settings.name', port_settings=[port_settings], floating_ip_settings=[floating_ip_settings]) @@ -503,7 +657,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) |