Python SDK for vCloud Air
Project description
README
vCloud Air lightweight Python SDK
This 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/
Requirements
Python 3.4+
Requests 2.10+
Installation
Run pip install vcloudair to download and install the package.
Modules
ANS (Advanced Network Services)
This module works with the Advanced Network Services API. Current classes include:
ANSFirewall
ANSNat
ANSIPSec
These allow retrieving, modifying, adding, and saving configurations for the Firewall and NAT sections, respectively.
Use the config_data property 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:
DisasterRecovery
The 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 class
Metrics
This 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.
Metrics
Query
The 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:
VMQuery
EdgeGatewayQueury
VAppQuery
VAppTemplateQuery
OrgVdcQuery
Session
This 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.
VCASession
VCAODSession
The 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 Examples
Logging Into vCloud Air
This is using the VPC/Dedicated login session. NOT On-Demand!
from vcloudair import VCASession
sess = VCASession('5.6', <username>, <password>)
sess.login()
#To show a list of available Orgs you can use the property vdc_names
print(sess.vdc_names)
#Membership testing also works
'orgname' in sess.vdc_names #True / False
#Alternatively, login() can be called with an org name and return the
#org data
sess.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 org
org_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 instance
token – The vCD authorization token
org_uuid – The UUID of the vDC itself
auth-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 called
Gathering Metrics
All metrics show up in ~60-second intervals. So, pulling the last 10 minutes worth of metrics will give you ~10 records/timestamps.
from vcloudair import Metrics
#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'])
#OR
new_metrics = Metrics(org_info) #Passing the org_info dict directly into the class
#OR
vms = ['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 Org
new_metrics.set_relative_interval('HOUR', 1) #Previous 1 hour
new_metrics.set_metric_filters('cpu.ready.summation') #Limit the metric results to only CPU ready
#Add 2 additional filters without clearing the previous
new_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']
Querying Edges
Standard 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 value
results['item_uuid']['field']
Query types also have a find_by_name('name') method which returns a list of UUIDs that have a matching ‘name’ attribute to the string passed into the method.
from vcloudair import EdgeGatewayQuery
egwq = EdgeGatewayQuery(org_info)
egwq.execute() #Run the query
print(egwq.results) #All results are stored in the results instance variable
egwq.set_fields('applicable', 'query', 'field', 'names') #vCD docs discuss query fields
egwq.execute() #Execute the query again to add the fields to results
edge_uuids = egwq.find_by_name('edge_name')
Retrieving ANS Firewall Configuration
NAT configuration works the same as the Firewall. Iteration and retrieving rules is also done using slicing or index-based calls as shown below.
from vcloudair import ANSFirewall
fw = ANSFirewall('edge-UUID', org_info)
fw.get_config()
fw[0] #Retrieve the first rule
del fw[2] #Delete the rule at index 2
for rule in fw: #Iterate through the rules
print(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 Configuration
fw.save_config() #Pushes the config back to the server via API
Adding an IPSec VPN
from vcloudair import ANSIPSec
ipsec = 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 algorithm
ipsec.save_config()
Initiating A Full DR Failover Test
from vcloudair import VCAODSession, DisasterRecovery
sesh = VCAODSession('5.7', 'username', 'password')
print('Logging into On-Demand')
sesh.login()
#Print out the instance list and their indexes
sesh.show_instance_list()
print('Logging into DR Instance')
instance_data = sesh.login_to_instance(0) #In this example, instance 0 is the DR instance
dr = DisasterRecovery(instance_data)
print('Retrieving Replications')
dr.retrieve_replications()
print('Testing Failover')
dr.do_test_failover(power_on=True, total=True)
#... Wait appropriate time
dr.do_test_cleanup(total=True)
Changelog
Version 0.5 (2016-09-30)
New Features
Added action_errors member to the DisasterRecovery class. 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. The VCASession method login now accepts an optional vcd_url parameter.
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.
Bugfixes
Added 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.
Misc
API documentation is now available
Version 0.4 (2016-09-22)
Improvements
DisasterRecovery class methods do_failover, do_test_failover, and do_test_cleanup now 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 Features
DisasterRecovery method dump_replication_details will 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.
Bugfixes
Added 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 PyPI
Improvements
Cleaned up the On-Demand instance display table by adding friendly names and region information
Misc
Converted MD files to RST format
Version 0.2 (2016-09-09)
New Features
Added 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 class DisasterRecovery
Version 0.1
Initial Release
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
File details
Details for the file vcloudair-0.5.tar.gz
.
File metadata
- Download URL: vcloudair-0.5.tar.gz
- Upload date:
- Size: 28.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 49ebcaa6a83d594373f41058fbacee5e9c688e3c347866d3700419ffff031406 |
|
MD5 | 71cea675332dc7fe88dc7fd8cf122f94 |
|
BLAKE2b-256 | 47a90611d492a7039ae043ee7e9c54374c1d3b89833f5afdd0e54421962c076c |