Package: vcloudair
READMEvCloud Air lightweight Python SDKThis is far from a complete vCloud Air (vCA) SDK. However, it does
provide easier access to the newer API features, specifically ANS and
Metrics. It also utilizes the newer and proper login process for vCA
rather than vCD.There is no guarantee of functionality and/or updates. This is updated
and enhanced as I need the functionality. If there is something I never
use within the API, it’s unlikely that it will make its way into this
SDK.Documentation:http://vcloudair.readthedocs.io/en/latest/RequirementsPython 3.4+Requests 2.10+InstallationRunpip install vcloudairto download and install the package.ModulesANS (Advanced Network Services)This module works with the Advanced Network Services API. Current
classes include:ANSFirewallANSNatANSIPSecThese allow retrieving, modifying, adding, and saving configurations for
the Firewall and NAT sections, respectively.Use theconfig_dataproperty to access the raw JSON/Dict containing
all information for the ANS section, including the global config
properties.DR (Disaster Recovery)This module is for Disaster Recovery 2.x (DRaaS) within vCloud Air.
Current classes include:DisasterRecoveryThe module allows for retrieving a list of DR replications and
initiating test failovers, test recoveries, and actual failovers.Note: Use with the On-Demand session classMetricsThis module works with the newer Metrics API for vCloud Air VPCs and
DCs. A link to the metrics documentation is below in the metrics usage
example.MetricsQueryThe classic vCD API has a query system that allows users to query
records for a number of types within the system. These records can be
traversed as resources. However, this library does not include traversal
of resource HREF records.Queries can be helpful to find out name<->UUID matches, as well a
general count of resources and some basic information (using the fields
parameter).Current canned query classes include:VMQueryEdgeGatewayQueuryVAppQueryVAppTemplateQueryOrgVdcQuerySessionThis module handles the basic login process for vCA and vCD. OAUTH
tokens are generated for vCloud Air and for any Org a user wants to log
into.VCASessionVCAODSessionThe VCA session refers to the login session used with VPC and Dedicated
clouds.The VCA OD session refers to the On-Demand platform and its related
login session and protocols.Usage ExamplesLogging Into vCloud AirThis is using the VPC/Dedicated login session.NOT On-Demand!fromvcloudairimportVCASessionsess=VCASession('5.6',<username>,<password>)sess.login()#To show a list of available Orgs you can use the property vdc_namesprint(sess.vdc_names)#Membership testing also works'orgname'insess.vdc_names#True / False#Alternatively, login() can be called with an org name and return the#org datasess.login('orgname1')#The difference between login() and login_to_vdc() is that the latter#will not generate a new VCA token. Only a new/additional vCD token for#the org specified.sess.login_to_vdc('orgname2')org_info=sess.login_to_vdc('orgname3')#Assigns the org data immediately#To retrieve the org data from the session later, use the name of the orgorg_info=sess['orgname3']Organization info stores five pieces of data in a dictionary. The keys
are as follows:vcdurl – The base VCD URL for the instancetoken – The vCD authorization tokenorg_uuid – The UUID of the vDC itselfauth-header – The name of the authorization header that should be
used with the token: ‘x-vcloud-authorization’ in all cases so far.version – The version of the API calledGathering MetricsAll metrics show up in ~60-second intervals. So, pulling the last 10
minutes worth of metrics will give you ~10 records/timestamps.fromvcloudairimportMetrics#Using org_info variable from above...#Specifying collection of metrics across the entire VDC (all VMs)new_metrics=Metrics(vcdurl=org_info['vcdurl'],token=org_info['token'],org_uuid=org_info['org_uuid'])#ORnew_metrics=Metrics(org_info)#Passing the org_info dict directly into the class#ORvms=['vm-UUID1','vm-UUID2']new_metrics=Metrics(org_info,vm_uuids=vms)#Pull only 2 VM metrics.#Passing in VM UUIDs will override passing in an entire Orgnew_metrics.set_relative_interval('HOUR',1)#Previous 1 hournew_metrics.set_metric_filters('cpu.ready.summation')#Limit the metric results to only CPU ready#Add 2 additional filters without clearing the previousnew_metrics.add_metric_filters('cpu.usage.average','cpu.idle.summation')new_metrics.collect()#Makes the API call#Data is stored in the metric_data instance variable#metric_data['vmUUID']['timestamp']['metric-name']Full Metrics
DocsQuerying EdgesStandard query results for all query types include UUID and Name fields
only. The UUID is used as the dictionary key with all other fields
stored in a subsequent dictionary as the valueresults['item_uuid']['field']Query types also have afind_by_name('name')method which returns a
list of UUIDs that have a matching ‘name’ attribute to the string passed
into the method.fromvcloudairimportEdgeGatewayQueryegwq=EdgeGatewayQuery(org_info)egwq.execute()#Run the queryprint(egwq.results)#All results are stored in the results instance variableegwq.set_fields('applicable','query','field','names')#vCD docs discuss query fieldsegwq.execute()#Execute the query again to add the fields to resultsedge_uuids=egwq.find_by_name('edge_name')vCD Query
DocumentationRetrieving ANS Firewall ConfigurationNAT configuration works the same as the Firewall. Iteration and
retrieving rules is also done using slicing or index-based calls as
shown below.fromvcloudairimportANSFirewallfw=ANSFirewall('edge-UUID',org_info)fw.get_config()fw[0]#Retrieve the first ruledelfw[2]#Delete the rule at index 2forruleinfw:#Iterate through the rulesprint(rule)Adding A Rule#The first three arguments do not have default vaules. The remaining ones do.fw.add_rule('Rule Name',source='external',destination='23.45.67.89',action='accept',protocol='tcp',source_port='any',dest_port=80)Saving ANS Firewall Configurationfw.save_config()#Pushes the config back to the server via APIAdding an IPSec VPNfromvcloudairimportANSIPSecipsec=ANSIPSec('edge-UUID',org_info)ipsec.get_config()ipsec.add_psk_tunnel('TestTunnel',local_id='23.92.255.65',local_ip='23.92.255.65',peer_id='195.177.229.88',peer_ip='195.177.229.88',local_subnets='10.0.50.0/24,10.0.51.0/24',peer_subnets=['10.0.40.0/24','10.0.41.0/24'],psk='ABcdEFghIJklMNopQRstUVwxYZ1234567890')# Optional, defaulted, parameters include DH Group, PFS, and encryption algorithmipsec.save_config()Initiating A Full DR Failover TestfromvcloudairimportVCAODSession,DisasterRecoverysesh=VCAODSession('5.7','username','password')print('Logging into On-Demand')sesh.login()#Print out the instance list and their indexessesh.show_instance_list()print('Logging into DR Instance')instance_data=sesh.login_to_instance(0)#In this example, instance 0 is the DR instancedr=DisasterRecovery(instance_data)print('Retrieving Replications')dr.retrieve_replications()print('Testing Failover')dr.do_test_failover(power_on=True,total=True)#... Wait appropriate timedr.do_test_cleanup(total=True)ChangelogVersion 0.5 (2016-09-30)New FeaturesAddedaction_errorsmember to theDisasterRecoveryclass. After an
action has completed (fail, test, cleanup), this list will be populated with
any individual actions that are suspected to have failed.This is a list of tuples containing (VM-UUID, VM-Name, Message) for each
suspected failure.This list is cleared any time a new action is executed.Added the ability to log directly into a vCD instance, bypassing the vCA
portal if desired. TheVCASessionmethodloginnow accepts an
optionalvcd_urlparameter.Note:There exists potential confusion between logging in via vCD vs vCA.
vCA accepts the VDC name whereas vCD accepts the Org name. Usually these are
the same but they may be different, especially if a VDC has been renamed in
the past.BugfixesAdded undocumented header in DR Failover call (thanks VMware Documentation for
being incomplete)Added de-duplication to DR actions performed so the same VM can’t be targetted
more than once in a particular action call.MiscAPI documentation is now availableVersion 0.4 (2016-09-22)ImprovementsDisasterRecoveryclass methodsdo_failover,do_test_failover, anddo_test_cleanupnow support multiple UUIDs being submitted to the calls.
E.g.:DisasterRecovery.do_failover('uuid1','uuid2', 'uuid3').Switched to a threaded model for failover and recovery tasks. Failover and
recovery tasks use the same task queue for the threads. So the total number of
concurrent operations is a combined total of both failover and recovery. Any
additional operations are simply added to the queue. The queue is processed
in a First-In-First-Out fashion.Switched to a threaded model when retrieving replications. This does not use
the same queue as the DR operations above. Currently it is unbounded as it
happens once during the login process. Will determine if this should be moved
to a pool model instead.New FeaturesDisasterRecoverymethoddump_replication_detailswill allow output of
all DR replications for a particular instance to be saved to a file. This is
to help with the creation of automation tasks by showing a match between VM
name and UUID.BugfixesAdded a timeout to the task monitoring (10min default) so the blocking call
for failovers and recovery won’t hang indefinitely if a task is hung in vCD.Version 0.3 (2016-09-12)Published to PyPIImprovementsCleaned up the On-Demand instance display table by adding friendly names and
region informationMiscConverted MD files to RST formatVersion 0.2 (2016-09-09)New FeaturesAdded a new session class for logging into On-Demand instances. This
includes DR 2.x (DRaaS)Added a new module for Disaster Recovery and a new classDisasterRecoveryVersion 0.1Initial Release