Ravello Python SDK

Overview

The Ravello Python SDK is a micro-SDK for using the Ravello service from the Python programming language. The focus is on providing a small set of bindings that doesn’t have any external dependencies. Some features are:

  • Supports Python 2.6, 2.7 and 3.3+.
  • No dependencies outside the standard library.
  • A minimal binding without a client-side object model. Objects and represented as simple dictionaries.
  • Should work on POSIX, Windows and Mac OSX.

Because there is no client-side object model, you should also read the Ravello API Reference. All object fields are documented there.

API

The Ravello SDK is implemented by the module ravello_sdk. The module is safe to be imported into your namespace:

from ravello_sdk import *

The module has the following contents:

Exceptions

class RavelloError

Exception used by RavelloClient.

Functions

random_luid()

Return a new random local ID.

update_luids(obj)

Update the locally unique IDs in obj.

The object must be a dict, or a list of dicts.

This replaces all “id” keys (directly or indirectly) below obj with an new random ID generated by random_luid(). This function is useful when adding VMs images to a new or existing application. Every entity in an application’s design must have a unique local ID. When you’re adding multiple VMs based on the same image, the IDs are copied and you need to use this function to ensure the VMs have unique local IDs again.

application_state(app)

Return the consolidated state for application app.

The app parameter must be a dict as returned by get_application().

The consolidated state for an application is the set of distinct states for its VMs. As special cases, None is returned if there are no VMs, and the single state is returned if there is exactly one state.

new_name(existing, prefix)

Return a name that is not in existing.

The existing parameter must be a sequence of strings, or dicts with a “name” key. It the latter case, it is typically a list returned by one of the “get all” functions like RavelloClient.get_applications() or :meth:~RavelloClient.get_blueprints`.

The unique name is generated by appending a number to prefix.

Classes

class RavelloClient(username=None, password=None, url=None, timeout=None, retries=None, proxy_url=None, eph_token=None, identity_domain=None)

A client for the Ravello API.

The client is a thin wrapper around the Ravello RESTful API. The client manages a single HTTPS connection, and implements login, redirect and retry functionality. A single generic request() method is provided to issue API requests.

On top of this, most existing RESTful API calls are mapped as methods on this class. These mapped methods are simple wrappers around the generic request() method. Some general comments on this mapping:

  • The calls are named “<method>_<resource>”, for example “create_keypair()” and “get_blueprints()”. A method is always an English verb, while a resource is can be a singular or plural Englush noun.
  • The standard methods are “get”, “create”, “update” and “delete”. Not all methods are defined for all resources, and some resources have additional methods.
  • The available resources are “application”, “blueprint”, “image”, “keypair” and “vm”. The plural versions of these exist as well.
  • There is no client-side object model. The return value from any API call is simply the parsed JSON response.
  • Resources are returned as a dict or a list of dicts. A dict always represents a single object, and its key/value pairs correspond to the object’s attributes. Lists always represents multiple objects.
  • Objects are identifed by a numeric ID, which is always the key “id”.
  • All methods that accept an object ID either accept this parameter as a simple Python int, or alternatively as a dict with an “id” key containing the ID. In the latter case, the dict is typically returned previsouly by another API call.
  • HTTP response codes in the 4xx or 5xx range are considered errors, and are turned into RavelloError exceptions (except for 404 which results in a response of None).
url

The parsed URL of the API endpoint, which is a urllib.parse.SplitResult instance.

connected

Whether or not the client is connected to the API.

have_credentials

Whether or not credentials are available.

have_eph_access_token

whether or not ephemeral access token is available.

logged_in

Whether or not the client is logged in.

user_info

Return information about the current logged-in user.

connect(url=None, proxy_url=None, eph_token=None)

Connect to the API.

It is not mandatory to call this method. If this method is not called, the client will automatically connect when required.

login(username=None, password=None, identity_domain=None)

Login to the API.

This method performs a login to the API, and store the resulting authentication cookie in memory.

It is not mandatory to call this method. If this method is not called, the client will automatically login when required.

When the organization of the user has an identity domain, the user must specify it or include it in the username: <identity_domain>/<username>. When the organization doesnt have an identity domain use only the username.

logout()

Logout from the API. This invalidates the authentication cookie in case of username/password authentication, and in any case will force close the connection.

close()

Close the connection to the API.

request(method, path, entity=None, headers=None)

Issues a request to the API.

The parsed entity is returned, or a RavelloError exception is raised on error.

This method can be used in case a certain API call has not yet been added as a method.

reload(obj)

Reload the object obj.

The object must have been returned by the API, and must be a dict with an "_href" key.

wait_for(obj, cond, timeout=None)

Wait for a condition on obj to become true.

The object obj must be reloadable. See reload() for more details.

The condition cond must be a dict or a callable. If it is a dict, it lists the keys and values that the object must have. If it is a callable, it will be called with the object as an argument, and it should return True or False.

The timeout argument specifies the total time to wait. If not specified, it will default to the system call timeout passed to the constructor.

If the condition does not become true before the timeout, a RavelloError exception is raised.

get_application(app, aspect=None)

Return the application with ID app, or None if it does not exist.

The aspect parameter can be used to return the application only with the specified aspect (e.g., design, deployment, properties).

get_applications(filter=None)

Return a list with all applications. The filter argument can be used to return only a subset of the applications. See the description of the cond argument to wait_for().

create_application(app)

Create a new application.

The app parameter must be a dict describing the application to create.

The new application is returned.

update_application(app)

Update an existing application.

The app parameter must be the updated application. The way to update an application (or any other resource) is to first retrieve it, make the updates client-side, and then use this method to make the update.

The updated application is returned.

update_vm(app, vm)

Update an existing vm.

The app parameter is the app containing the vm to update.

The vm parameter must be the updated vm. The way to update a vm (or any other resource) is to first retrieve it, make the updates client-side, and then use this method to make the update.

The updated vm is returned.

delete_application(app)

Delete an application with ID app.

publish_application(app, req={'optimizationLevel': 'COST_OPTIMIZED'})

Publish the application with ID app.

The req parameter, if provided, must be a dict with publish parameters.

start_application(app, req=None)

Start the application with ID app.

The req parameter, if provided, must be a dict with start parameters.

stop_application(app, req=None)

Stop the application with ID app.

The req parameter, if provided, must be a dict with stop parameters.

restart_application(app, req=None)

Restart the application with ID app.

The req parameter, if provided, must be a dict with restart parameters.

publish_application_updates(app, autostart=True)

Publish updates for the application with ID app.

set_application_expiration(app, req)

Set the expiration for the application with ID app.

The req parameter must be a dict describing the new expiration.

get_application_publish_locations(app, req=None)

Get a list of locations where app can be published.

get_blueprint_publish_locations(bp, req=None)

Get a list of locations where bp can be published.

get_vm(app, vm, aspect=None)

Return the vm with ID vm in the appplication with ID app, or None if it does not exist.

The aspect parameter (design, deployment) can be used to return the vm as designed or as deployed in the cloud.

get_vms(app, filter=None, level='design')

Return a list with all vms (for a given app).

The filter argument can be used to return only a subset of the applications. See the description of the cond argument to wait_for().

start_vm(app, vm)

Start the VM with ID vm in the application with ID app.

stop_vm(app, vm)

Stop the VM with ID vm in the application with ID app.

poweroff_vm(app, vm)

Power off the VM with ID vm in the application with ID app.

restart_vm(app, vm)

Restart the VM with ID vm in the application with ID app.

redeploy_vm(app, vm)

Redeploy the VM with ID vm in the application with ID app.

repair_vm(app, vm)

Repair the VM with ID vm in the application with ID app.

reset_disks_vm(app, vm)

Resets each disk of the VM with ID vm in the application with ID app.

get_vnc_url(app, vm)

Get the VNC URL for the VM with ID vm in the application with ID app.

get_detailed_charges_for_application(app, mode='deployment', deployment_options={})

Get the detailed hourly charges for an application. app is the application to get the charges for mode optional parameter, either ‘design’ or ‘deployment’ (default value) deployment_options optional parameter, should be non empty if and only if mode is being used, is a dict with the deployment optimizationLevel when querying for a design pricing. See the REST API docs for details on possible values.

get_vm_fqdn(app, vm)

Get the FQDN for a deployed VM app is the applicaiton/application-id of the VM vm is the VM/VM-id we’re querying for

get_vm_state(app, vm)

Get the state of a deployed VM (e.g. STARTED / STOPPED / ERROR / ….) app is the applicaiton/application-id of the VM vm is the VM/VM-id we’re querying for

get_vm_public_ips(app, vm)

Get the list of a VM’s public IPs app is the applicaiton/application-id of the VM vm is the VM/VM-id we’re querying for

is_application_published(app)

Is the application app published or draft?

add_library_vm_to_application(app, library_vm_id)

Add a VM from the library to an existing application design (note that you will still need to publish the update) app the application (object or ID) to add the library VM to library_vm_id the ID of the Library VM to add to the application

delete_vm_from_application(app, vm)

Deletes a single VM from an existing application’s design (note that you will still need to publish the update) app the application (object or ID) to delete the library VM from vm the VM to delete from the application

get_blueprint(bp)

Return the blueprint with ID bp, or None if it does not exist.

get_blueprints(filter=None)

Return a list with all blueprints.

The filter argument can be used to return only a subset of the applications. See the description of the cond argument to wait_for().

create_blueprint(bp)

Create a new blueprint.

The bp parameter must be a dict describing the blueprint to create.

The new blueprint is returned.

delete_blueprint(bp)

Delete the blueprint with ID bp.

get_detailed_charges_for_blueprint(bp, deployment_options={})

Estimate the detailed charges for an application deployed from this blueprint. bp is the blueprint to get the charges for deployment_options required parameter, is a dict with the deployment optimizationLevel when querying for a design pricing. See the REST API docs for details on possible values.

get_image(img)

Return the image with ID img, or None if it does not exist.

get_images(filter=None)

Return a list with all images.

The filter argument can be used to return only a subset of the images. See the description of the cond argument to wait_for().

create_image(image)

Create a new image.

The image parameter must be a dict describing the image to create.

The new image is returned.

update_image(img)

Update an existing image.

The img parameter must be the updated image. The updated image is returned.

delete_image(img)

Delete the image with ID img.

get_diskimage(img)

Return the disk image with ID img, or None if it does not exist.

get_diskimages(filter=None)

Return a list with all disk images.

The filter argument can be used to return only a subset of the disk images. See the description of the cond argument to wait_for().

create_diskimage(img)

Create a new disk image.

The img parameter must be a dict describing the disk image to create.

The new disk image is returned.

update_diskimage(img)

Update an existing image.

The img parameter must be the updated image. The updated disk image is returned.

delete_diskimage(img)

Delete the image with ID img.

get_keypair(kp)

Return the keypair with ID kp, or None if it does not exist.

get_keypairs(filter=None)

Return a list with all keypairs.

The filter argument can be used to return only a subset of the keypairs. See the description of the cond argument to wait_for().

create_keypair(kp)

Create a new keypair.

The kp parameter must be a dict describing the keypair to create.

The new blueprint is returned.

update_keypair(kp)

Update an existing keypair.

The kp parameter must be the updated keypair. The updated keypair is returned.

delete_keypair(kp)

Delete the keypair with ID kp.

generate_keypair()

Generate a new keypair and return it.

get_user(user)

Return the user with ID user, or None if it does not exist.

get_users(filter=None)

Return a list with all users.

The filter argument can be used to return only a subset of the users. See the description of the cond argument to wait_for().

invite_user(user)

Invite a new user.

The user parameter must be a dict describing the user to invite.

The new user is returned.

update_user(user, userId)

Update an existing user.

The user parameter must be the updated user. The way to update a user (or any other resource) is to first retrieve it, make the updates client-side, and then use this method to make the update. In this case, note however that you can only provide email, name, roles, and surname (and email cannot be changed).

The updated user is returned.

delete_user(user)

Delete a user with ID user.

changepw_user(passwords, user)

Change the password of a user with ID user.

The passwords parameter must be a dict describing the existing and new passwords.

get_billing(filter=None)

Return a list with all applications’ charges incurred since beginning of the month.

The filter argument can be used to return only a subset of the applications. See the description of the cond argument to wait_for().

get_billing_for_month(year, month)

Return a list with all applications’ charges incurred during the specified month and year.

get_events()

Return a list of all possible event names.

get_alerts()

Return a list of all alerts that user is registered to.

If user is an administrator, list contains all alerts that the organization is registered too.

create_alert(eventName, userId=None)

Registers a user to an alert.

User must be an administrator to specify a userId.

delete_alert(alertId)

Delete a specific userAlert.

Specifiy an alertId to unregister a user from it.

search_notifications(query)

Return list of notifications regarding given criteria.

The query parameter must be a dict describing the notifications to match. Technically, all 4 of the following params are optional: appId, notificationLevel, maxResults, dateRange

get_organization(org=None)

Return the authenticated user organization’s details.

The org parameter can be used to instead return details according to organization ID.

update_organization(org)

Update an organization’s details.

The org parameter must be the updated organization. The way to update an organization (or any other resource) is to first retrieve it, make the updates client-side, and then use this method to make the update.

The updated organization is returned.

get_permgroup(pg)

Return the permission group with ID pg, or None if it does not exist.

get_permgroups(filter=None)

Return a list with all permission groups.

The filter argument can be used to return only a subset of the permission groups. See the description of the cond argument to wait_for().

create_permgroup(pg)

Create a new permission group.

The pg parameter must be a dict describing the permission group to create.

The new permission group is returned.

update_permgroup(pg)

Update an existing permission group.

The pg parameter must be the updated permission group. The way to update a permission group (or any other resource) is to first retrieve it, make the updates client-side, and then use this method to make the update.

The updated permission group is returned.

delete_permgroup(pg)

Delete a permission group with ID pg.

get_users_in_permgroup(pg)

List all of the users in a permission group.

add_user_to_permgroup(pg, user)

Add a user to a permission group.

The user parameter must be a valid user id.

del_user_from_permgroup(pg, user)

Delete a user from a permission group.

The user parameter must be a valid user id.

get_permgroup_descriptors()

Return a list of resource permission descriptors.

create_elastic_ip(locationType, locationName, name=None, description=None)

Creates elastic Ip. Returns the ip

delete_elastic_ip(ip)
Parameters:ip – The ip to delete. In string format.
get_elastic_ips()
Returns:all the elastic ips
get_elastic_ip_locations()
Returns:all the possible locations for elastic ip
create_application_task(application, task_details)

Create and Schedule a new application task.

The task_details parameter is a dict describing the task to schedule

update_application_task(application, task, task_details)

Update an already scheduled application task.

The task parameter is the ID of the task to update The task_details parameter is a dict describing the task to schedule

get_application_tasks(application)

Return a list of the application’s scheduled tasks

get_application_task(application, task)

Return a specific application’s scheduled task

delete_application_task(application, task)

Delete a specific application’s scheduled task

delete_application_tasks(application)

Delete all scheduled tasks of an application

get_ephemeral_access_tokens()

Return a list of all ephemeral access tokens

get_ephemeral_access_token(token)

Return a specific ephemeral access token

create_ephemeral_access_token(token_details)

Creates a new ephemeral access token. The token_details parameter is a dict describing the ephemeral access token to create. This parameter has a mandatory field named name, as well as optional fields: - expirationTime - in millis since 1.1.1970 UTC - description - text - permissions - a list of permissions associated with the eph access token

update_ephemeral_access_token(token, token_details)

Updates an existing ephemeral access token. The token parameter is the ID of the token to update The token_details parameter is a dict describing the updated token details

delete_ephemeral_access_token(token)

Deletes an existing ephemeral access token. The token parameter is the ID of the token to delete

get_community(community)

Retrieves an existing community. The community parameter is the ID of the community to retrieve

get_communities()

Retrieves all communities.

get_cost_buckets(permissions='execute, update', skip_deleted=False)

Retrieves all cost buckets permissions - Possible values: execute, create, read, update, delete, share or ephemeral_access, or any combination of the above, comma separated. The returned list will be only buckets with user’s authentication plus defined permissions. skip_deleted - If False, list contains also deleted cost buckets.

get_cost_bucket(cost_bucket)

Retrieves an existing cost bucket. The cost_bucket parameter is the ID of the cost bucket to retrieve

create_cost_bucket(cost_bucket_details)

Creates a new cost bucket. The cost_bucket_details parameter is a dict describing the cost bucket to create. This parameter has a mandatory field named name, as well as optional fields: - description - The description of the cost bucket - parentId - The ID of the cost bucket parent, which is also a cost bucket. If this parameter is missing, the default parentId, “Organization”, is set.

update_cost_bucket(cost_bucket, cost_bucket_details)

Updates an existing cost bucket. The cost_bucket parameter is the ID of the cost bucket to update The cost_bucket_details parameter is a dict describing the cost bucket details

associate_resource_to_cost_bucket(cost_bucket, resource_details)

Associate Billed Resource to a Different Cost Bucket The cost_bucket parameter is the ID of the cost bucket the resource will be associated to The resource_details parameter is a dict describing the resource to associate details

describe_cost_bucket()

Describe Cost Bucket

get_cost_alert_definition(cost_alert_definition)

Returns a single cost alert definition according to its ID. The cost_alert_definition parameter is the ID of the cost alert definition to retrieve

get_cost_alert_definitions(cost_bucket)

Retrieves all the cost alert definitions for an existing cost bucket. The cost_bucket parameter is the ID of the cost bucket to retrieve

create_cost_alert_definition(cost_alert_definition_details)
Creates a new cost alert definition. In addition to permission to create cost alert definitions,
the user must also have READ permission on the aggregation parent, and READ permission on Billing Info.

The cost_alert_definition_details parameter is a dict describing the cost alert definition to create. This parameter has several mandatory fields: - aggregationTimeUnit - The duration of the aggregation. Possible values: daily, weekly, monthly, yearly, all_times. - costLimit - The limit in dollars. - aggregationParent - Possible values: “cost_bucket” or “application”. If “cost_bucket” is sent, an alert is sent when the quota for this bucket is exceeded. If “application” is sent, an alert is sent when the quota is exceeded for this application. - parentId - The ID of the cost_bucket / application in which the alert is defined. This parameter has several optional fields: - description - The description of the cost bucket - warningThreshold - The threshold for warning, as a percentage. - userIds - List of IDs of the users that will receive the messages when the configured quota is exceeded.

update_cost_alert_definition(cost_alert_definition, cost_alert_definition_details)

Updates a specific cost alert definition. The user should have the following permissions in order to complete this operation: UPDATE permission on cost alert definitions, READ permission on the aggregation parent (the cost bucket or application’s on which the alert is set) and READ permission on Billing Info. The cost_alert_definition parameter is the ID of the cost alert definition to update The cost_alert_definition_details parameter is a dict describing the cost alert definition to update.

delete_cost_alert_definition(cost_alert_definition)

Deletes a cost alert definition. The user should have the following permissions in order to complete this operation: DELETE permission on cost alert definitions, READ permission on the aggregation parent (the cost bucket or application’s on which the alert is set) and READ permission on Billing Info. The cost_alert_definition parameter is the ID of the cost alert definition to delete

get_users_of_cost_alert_definition(cost_alert_definition)

Returns list of all the recipients of a specific cost alert definition. The cost_alert_definition parameter is the ID of the cost alert definition to retrieve

add_user_to_cost_alert_definition(cost_alert_definition, user)

Adds a recipient to the cost alert definition. Required permissions: READ permission on the user, and UPDATE permission on the Cost Alert Definition. The cost_alert_definition parameter is the ID of the cost alert definition to add the user to The user parameter is the ID of the user to add to the cost alert definition

remove_user_from_cost_alert_definition(cost_alert_definition, user)

Deletes related user from cost alert definition. Required permissions: READ permission on the user, and UPDATE permission on the Cost Alert Definition. The cost_alert_definition parameter is the ID of the cost alert definition to remove the user from The user parameter is the ID of the user to remove from the cost alert definition

get_shares(request=None)

Get List of Shares. Returns a list of share records, optional filters could be used. - sharingUserId - The ID of the sharing user. - targetEmail - The email of the user whom we share the resource with. - sharedResourceType - Could be one of the following: BLUEPRINT, LIBRARY_VM, DISK_IMAGE. - sharedResourceId - The resource ID.

share_resource(share_details)

Share Specific Resource. The share_details parameter is a dict, describing the share to create. All fields are mandatory: - targetEmail - The email address of the user the share the resource with. - sharedResourceType - Should be one of the following: BLUEPRINT, LIBRARY_VM, DISK_IMAGE - sharedResourceId - The resource ID

delete_share(share)

Delete Share Data by ID. Unshare specific resource.