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.
-
main_file_name
¶ Returns: Blueprint main file name.
-
plan
¶ Gets the plan the blueprint represents: nodes, relationships etc...
Returns: The content of the blueprint.
-
description
¶ Gets the description of the blueprint
Returns: The description of the blueprint.
-
-
class
cloudify_rest_client.blueprints.
BlueprintsClient
(api)[source]¶ Bases:
object
-
list
(_include=None, **kwargs)[source]¶ Returns a list of currently stored blueprints.
Parameters: - _include – List of fields to include in response.
- kwargs – Optional filter fields. For a list of available fields see the REST service’s models.BlueprintState.fields
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¶
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.
DeploymentsClient
(api)[source]¶ Bases:
object
-
list
(_include=None, **kwargs)[source]¶ Returns a list of all deployments.
Parameters: - _include – List of fields to include in response.
- kwargs – Optional filter fields. for a list of available fields see the REST service’s models.Deployment.fields
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, **kwargs)[source]¶ List deployment modifications
Parameters: - deployment_id – The deployment id (optional)
- kwargs – Optional filter fields. for a list of available fields see the REST service’s models.DeploymentModification.fields
-
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:
-
get
(modification_id, _include=None)[source]¶ Get 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).
-
list
(include_logs=False, message=None, from_datetime=None, to_datetime=None, _include=None, **kwargs)[source]¶ List events
Parameters: - include_logs – Whether to also get logs.
- message – an expression used for wildcard search events by their message text
- from_datetime – search for events later or equal to datetime
- to_datetime – search for events earlier or equal to datetime
- _include – return only an exclusive list of fields
Returns: dict with ‘metadata’ and ‘items’ fields
-
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'¶
-
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)
-
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
-
is_system_workflow
¶ Returns: True if the workflow executed is a system workflow, otherwise False
-
created_at
¶ Returns: The execution creation time.
-
-
class
cloudify_rest_client.executions.
ExecutionsClient
(api)[source]¶ Bases:
object
-
list
(deployment_id=None, include_system_workflows=False, _include=None, **kwargs)[source]¶ Returns a list of executions.
Parameters: - deployment_id – Optional deployment id to get executions for.
- _include_system_workflows – Include executions of system workflows
- _include – List of fields to include in response.
- kwargs – Optional filter fields. For a list of available fields see the REST service’s models.Execution.fields
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.
-
Manager API¶
-
class
cloudify_rest_client.manager.
ManagerClient
(api)[source]¶ Bases:
object
-
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, node_id=None, _include=None, **kwargs)[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 name to only fetch node instances with this name. The node_name positional argument will be deprecated as of the next rest-client version. Use node_id instead.
- node_id – Equivalent to node_name.
- _include – List of fields to include in response.
- kwargs – Optional filter fields. for a list of available fields see the REST service’s models.DeploymentNodeInstance.fields
Returns: Node instances.
Return type:
-
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
-
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
¶ 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, **kwargs)[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. This parameter is deprecated, use ‘id’ instead.
- _include – List of fields to include in response.
- kwargs – Optional filter fields. for a list of available fields see the REST service’s models.DeploymentNode.fields
Returns: Nodes.
Return type:
-
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:
-
Search API¶
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:
-