Welcome to cloudify-rest-client’s documentation!

What is it?

This rest client provides access to the REST API exposed by a Cloudify manager.

Basic Usage

This client’s API tries to be as consistent as possible when accessing different resource types. The example below will fetch the blueprints currently uploaded to the manager.

from cloudify_rest_client import CloudifyClient

client = CloudifyClient('http://MANAGER_HOST')
blueprints = client.blueprints.list()

for blueprint in blueprints:
   print blueprint.id

Contents:

Blueprints API

class cloudify_rest_client.blueprints.Blueprint(blueprint)[source]

Bases: dict

id
Returns:The identifier of the blueprint.
created_at
Returns:Timestamp of blueprint creation.
plan

Gets the plan the blueprint represents: nodes, relationships etc...

Returns:The content of the blueprint.
class cloudify_rest_client.blueprints.BlueprintsClient(api)[source]

Bases: object

list(_include=None)[source]

Returns a list of currently stored blueprints.

Parameters:_include – List of fields to include in response.
Returns:Blueprints list.
publish_archive(archive_location, blueprint_id, blueprint_filename=None)[source]

Publishes a blueprint archive to the Cloudify manager.

Parameters:
  • archive_location – Path or Url to the archive file.
  • blueprint_id – Id of the uploaded blueprint.
  • blueprint_filename – The archive’s main blueprint yaml filename.
Returns:

Created blueprint.

Archive file should contain a single directory in which there is a blueprint file named blueprint_filename (if blueprint_filename is None, this value will be passed to the REST service where a default value should be used). Blueprint ID parameter is available for specifying the blueprint’s unique Id.

upload(blueprint_path, blueprint_id)[source]

Uploads a blueprint to Cloudify’s manager.

Parameters:
  • blueprint_path – Main blueprint yaml file path.
  • blueprint_id – Id of the uploaded blueprint.
Returns:

Created blueprint.

Blueprint path should point to the main yaml file of the blueprint to be uploaded. Its containing folder will be packed to an archive and get uploaded to the manager. Blueprint ID parameter is available for specifying the blueprint’s unique Id.

get(blueprint_id, _include=None)[source]

Gets a blueprint by its id.

Parameters:
  • blueprint_id – Blueprint’s id to get.
  • _include – List of fields to include in response.
Returns:

The blueprint.

delete(blueprint_id)[source]

Deletes the blueprint whose id matches the provided blueprint id.

Parameters:blueprint_id – The id of the blueprint to be deleted.
Returns:Deleted blueprint.
download(blueprint_id, output_file=None)[source]

Downloads a previously uploaded blueprint from Cloudify’s manager.

Parameters:
  • blueprint_id – The Id of the blueprint to be downloaded.
  • output_file – The file path of the downloaded blueprint file (optional)
Returns:

The file path of the downloaded blueprint.

Client API

class cloudify_rest_client.client.StreamedResponse(response)[source]

Bases: object

headers
bytes_stream(chunk_size=8192)[source]
lines_stream()[source]
close()[source]
class cloudify_rest_client.client.CloudifyClient(host='localhost', port=None, protocol='http', headers=None, query_params=None, cert=None, trust_all=False)[source]

Bases: object

Cloudify’s management client.

Deployments API

class cloudify_rest_client.deployments.Deployment(deployment)[source]

Bases: dict

Cloudify deployment.

id
Returns:The identifier of the deployment.
blueprint_id
Returns:The identifier of the blueprint this deployment belongs to.
workflows
Returns:The workflows of this deployment.
inputs
Returns:The inputs provided on deployment creation.
outputs
Returns:The outputs definition of this deployment.
class cloudify_rest_client.deployments.Workflow(workflow)[source]

Bases: dict

id
Returns:The workflow’s id
name
Returns:The workflow’s name
parameters
Returns:The workflow’s parameters
class cloudify_rest_client.deployments.DeploymentOutputs(outputs)[source]

Bases: dict

deployment_id

Deployment Id the outputs belong to.

outputs

Deployment outputs as dict.

class cloudify_rest_client.deployments.DeploymentOutputsClient(api)[source]

Bases: object

get(deployment_id)[source]

Gets the outputs for the provided deployment’s Id.

Parameters:deployment_id – Deployment Id to get outputs for.
Returns:Outputs as dict.
class cloudify_rest_client.deployments.DeploymentsClient(api)[source]

Bases: object

list(_include=None)[source]

Returns a list of all deployments.

Parameters:_include – List of fields to include in response.
Returns:Deployments list.
get(deployment_id, _include=None)[source]

Returns a deployment by its id.

Parameters:
  • deployment_id – Id of the deployment to get.
  • _include – List of fields to include in response.
Returns:

Deployment.

create(blueprint_id, deployment_id, inputs=None)[source]

Creates a new deployment for the provided blueprint id and deployment id.

Parameters:
  • blueprint_id – Blueprint id to create a deployment of.
  • deployment_id – Deployment id of the new created deployment.
  • inputs – Inputs dict for the deployment.
Returns:

The created deployment.

delete(deployment_id, ignore_live_nodes=False)[source]

Deletes the deployment whose id matches the provided deployment id. By default, deployment with live nodes deletion is not allowed and this behavior can be changed using the ignore_live_nodes argument.

Parameters:
  • deployment_id – The deployment’s to be deleted id.
  • ignore_live_nodes – Determines whether to ignore live nodes.
Returns:

The deleted deployment.

Deployment Modfications API

class cloudify_rest_client.deployment_modifications.DeploymentModificationNodeInstances(node_instances)[source]

Bases: dict

List of added nodes and nodes that are related to them

List of removed nodes and nodes that are related to them

before_modification

List of node instances with their state as it existed before the deployment modification started

before_rollback

If deployment modification was rolledback, this will be a list of node instances with their state as it existed before the deployment modification was rolledback

class cloudify_rest_client.deployment_modifications.DeploymentModification(modification)[source]

Bases: dict

STARTED = 'started'
FINISHED = 'finished'
ROLLEDBACK = 'rolledback'
id

Deployment modification id

status

Deployment modification status

deployment_id

Deployment Id the outputs belong to.

node_instances

Dict containing added_and_related and remove_and_related node instances list

modified_nodes

Dict containing original modified nodes that started this modification

created_at

Deployment modification creation date

ended_at

Deployment modification end date

context

Dict containing context that has been attached to modification.

This context has no predefined schema. Its structure can be whatever has been attached to the modification when it was started.

class cloudify_rest_client.deployment_modifications.DeploymentModificationsClient(api)[source]

Bases: object

list(deployment_id=None, _include=None)[source]

List deployment modifications

Parameters:deployment_id – The deployment id (optional)
start(deployment_id, nodes, context=None)[source]

Start deployment modification.

Parameters:
  • deployment_id – The deployment id
  • nodes – the nodes to modify
Returns:

DeploymentModification dict

Return type:

DeploymentModification

get(modification_id, _include=None)[source]

Get deployment modification

Parameters:modification_id – The modification id
finish(modification_id)[source]

Finish deployment modification

Parameters:modification_id – The modification id
rollback(modification_id)[source]

Rollback deployment modification

Parameters:modification_id – The modification id

Events API

class cloudify_rest_client.events.EventsClient(api)[source]

Bases: object

get(execution_id, from_event=0, batch_size=100, include_logs=False)[source]

Returns event for the provided execution id.

Parameters:
  • execution_id – Id of execution to get events for.
  • from_event – Index of first event to retrieve on pagination.
  • batch_size – Maximum number of events to retrieve per call.
  • include_logs – Whether to also get logs.
Returns:

Events list and total number of currently available events (tuple).

Exceptions API

exception cloudify_rest_client.exceptions.CloudifyClientError(message, server_traceback=None, status_code=-1, error_code=None)[source]

Bases: exceptions.Exception

exception cloudify_rest_client.exceptions.DeploymentEnvironmentCreationInProgressError(message, server_traceback=None, status_code=-1, error_code=None)[source]

Bases: cloudify_rest_client.exceptions.CloudifyClientError

Raised when there’s attempt to execute a deployment workflow and deployment environment creation workflow execution is still running. In such a case, workflow execution should be retried after a reasonable time or after the execution of deployment environment creation workflow has terminated.

ERROR_CODE = 'deployment_environment_creation_in_progress_error'
exception cloudify_rest_client.exceptions.DeploymentEnvironmentCreationPendingError(message, server_traceback=None, status_code=-1, error_code=None)[source]

Bases: cloudify_rest_client.exceptions.CloudifyClientError

Raised when there’s attempt to execute a deployment workflow and deployment environment creation workflow execution is pending. In such a case, workflow execution should be retried after a reasonable time or after the execution of deployment environment creation workflow has terminated.

ERROR_CODE = 'deployment_environment_creation_pending_error'
exception cloudify_rest_client.exceptions.IllegalExecutionParametersError(message, server_traceback=None, status_code=-1, error_code=None)[source]

Bases: cloudify_rest_client.exceptions.CloudifyClientError

Raised when an attempt to execute a workflow with wrong/missing parameters has been made.

ERROR_CODE = 'illegal_execution_parameters_error'
exception cloudify_rest_client.exceptions.NoSuchIncludeFieldError(message, server_traceback=None, status_code=-1, error_code=None)[source]

Bases: cloudify_rest_client.exceptions.CloudifyClientError

Raised when an _include query parameter contains a field which does not exist for the queried data model.

ERROR_CODE = 'no_such_include_field_error'
exception cloudify_rest_client.exceptions.MissingRequiredDeploymentInputError(message, server_traceback=None, status_code=-1, error_code=None)[source]

Bases: cloudify_rest_client.exceptions.CloudifyClientError

Raised when a required deployment input was not specified on deployment creation.

ERROR_CODE = 'missing_required_deployment_input_error'
exception cloudify_rest_client.exceptions.UnknownDeploymentInputError(message, server_traceback=None, status_code=-1, error_code=None)[source]

Bases: cloudify_rest_client.exceptions.CloudifyClientError

Raised when an unexpected input was specified on deployment creation.

ERROR_CODE = 'unknown_deployment_input_error'
exception cloudify_rest_client.exceptions.FunctionsEvaluationError(message, server_traceback=None, status_code=-1, error_code=None)[source]

Bases: cloudify_rest_client.exceptions.CloudifyClientError

Raised when function evaluation failed.

ERROR_CODE = 'functions_evaluation_error'
exception cloudify_rest_client.exceptions.UnknownModificationStageError(message, server_traceback=None, status_code=-1, error_code=None)[source]

Bases: cloudify_rest_client.exceptions.CloudifyClientError

Raised when an unknown modification stage was provided.

ERROR_CODE = 'unknown_modification_stage_error'
exception cloudify_rest_client.exceptions.ExistingStartedDeploymentModificationError(message, server_traceback=None, status_code=-1, error_code=None)[source]

Bases: cloudify_rest_client.exceptions.CloudifyClientError

Raised when a deployment modification start is attempted while another deployment modification is currently started

ERROR_CODE = 'existing_started_deployment_modification_error'
exception cloudify_rest_client.exceptions.DeploymentModificationAlreadyEndedError(message, server_traceback=None, status_code=-1, error_code=None)[source]

Bases: cloudify_rest_client.exceptions.CloudifyClientError

Raised when a deployment modification finish/rollback is attempted on a deployment modification that has already been finished/rolledback

ERROR_CODE = 'deployment_modification_already_ended_error'
exception cloudify_rest_client.exceptions.UserUnauthorizedError(message, server_traceback=None, status_code=-1, error_code=None)[source]

Bases: cloudify_rest_client.exceptions.CloudifyClientError

Raised when a call has been made to a secured resource with an unauthorized user (no credentials / bad credentials)

ERROR_CODE = 'unauthorized_error'
cloudify_rest_client.exceptions.error

alias of UserUnauthorizedError

Executions API

class cloudify_rest_client.executions.Execution(execution)[source]

Bases: dict

Cloudify workflow execution.

id
Returns:The execution’s id.
deployment_id
Returns:The deployment’s id this execution is related to.
status
Returns:The execution’s status.
error
Returns:The execution error in a case of failure, otherwise None.
workflow_id
Returns:The id of the workflow this execution represents.
parameters
Returns:The execution’s parameters
created_at
Returns:The execution creation time.
class cloudify_rest_client.executions.ExecutionsClient(api)[source]

Bases: object

list(deployment_id=None, _include=None)[source]

Returns a list of executions.

Parameters:
  • deployment_id – Optional deployment id to get executions for.
  • _include – List of fields to include in response.
Returns:

Executions list.

get(execution_id, _include=None)[source]

Get execution by its id.

Parameters:
  • execution_id – Id of the execution to get.
  • _include – List of fields to include in response.
Returns:

Execution.

update(execution_id, status, error=None)[source]

Update execution with the provided status and optional error.

Parameters:
  • execution_id – Id of the execution to update.
  • status – Updated execution status.
  • error – Updated execution error (optional).
Returns:

Updated execution.

start(deployment_id, workflow_id, parameters=None, allow_custom_parameters=False, force=False)[source]

Starts a deployment’s workflow execution whose id is provided.

Parameters:
  • deployment_id – The deployment’s id to execute a workflow for.
  • workflow_id – The workflow to be executed id.
  • parameters – Parameters for the workflow execution.
  • allow_custom_parameters – Determines whether to allow parameters which weren’t defined in the workflow parameters schema in the blueprint.
  • force – Determines whether to force the execution of the workflow in a case where there’s an already running execution for this deployment.
Raises:

IllegalExecutionParametersError

Returns:

The created execution.

cancel(execution_id, force=False)[source]

Cancels the execution which matches the provided execution id.

Parameters:
  • execution_id – Id of the execution to cancel.
  • force – Boolean describing whether to send a ‘cancel’ or a ‘force-cancel’ action # NOQA
Returns:

Cancelled execution.

Manager API

class cloudify_rest_client.manager.ManagerClient(api)[source]

Bases: object

get_status()[source]
Returns:Cloudify’s management machine status.
get_version()[source]
Returns:Cloudify’s management machine version information.
get_context(_include=None)[source]

Gets the context which was stored on management machine bootstrap. The context contains Cloudify specific information and Cloud provider specific information.

Parameters:_include – List of fields to include in response.
Returns:Context stored in manager.
create_context(name, context)[source]

Creates context in Cloudify’s management machine. This method is usually invoked right after management machine bootstrap with relevant Cloudify and cloud provider context information.

Parameters:
  • name – Cloud provider name.
  • context – Context as dict.
Returns:

Create context result.

update_context(name, context)[source]

Updates context in Cloudify’s management machine. The context is imperative for the manager to function properly, only use this method if you know exactly what you are doing. Note that if the provider context does not exist, this call will result with an error.

Parameters:
  • name – Cloud provider name.
  • context – Context as dict.

Node Instances API

class cloudify_rest_client.node_instances.NodeInstance(node_instance)[source]

Bases: dict

Cloudify node instance.

id
Returns:The identifier of the node instance.
node_id
Returns:The identifier of the node whom this is in instance of.
relationships
Returns:The node instance relationships.
host_id
Returns:The node instance host_id.
deployment_id
Returns:The deployment id the node instance belongs to.
runtime_properties
Returns:The runtime properties of the node instance.
state
Returns:The current state of the node instance.
version
Returns:The current version of the node instance (used for optimistic locking on update)
class cloudify_rest_client.node_instances.NodeInstancesClient(api)[source]

Bases: object

get(node_instance_id, _include=None)[source]

Returns the node instance for the provided node instance id.

Parameters:
  • node_instance_id – The identifier of the node instance to get.
  • _include – List of fields to include in response.
Returns:

The retrieved node instance.

update(node_instance_id, state=None, runtime_properties=None, version=0)[source]

Update node instance with the provided state & runtime_properties.

Parameters:
  • node_instance_id – The identifier of the node instance to update.
  • state – The updated state.
  • runtime_properties – The updated runtime properties.
  • version – Current version value of this node instance in Cloudify’s storage (used for optimistic locking).
Returns:

The updated node instance.

list(deployment_id=None, node_name=None, _include=None)[source]

Returns a list of node instances which belong to the deployment identified by the provided deployment id.

Parameters:
  • deployment_id – Optional deployment id to list node instances for.
  • node_name – Optional node id to only fetch node instances with this name
  • _include – List of fields to include in response.
Returns:

Node instances.

Return type:

list

Nodes API

class cloudify_rest_client.nodes.Node(node_instance)[source]

Bases: dict

Cloudify node.

id
Returns:The identifier of the node.
deployment_id
Returns:The deployment id the node belongs to.
properties
Returns:The static properties of the node.
operations
Returns:The node operations mapped to plugins.
Return type:dict
relationships
Returns:The node relationships with other nodes.
Return type:list
blueprint_id
Returns:The id of the blueprint this node belongs to.
Return type:str
plugins
Returns:The plugins this node has operations mapped to.
Return type:dict
number_of_instances
Returns:The number of instances this node has.
Return type:int
planned_number_of_instances
Returns:The planned number of instances this node has.
Return type:int
deploy_number_of_instances
Returns:The number of instances this set for this node when the deployment was created.
Return type:int
host_id
Returns:The id of the node instance which hosts this node.
Return type:str
type_hierarchy
Returns:The type hierarchy of this node.
Return type:list
type
Returns:The type of this node.
Return type:str
class cloudify_rest_client.nodes.NodesClient(api)[source]

Bases: object

list(deployment_id=None, node_id=None, _include=None)[source]

Returns a list of nodes which belong to the deployment identified by the provided deployment id.

Parameters:
  • deployment_id – The deployment’s id to list nodes for.
  • node_id – If provided, returns only the requested node.
  • _include – List of fields to include in response.
Returns:

Nodes.

Return type:

list

get(deployment_id, node_id, _include=None)[source]

Returns the node which belongs to the deployment identified by the provided deployment id .

Parameters:
  • deployment_id – The deployment’s id of the node.
  • node_id – The node id.
  • _include – List of fields to include in response.
Returns:

Nodes.

Return type:

Node

Search API

class cloudify_rest_client.search.SearchClient(api)[source]

Bases: object

run_query(query)[source]

Run the provided Elasticsearch query.

Parameters:query – Elasticsearch query.
Returns:Elasticsearch result hits.

Evaluate API

class cloudify_rest_client.evaluate.EvaluatedFunctions(evaluated_functions)[source]

Bases: dict

Evaluated functions.

deployment_id
Returns:The deployment id this request belongs to.
payload
Returns:The evaluation payload.
class cloudify_rest_client.evaluate.EvaluateClient(api)[source]

Bases: object

functions(deployment_id, context, payload)[source]

Evaluate intrinsic functions in payload in respect to the provided context.

Parameters:
  • deployment_id – The deployment’s id of the node.
  • context – The processing context (dict with optional self, source, target).
  • payload – The payload to process.
Returns:

The payload with its intrinsic functions references evaluated.

Return type:

EvaluatedFunctions

Tokens API

class cloudify_rest_client.tokens.Token(token)[source]

Bases: dict

value
Returns:The value of the token.
class cloudify_rest_client.tokens.TokensClient(api)[source]

Bases: object

get()[source]

Get an authentication token.

Return type:Token

Indices and tables