Package: ospclientsdk
ospclientsdkAn SDK like wrapper around the openstackclient to reduce the need to write boilerplate
subprocess code.InstallationOspclientsdk can be easily installed with a one line command. It is recommended (as best practice) to create a virtual
environment and install ospclientsdk. Please see the commands below to install. Note this is only supported
in python 3.6 and higher.# install python virtualenv
$ pip install python-virtualenv

# create virtualenv
$ virtualenv ospclientsdk

# activate virtualenv
$ source ospclientsdk/bin/activate

# install blaster
$ (ospclientsdk) pip install ospclientsdkUsageLet's dive into how to use this sdk.InitializeWhen working with the sdk the main interface you will be interacting with is theClientShellclass. This interface can be initialized with with or without credentialsfromospclientsdkimportClientShellimportyaml"""You can provide a string path to a clouds.yaml file. If a cloud isn't specifiedthe shell will default to using one called 'openstack'"""shell=ClientShell(cloud_file='clouds.yaml',cloud='test')"""You can also preload the clouds.yaml file or build the dictionary by handand provide it that way."""creds={}withopen('clouds.yaml')asf:creds=yaml.safe_load(f)shell=ClientShell(cloud_dict=creds,cloud='test')"""You can also load the shell with credentials after it has been initialized"""shell=ClientShell()shell.load_cloud_config(cloud_dict=creds,cloud='test')Once the shell has been intialized you can see what command groups and commands
are available in a couple of ways.Note when the commands are loaded the white spaces are replaced with
underscores ('_') to make it easier to parse and find what you're looking for. i.e.server createtoserver_createfromospclientsdkimportClientShellshell=ClientShell(cloud_file='clouds.yaml',cloud='test')"""You can see a simplied version of all available command groups and their respective commands.This will return a dictionary. Where the key is the name of the of the command group andthe values are a list of commands supported by the command group."""cmd_groups=shell.all_osp_cmd_groupscmd_list=cmd_groups.get('data_processing',{})"""If you already know the name of the command group you want and would like to see thecommands available for it. You can access one of the many command group properties."""cmd_list=shell.data_processing_commands"""If you would like to check which are the available commands irrespective of command groupyou can do so as well"""all_cmds=shell.all_osp_commandsExecuting CommandsOnce you have an idea of what commands you want to execute you have a few different ways of
executing them. Before we dive into those, let's talk a little bit about generating the options
and their arguments.OptionsThe options and argument values for the command actions are always defined as dictionaries. Let's
touch on a couple examplesExample 1Any time an option takes an argument# Thiscommandcreate--optionarg<res_name># Can be defined like{'option':'arg','res':'res_name'}Example 2Any time an option takes an argument and can be specified multiple times# Thiscommandcreate--optionarg1--optionarg2<res_name># Can be defined like{'option':['arg1','arg2'],'res':'res_name'}Example 3Any time an option takes an argument with the value in k=v# Thiscommandcreate--optionarg1=val1# Can be defined like{'option':[{'arg1':'val1'}],'res':'res_name'}Example 4Any time an option takes an argument with the value in k=v and can be specified multiple times.# Thiscommandcreate--optionarg1=val1--optionarg2=val2<res_name># Can be defined like{'option':[{'arg1':'val1'},{'arg2':'val2'}],'res':'res_name'}Example 5Any time an option takes an argument but the value can be a comma separated list of k=v# Thiscommandcreate--optionarg1=val1,arg2=val2,arg3=val3<res_name># Can be defined like{'option':[{'arg1':'val1','arg2':'val2','arg3':'val3'}],'res':'res_name'}Example 6Any time an option takes no argument and actions like a boolean flag# Thiscommandcreate--option<res_name># Can be defined like{'option':True,'res':'res_name'}Example 7In the case ofaddcommand actions, which not only require the name or id of the resource
it needs the name or id of the target resource you want to add# Thiscommandadd--optionarg1<res_name><tgt_res># Can be defined like{'option':'arg1','res':'res_name','tgt_res':'tgt_res'}Noterather thannameyou could supplyidand rather thantgt_nameyou can supplytgt_idExample 7In the case ofdeletecommand actions, you can specify multiple resources# Thiscommanddelete<res_name_1><res_name_2># Can be defined like{'res':['res_name_1','res_name_2']}For a full list of commands and options refer to theopenstackclientdocumentation.High Level APIsThe first and recommended way is to use the high level APIs the shell provides
through a series of proxy instances. Each proxy object reflects a command group
and provides APIs that map to the corresponding CLI commands.Example 1fromospclientsdkimportClientShellshell=ClientShell(cloud_file='clouds.yaml',cloud='test')# Build a dictionary of the required arguements/options and their parameters.# Each key is command option and the value is the parameter.server_params=dict(name="ccit_test_client",image="rhel-7.5-server-x86_64-released",flavor="m1.small",key_name="db2-test",network=["test_private_network"],wait=True)# To create a server using the above define dict I simply access# the compute instance and us the server_create functionresults=shell.compute.server_create(server_params)Example 2fromospclientsdkimportClientShellshell=ClientShell(cloud_file='clouds.yaml',cloud='test')# Build a dictionary of the required arguements/options and their parameters.# Each key is command option and the value is the parameter.trunk_port_params=dict(name="test_compute_trunk",parent_port="test_port",subport=[dict(port="dummy_port",segmentation_type="vlan",segmentation_id=2007)])# To create a network trunk port using the above defined dict I simply access# the neutronclient instance and us the network_trunk_create functionresults=shell.neutronclient.network_trunk_create(trunk_port_params)Mid Level APIYou can use therun_commandto to supply the command
(using the underscore version of the command) and a dictionary options and it's parameters.This can come in handy in scenarios where it's quite possible that other openstackclient
plugins have been installed after the clientshell has been initialized. But you still want
to take advantage of supplying the command options and arguments as a dictionary.fromospclientsdkimportClientShellshell=ClientShell(cloud_file='clouds.yaml',cloud='test')# Build a dictionary of the required arguements/options and their parameters.# Each key is command option and the value is the parameter.trunk_port_params=dict(name="test_compute_trunk",parent_port="test_port",subport=[dict(port="dummy_port",segmentation_type="vlan",segmentation_id=2007)])# To create a network trunk port using the above defined dict I# use I pass in the command as a string and the options as a dictionaruresults=shell.run_command('network_trunk_create',trunk_port_params)Low Level APIYou can use the functionrun_raw_commandto explicitly run full commands. This will
allow you to pass in a string directly.This commmand might be useful if there are problems
with the clientshell normalizing the options or if you want to leverage the underlying shell to
chain together commands and do some complex processing without having to setup
subprocess boilerplate code yourself.Note since we aren't doing any string checking make sure you aren't passing in anything unsafe
for the underlying shell to execute. Also make sure to escape your command properly.fromospclientsdkimportClientShellshell=ClientShell(cloud_file='clouds.yaml',cloud='test')# Pass in a string representing a string commandresults=shell.run_raw_command('openstack server show -f json')OutputWhen the ospclientsdk executes it will return back
to you a dictionary. It will contain the following keys:rcstdoutstderrYou can use the rc value to determine if the command passed (0) or failed (1) and how to respond to
either scenario. The stdout key will always be deserialized into a dictionary so that
it can be easily manipulated and accessed. The stderr will typically always be a text string.Running openstack commands remotelyThere are use cases where it's useful to run the commands remotely on a test driver or bastion host.
The SDK provides aremote_shellcontext that can forward all CLI commands to the desired host without
a lot of extra boilerplate code. Before using this context first install the necessary ssh package:$pipinstallospclientsdk['remote_shell']Next it's recommended you will load your ssh agent up with a key appropriate to the target client host.Then you can start using it. Below are some examplesfromospclientsdkimportClientShell,remote_shellshell=ClientShell(cloud_file='clouds.yaml',cloud='test')# Build a dictionary of the required arguements/options and their parameters.# Each key is command option and the value is the parameter.server_params=dict(res="ccit_test_client",image="rhel-7.5-server-x86_64-released",flavor="m1.small",key_name="db2-test",network=["test_private_network"],wait=True)# Here is an example where we log into a remote host using user 'cloud-user' and a key file# using the high level apiwithremote_shell(hostname="10.x.x.x",username="cloud-user",key_file="keys/test-key"):results=shell.compute.server_create(server_params)# Here is an example running raw commands to a remote host using the FQDN and 'fedora' user# but we've specified a client path for where to look for the 'openstack' binary since it is# not in the $PATH on the remote host. This comes in useful if you've installed the client# in a virtualenv on the remote host.withremote_shell(hostname="host.example.com",username="fedora",key_file="keys/test-key",client_path="/home/fedora/cbn/bin"):results=shell.run_raw_command('openstack server show -f json')