{ "info": { "author": "Scott Schaefer", "author_email": "sschaefer@vmware.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Natural Language :: English", "Operating System :: MacOS", "Operating System :: Microsoft :: Windows", "Operating System :: POSIX :: Linux", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: Implementation :: CPython", "Topic :: Software Development :: Libraries :: Python Modules", "Topic :: System :: Systems Administration" ], "description": "README\n======\n\nvCloud Air lightweight Python SDK\n---------------------------------\n\nThis is far from a complete vCloud Air (vCA) SDK. However, it does\nprovide easier access to the newer API features, specifically ANS and\nMetrics. It also utilizes the newer and proper login process for vCA\nrather than vCD.\n\nThere is no guarantee of functionality and/or updates. This is updated\nand enhanced as I need the functionality. If there is something I never\nuse within the API, it's unlikely that it will make its way into this\nSDK.\n\nDocumentation: http://vcloudair.readthedocs.io/en/latest/\n\nRequirements\n------------\n\n- Python 3.4+\n- Requests 2.10+\n\nInstallation\n------------\n\nRun ``pip install vcloudair`` to download and install the package.\n\nModules\n-------\n\nANS (Advanced Network Services)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThis module works with the Advanced Network Services API. Current\nclasses include:\n\n- ``ANSFirewall``\n- ``ANSNat``\n- ``ANSIPSec``\n\nThese allow retrieving, modifying, adding, and saving configurations for\nthe Firewall and NAT sections, respectively.\n\nUse the ``config_data`` property to access the raw JSON/Dict containing\nall information for the ANS section, including the global config\nproperties.\n\nDR (Disaster Recovery)\n~~~~~~~~~~~~~~~~~~~~~~\n\nThis module is for Disaster Recovery 2.x (DRaaS) within vCloud Air.\nCurrent classes include:\n\n- ``DisasterRecovery``\n\nThe module allows for retrieving a list of DR replications and\ninitiating test failovers, test recoveries, and actual failovers.\n\n**Note: Use with the On-Demand session class**\n\nMetrics\n~~~~~~~\n\nThis module works with the newer Metrics API for vCloud Air VPCs and\nDCs. A link to the metrics documentation is below in the metrics usage\nexample.\n\n- ``Metrics``\n\nQuery\n~~~~~\n\nThe classic vCD API has a query system that allows users to query\nrecords for a number of types within the system. These records can be\ntraversed as resources. However, this library does not include traversal\nof resource HREF records.\n\nQueries can be helpful to find out name<->UUID matches, as well a\ngeneral count of resources and some basic information (using the fields\nparameter).\n\nCurrent canned query classes include:\n\n- ``VMQuery``\n- ``EdgeGatewayQueury``\n- ``VAppQuery``\n- ``VAppTemplateQuery``\n- ``OrgVdcQuery``\n\nSession\n~~~~~~~\n\nThis module handles the basic login process for vCA and vCD. OAUTH\ntokens are generated for vCloud Air and for any Org a user wants to log\ninto.\n\n- ``VCASession``\n- ``VCAODSession``\n\nThe VCA session refers to the login session used with VPC and Dedicated\nclouds.\n\nThe VCA OD session refers to the On-Demand platform and its related\nlogin session and protocols.\n\nUsage Examples\n--------------\n\nLogging Into vCloud Air\n~~~~~~~~~~~~~~~~~~~~~~~\n\nThis is using the VPC/Dedicated login session. **NOT On-Demand!**\n\n.. code-block:: python\n\n from vcloudair import VCASession\n\n sess = VCASession('5.6', , )\n sess.login()\n\n #To show a list of available Orgs you can use the property vdc_names\n print(sess.vdc_names)\n\n #Membership testing also works\n 'orgname' in sess.vdc_names #True / False\n\n #Alternatively, login() can be called with an org name and return the\n #org data\n\n sess.login('orgname1')\n\n #The difference between login() and login_to_vdc() is that the latter\n #will not generate a new VCA token. Only a new/additional vCD token for\n #the org specified.\n\n sess.login_to_vdc('orgname2')\n org_info = sess.login_to_vdc('orgname3') #Assigns the org data immediately\n\n #To retrieve the org data from the session later, use the name of the org\n org_info = sess['orgname3']\n\nOrganization info stores five pieces of data in a dictionary. The keys\nare as follows:\n\n- vcdurl -- The base VCD URL for the instance\n- token -- The vCD authorization token\n- org\\_uuid -- The UUID of the vDC itself\n- auth-header -- The name of the authorization header that should be\n used with the token: 'x-vcloud-authorization' in all cases so far.\n- version -- The version of the API called\n\nGathering Metrics\n~~~~~~~~~~~~~~~~~\n\nAll metrics show up in ~60-second intervals. So, pulling the last 10\nminutes worth of metrics will give you ~10 records/timestamps.\n\n.. code-block:: python\n\n from vcloudair import Metrics\n\n #Using org_info variable from above...\n #Specifying collection of metrics across the entire VDC (all VMs)\n new_metrics = Metrics(vcdurl=org_info['vcdurl'], token=org_info['token'],\n org_uuid=org_info['org_uuid'])\n\n #OR\n\n new_metrics = Metrics(org_info) #Passing the org_info dict directly into the class\n\n #OR\n\n vms = ['vm-UUID1', 'vm-UUID2']\n new_metrics = Metrics(org_info, vm_uuids=vms) #Pull only 2 VM metrics.\n\n #Passing in VM UUIDs will override passing in an entire Org\n\n new_metrics.set_relative_interval('HOUR', 1) #Previous 1 hour\n new_metrics.set_metric_filters('cpu.ready.summation') #Limit the metric results to only CPU ready\n\n #Add 2 additional filters without clearing the previous\n new_metrics.add_metric_filters('cpu.usage.average', 'cpu.idle.summation')\n\n new_metrics.collect() #Makes the API call\n\n #Data is stored in the metric_data instance variable\n #metric_data['vmUUID']['timestamp']['metric-name']\n\n`Full Metrics\nDocs `_\n\nQuerying Edges\n~~~~~~~~~~~~~~\n\nStandard query results for all query types include UUID and Name fields\nonly. The UUID is used as the dictionary key with all other fields\nstored in a subsequent dictionary as the value\n\n``results['item_uuid']['field']``\n\nQuery types also have a ``find_by_name('name')`` method which returns a\nlist of UUIDs that have a matching 'name' attribute to the string passed\ninto the method.\n\n.. code-block:: python\n\n from vcloudair import EdgeGatewayQuery\n\n egwq = EdgeGatewayQuery(org_info)\n egwq.execute() #Run the query\n\n print(egwq.results) #All results are stored in the results instance variable\n\n egwq.set_fields('applicable', 'query', 'field', 'names') #vCD docs discuss query fields\n egwq.execute() #Execute the query again to add the fields to results\n\n edge_uuids = egwq.find_by_name('edge_name')\n\n`vCD Query\nDocumentation `_\n\nRetrieving ANS Firewall Configuration\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nNAT configuration works the same as the Firewall. Iteration and\nretrieving rules is also done using slicing or index-based calls as\nshown below.\n\n.. code-block:: python\n\n from vcloudair import ANSFirewall\n\n fw = ANSFirewall('edge-UUID', org_info)\n fw.get_config()\n\n fw[0] #Retrieve the first rule\n del fw[2] #Delete the rule at index 2\n for rule in fw: #Iterate through the rules\n print(rule)\n\nAdding A Rule\n~~~~~~~~~~~~~\n\n.. code-block:: python\n\n #The first three arguments do not have default vaules. The remaining ones do.\n fw.add_rule('Rule Name', source='external', destination='23.45.67.89', action='accept',\n protocol='tcp', source_port='any', dest_port=80)\n\nSaving ANS Firewall Configuration\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: python\n\n fw.save_config() #Pushes the config back to the server via API\n\nAdding an IPSec VPN\n~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: python\n\n from vcloudair import ANSIPSec\n\n ipsec = ANSIPSec('edge-UUID', org_info)\n ipsec.get_config()\n ipsec.add_psk_tunnel('TestTunnel', local_id='23.92.255.65',\n local_ip='23.92.255.65',\n peer_id='195.177.229.88',\n peer_ip='195.177.229.88',\n local_subnets='10.0.50.0/24,10.0.51.0/24',\n peer_subnets=['10.0.40.0/24','10.0.41.0/24'],\n psk='ABcdEFghIJklMNopQRstUVwxYZ1234567890')\n\n # Optional, defaulted, parameters include DH Group, PFS, and encryption algorithm\n\n ipsec.save_config()\n\nInitiating A Full DR Failover Test\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: python\n\n from vcloudair import VCAODSession, DisasterRecovery\n\n sesh = VCAODSession('5.7', 'username', 'password')\n print('Logging into On-Demand')\n sesh.login()\n\n #Print out the instance list and their indexes\n sesh.show_instance_list()\n\n print('Logging into DR Instance')\n instance_data = sesh.login_to_instance(0) #In this example, instance 0 is the DR instance\n\n dr = DisasterRecovery(instance_data)\n\n print('Retrieving Replications')\n dr.retrieve_replications()\n\n print('Testing Failover')\n dr.do_test_failover(power_on=True, total=True)\n #... Wait appropriate time\n dr.do_test_cleanup(total=True)\n\n\n.. :changelog:\n\nChangelog\n=========\n\nVersion 0.5 (2016-09-30)\n------------------------\n\n**New Features**\n\n- Added ``action_errors`` member to the ``DisasterRecovery`` class. After an\n action has completed (fail, test, cleanup), this list will be populated with\n any individual actions that are suspected to have failed.\n\n This is a list of tuples containing (VM-UUID, VM-Name, Message) for each\n suspected failure.\n\n This list is cleared any time a new action is executed.\n\n- Added the ability to log directly into a vCD instance, bypassing the vCA\n portal if desired. The ``VCASession`` method ``login`` now accepts an\n optional ``vcd_url`` parameter.\n\n **Note:** There exists potential confusion between logging in via vCD vs vCA.\n vCA accepts the VDC name whereas vCD accepts the Org name. Usually these are\n the same but they may be different, especially if a VDC has been renamed in\n the past.\n\n**Bugfixes**\n\n- Added undocumented header in DR Failover call (thanks VMware Documentation for\n being incomplete)\n- Added de-duplication to DR actions performed so the same VM can't be targetted\n more than once in a particular action call.\n\n**Misc**\n\n- API documentation is now available\n\nVersion 0.4 (2016-09-22)\n------------------------\n\n**Improvements**\n\n- ``DisasterRecovery`` class methods ``do_failover``, ``do_test_failover``, and\n ``do_test_cleanup`` now support multiple UUIDs being submitted to the calls.\n E.g.: ``DisasterRecovery.do_failover('uuid1', 'uuid2', 'uuid3')``.\n- Switched to a threaded model for failover and recovery tasks. Failover and\n recovery tasks use the same task queue for the threads. So the total number of\n concurrent operations is a combined total of both failover and recovery. Any\n additional operations are simply added to the queue. The queue is processed\n in a First-In-First-Out fashion.\n- Switched to a threaded model when retrieving replications. This does not use\n the same queue as the DR operations above. Currently it is unbounded as it\n happens once during the login process. Will determine if this should be moved\n to a pool model instead.\n\n**New Features**\n\n- ``DisasterRecovery`` method ``dump_replication_details`` will allow output of\n all DR replications for a particular instance to be saved to a file. This is\n to help with the creation of automation tasks by showing a match between VM\n name and UUID.\n\n**Bugfixes**\n\n- Added a timeout to the task monitoring (10min default) so the blocking call\n for failovers and recovery won't hang indefinitely if a task is hung in vCD.\n\nVersion 0.3 (2016-09-12)\n------------------------\n\n- Published to PyPI\n\n**Improvements**\n\n- Cleaned up the On-Demand instance display table by adding friendly names and\n region information\n\n**Misc**\n\n- Converted MD files to RST format\n\nVersion 0.2 (2016-09-09)\n------------------------\n\n**New Features**\n\n- Added a new session class for logging into On-Demand instances. This\n includes DR 2.x (DRaaS)\n- Added a new module for Disaster Recovery and a new class\n ``DisasterRecovery``\n\nVersion 0.1\n-----------\n\n- Initial Release\n", "description_content_type": null, "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://gitlab.com/scottjs/vcloudair", "keywords": "", "license": "MIT", "maintainer": "", "maintainer_email": "", "name": "vcloudair", "package_url": "https://pypi.org/project/vcloudair/", "platform": "", "project_url": "https://pypi.org/project/vcloudair/", "project_urls": { "Homepage": "https://gitlab.com/scottjs/vcloudair" }, "release_url": "https://pypi.org/project/vcloudair/0.5/", "requires_dist": null, "requires_python": "", "summary": "Python SDK for vCloud Air", "version": "0.5" }, "last_serial": 2374025, "releases": { "0.3": [ { "comment_text": "", "digests": { "md5": "e30858e0e995edcf0a21f7d0ec49bb6c", "sha256": "ec82c00da8c8e3414adac43284579b0660b481a922e0e42160a52c4b3c4eb771" }, "downloads": -1, "filename": "vcloudair-0.3.tar.gz", "has_sig": false, "md5_digest": "e30858e0e995edcf0a21f7d0ec49bb6c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 21536, "upload_time": "2016-09-12T19:18:41", "url": "https://files.pythonhosted.org/packages/9c/ad/ba87472ebc83f6d8f7defcde66a04e07727aac553f252b8cfe5324a354a2/vcloudair-0.3.tar.gz" } ], "0.4": [ { "comment_text": "", "digests": { "md5": "93857bf895c194f6e92539a9bd57a348", "sha256": "7933187b6e9cd465f9a81243464a9b9601db98a7bc946b4e1643fc053fb3bfe5" }, "downloads": -1, "filename": "vcloudair-0.4.tar.gz", "has_sig": false, "md5_digest": "93857bf895c194f6e92539a9bd57a348", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 23434, "upload_time": "2016-09-22T17:33:56", "url": "https://files.pythonhosted.org/packages/6f/31/669babe06e79f2643937533bfff68abd097a84bfdc79c61988bf5e29a553/vcloudair-0.4.tar.gz" } ], "0.5": [ { "comment_text": "", "digests": { "md5": "71cea675332dc7fe88dc7fd8cf122f94", "sha256": "49ebcaa6a83d594373f41058fbacee5e9c688e3c347866d3700419ffff031406" }, "downloads": -1, "filename": "vcloudair-0.5.tar.gz", "has_sig": false, "md5_digest": "71cea675332dc7fe88dc7fd8cf122f94", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 28113, "upload_time": "2016-09-30T19:54:03", "url": "https://files.pythonhosted.org/packages/47/a9/0611d492a7039ae043ee7e9c54374c1d3b89833f5afdd0e54421962c076c/vcloudair-0.5.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "71cea675332dc7fe88dc7fd8cf122f94", "sha256": "49ebcaa6a83d594373f41058fbacee5e9c688e3c347866d3700419ffff031406" }, "downloads": -1, "filename": "vcloudair-0.5.tar.gz", "has_sig": false, "md5_digest": "71cea675332dc7fe88dc7fd8cf122f94", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 28113, "upload_time": "2016-09-30T19:54:03", "url": "https://files.pythonhosted.org/packages/47/a9/0611d492a7039ae043ee7e9c54374c1d3b89833f5afdd0e54421962c076c/vcloudair-0.5.tar.gz" } ] }