Conductor REST API V3.1

Basic usage

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-pasword> \
    "http://<manager-ip>/api/v3.1/<endpoint>"

# Using ClodifyClient
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager-ip>',
    username='<manager-username>',
    password='<manager-password>',
    tenant='<manager-tenant>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager-ip>/api/v3.1/<endpoint>'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers)
response.json()

Welcome to Conductor’s REST API Documentation!

The base URI for the v3.1 REST API is: /api/v3.1.

All communication to the server requires:

Authentication using user credentials.
Tenant name, representing the scope of the request.

Every Conductor Manager has a default tenant, called default_tenant. The default_tenant tenant is created during bootstrap.

In addition to the default_tenant, every Conductor Manager includes a bootstrap Admin. The bootstrap Admin is the Admin user that created during the bootstrap.

In addition to the user credentials, every request must also specify a tenant in the header.

If you have not created any new tenant, you can use the default_tenant as the tenant for the request.

Parameters

<manager-ip>: Replace with the IP of your Conductor Manager
<manager-username>: Replace with a username for the Conductor Manager instance username
<manager-password>: Replace with the password for the user specified in
<manager-tenant>: Replace with the tenant on which to perform the request
<manager-token>: Replace with a token obtained using the tokens endpoint (see the authentication section)

Response Fields Filtering (Projection)

Request Example (receive only the id and created_at fields)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-api>/api/v3.1/blueprints?_include=id,created_at"

# Using ClodifyClient
blueprints = client.blueprints.list(_include=['id','created_at'])
for blueprint in blueprints:
  print blueprint

# Using requests
url = 'http://<manager-ip>/api/v3.1/blueprints'
querystring = {'_include': 'id,created_at'}
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "created_at": "2017-04-17T12:12:36.626Z",
      "id": "hello-world"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 1
    }
  }
}

You can choose to have only specific fields in the response by using the _include query parameter.

The parameter value is a comma separated list of fields to include in the response, e.g. _include=field1,field2,field3

Note that specified field names must be part of the resource schema, otherwise an error is raised.

Query Filtering (Selection)

Request Example (requesting only blueprints which id is my_blueprint1 or my_blueprint2)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-pasword> \
    "http://<manager-ip>/api/v3.1/blueprints?_include=id,created_at&id=my-blueprint-1&id=my-blueprint-2"

# Using ClodifyClient
blueprints = client.blueprints.list(
    _include=['id','created_at'],
    id=['my-blueprint-1', 'my-blueprint-2'],
)
for blueprint in blueprints:
    print blueprint

# Using requests
url = "http://<manager-ip>/api/v3.1/blueprints"
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    '_include': 'id,created_at',
    'id': ['my-blueprint-1', 'my-blueprint-2'],
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "created_at": "2017-04-17T12:34:52.911Z",
      "id": "my-blueprint-1"
    },
    {
      "created_at": "2017-04-17T12:34:57.256Z",
      "id": "my-blueprint-2"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 2
    }
  }
}

You can make your query more specific by using filters.

Filters are query parameters where the key is a field name and the value is a field value, e.g. id=my-specific-id

Filters also accept multiple values (OR) by using multiple parameters of the same key, e.g. id=my-specific-id&id=another-id

Sorting

Request Example #1 (sort deployments by id descending)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager_ip>/api/v3.1/deployments?_include=id,blueprint_id&_sort=-id"

# Using CloudifyClient
deployments = client.deployments.list(
    _include=['id', 'blueprint_id'],
    _sort='-id',
)
for deployment in deployments:
    print deployment

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    '_include': 'id,blueprint_id',
    '_sort': '-id',
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example #1

{
  "items": [
    {
      "id": "hello1",
      "blueprint_id": "hello-world"
    },
    {
      "id": "dep4",
      "blueprint_id": "my-blueprint-2"
    },
    {
      "id": "dep3",
      "blueprint_id": "my-blueprint-1"
    },
    {
      "id": "dep2",
      "blueprint_id": "my-blueprint-2"
    },
    {
      "id": "dep1",
      "blueprint_id": "my-blueprint-1"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 5,
      "offset": 0,
      "size": 5
    }
  }
}

Request Example #2 (sort deployments by blueprint_id ascending and id descending)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager_ip>/api/v3.1/deployments?_include=id,blueprint_id&_sort=blueprint_id&_sort=-id"

# Using CloudifyClient
deployments = client.deployments.list(
    _include=['id', 'blueprint_id'],
    _sort=['blueprint_id', '-id'],
)
for deployment in deployments:
    print deployment

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    '_include': 'id,blueprint_id',
    '_sort': ['blueprint_id', '-id'],
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example #2

{
  "items": [
    {
      "id": "hello1",
      "blueprint_id": "hello-world"
    },
    {
      "id": "dep3",
      "blueprint_id": "my-blueprint-1"
    },
    {
      "id": "dep1",
      "blueprint_id": "my-blueprint-1"
    },
    {
      "id": "dep4",
      "blueprint_id": "my-blueprint-2"
    },
    {
      "id": "dep2",
      "blueprint_id": "my-blueprint-2"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 5,
      "offset": 0,
      "size": 5
    }
  }
}

Sort resources by using the _sort query parameter, e.g. _sort=id

The default sort order is ascending; to make it descending, prefix the field with a minus sign, e.g. _sort=-id (example #1)

Sorting also works on multiple fields by using multiple _sort parameters, where the sort sequence corresponds to the order of _sort parameters in the request (example #2).

Pagination

Request Example (skip 1 resource, get size of 4)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/events?_size=4&_offset=1&_include=timestamp"

# Using CloudifyClient
events = client.events.list(
    _size=4,
    _offset=1,
    _include=['timestamp'],
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/events'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    '_size': '4',
    '_offset': '1',
    '_include':'timestamp',
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "timestamp": "2017-04-17T13:53:22.570Z"
    },
    {
      "timestamp": "2017-04-17T13:53:10.558Z"
    },
    {
      "timestamp": "2017-04-17T13:53:09.799Z"
    },
    {
      "timestamp": "2017-04-17T13:52:54.549Z"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 20,
      "offset": 1,
      "size": 4
    }
  }
}

If the response includes too many items for the client to handle at once, use pagination to get only a subset of the results, defined by two parameters:

_size the max size of the result subset to receive.
_offset (default: 0) the number of resources to skip, i.e. _offset=1 means you skip the first resource.

* both parameters are optional.

* in any case, with or without pagination, max size of the result will be less than max_results parameters, which is 1000 by default. max_results parameters is part of the manager_rest config.

The response metadata returns the requested parameters, and a total field which indicates the size of the full set.

Authentication

Authentication headers should be added to every request sent to a secured manager. Any header can be used, as long as it’s support by one of the manager’s authentication providers. The default manager configuration supports basic HTTP authentication (examples #1, #2) and tokens (example #3). Valid credentials do not affect the returned response, but invalid credentials return a “User Unauthorized” error.

Request Example #1 (Get the server’s status, authenticate with username and password)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-pasword> \
    "http://<manager-ip>/api/v3.1/status?_include=status"

# Using CloudifyClient
client.manager.get_status()

# Using requests
url = 'http://<manager-ip>/api/v3.1/status'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'status'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example #1

{
  "status": "running"
}

Request Example #2 (Get a token, authenticate with username and password)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-pasword> \
    "<manager-ip>/api/v3.1/tokens"

# Using CloudifyClient
client.tokens.get()

# Using requests
url = 'http://<manager-ip>/api/v3.1/tokens'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example #2

{
  "role": "admin",
  "value": "WyIwIiwiMzE0OTNmNWFjOTE1MzdhM2IyZWM4NTFhYWY4NzU0NWEiXQ.C9Z82w.dlVgLkkyeWZgZP06xMxe8Omht90"
}

Request Example #3 (Get all the blueprints, authenticate with a token)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    --header "Authentication-Token: <manager-token>" \
    "http://<manager-ip>/api/v3.1/blueprints?_include=id"

# Using CloudifyClient
client = CloudifyClient(
    host='<manager-ip>',
    tenant='<manager-tenant>',
    token='<manager-token>',
)
blueprints = client.blueprints.list(_include=['id'])
for blueprint in blueprints:
    print blueprint

# Using requests
url = 'http://<manager-ip>/api/v3.1/blueprints'
headers = {
    'Tenant': '<manager-tenant>',
    'Autentication-Token': '<manage-token>',
}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    headers=headers,
    params=querystring,
)
response.json()

Response Example #3

{
  "items": [
    {
      "id": "my-blueprint-1"
    },
    {
      "id": "my-blueprint-2"
    },
    {
      "id": "hello-world"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 3
    }
  }
}

Agents

The Agents Resource

This resource represents a Conductor Agent, and is used for examining the details of installed agents.

Attributes:

Attribute	Type	Description
`id`	string	Unique identifier of the node instance that installed the agent
`host_id`	string	Unique identifier of the node instance that the agent is installed on. Identical to `id` except for deployment proxy agents.
`ip`	string	IP of the host the agent is installed on
`install_methods`	string	The agent’s install_method (remote/plugin/init_script/provided)
`system`	string	Description of the OS the agent is installed on (the linux distribution name, or “windows”)
`version`	string	Conductor version of the agent software
`node`	string	ID of the node that installed the agent
`deployment`	string	ID of the deployment that installed the agent

List agents

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/agents?node_ids=<node_1>&node_ids=<node_2>"

# Using CloudifyClient
client.agents.list(node_ids=['node_1', 'node_2'])

# Using requests
url = 'http://<manager-ip>/api/v3.1/agents'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'node_ids': ['node_1', 'node_2']
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
    "items": [
        {
            "node": "x",
            "ip": "127.0.0.1",
            "system": "centos core",
            "install_method": "remote",
            "version": "4.5.0",
            "deployment": "d4",
            "host_id": "x_asa5b3",
            "id": "x_asa5b3"
        }
    ],
    "metadata": {
        "pagination": {
            "total": 1,
            "offset": 0,
            "size": 1
        }
    }
}

Gets the list of installed agents.

URI Parameters

For additional filtering of the agents list, the following parameters can be provided:

deployment_id: the agent deployment ID
node_ids: the agent node ID (can be provided multiple times)
node_instance_ids: the agent node instance ID (can be provided multiple times)
install_method: the agent install method (can be provided multiple times)
_all_tenants: whether to include resources from all tenants associated with the user.

Response

A list of Agent resources.

Blueprints

The Blueprint Resource

Attributes:

Attribute	Type	Description
`created_at`	datetime	The time the blueprint was uploaded to the manager.
`description`	string	The blueprint’s description.
`id`	string	A unique identifier for the blueprint.
`main_file_name`	string	The blueprint’s main file name.
`plan`	dict	The parsed result of the blueprint.
`requirements`	dict	Description of the blueprint deploy requirements.
`updated_at`	datetime	The last time the blueprint was updated.
`labels`	list	A list of the deployment’s labels.

Get Blueprint

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/blueprints?id=<blueprint-id>&_include=id"

# Using ConductorClient
client.blueprints.get(blueprint_id='<blueprint-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/blueprints'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'id': '<blueprint-id>',
    '_include': 'id',
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "hello-world"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 1
    }
  }
}

GET "{manager-ip}/api/v3.1/blueprints?id={blueprint-id}"

Gets a specific blueprint.

URI Parameters

blueprint-id: The id of the blueprint to retrieve.

Response

A Blueprint resource.

Upload Blueprint

Request Example

# create blueprint from blueprint_archive_url
$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -F 'params={"blueprint_archive_url": "http://url/to/archive.zip", application_file_name": "<filename>.yaml", "visibility": "<visibility>"}' \
    "http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>"

# create blueprint from a .tgz archive, with additional parameters
$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -F blueprint_archive=@<blueprint_archive>.tar.gz \
    -F 'params={"application_file_name": "<filename>.yaml", "visibility": "<visibility>", "labels": [{"key": "<label key>", "value": "<label value>"}]}' \
    "http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>"

# Using ConductorClient, uploading a zip file
client.blueprints.publish_archive(
    blueprint_id='<blueprint-id>',
    archive_location='https://url/to/archive/master.zip',
    blueprint_filename='<blueprint-id>.yaml',
    visibility='<visibility>',
    labels=[{'<key1>': '<val1>'}, ...]
)
# Using ConductorClient, uploading a directory
# (will be tar'ed on the fly)
client.blueprints.upload(
    'path/to/blueprint.yaml',
    '<blueprint-id>',
    visibility='<visibility>',
    labels=[{'<key1>': '<val1>'}, ...]
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'application_file_name': '<blueprint-id>.yaml',
    'blueprint_archive_url': 'https://url/to/archive/master.zip',
    'visibility': '<visibility>',
    'labels': '<key1>=<val1>,<key2>=<val2>,...'
}
response = requests.put(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "main_file_name": "singlehost-blueprint.yaml",
  "description": "This blueprint installs a simple web server on the manager VM using Conductor's script plugin.\n",
  "tenant_name": "default_tenant",
  "created_at": "2021-03-25T15:51:30.526Z",
  "updated_at": "2021-03-25T15:51:30.526Z",
  "created_by": "admin",
  "private_resource": false,
  "visibility": "tenant",
  "plan": {
    ...
  },
  "labels": [
    ...
  ],
  "id": "hello-world"
}

PUT "{manager-ip}/api/v3.1/blueprints/{blueprint-id}"

Uploads a blueprint to Conductor’s manager. The call expects a multipart/form-data-encoded request body, containing the fields blueprint_archive - a zip or tgz of the blueprint, and params - a JSON-encoded field containing blueprint metadata. The “params” field may contain the keys application_file_name, visibility, labels, and async_upload. It is also possible to upload a blueprint from a URL by specifying the URL in the blueprint_archive_url key in the params field.

URI Parameters

blueprint-id: The id of the uploaded blueprint.

Request Body

The request body must be multipart/form-data.

Property | Type | Description blueprint_archive | binary | The contents of a zip or tgz-compressed archive of the blueprint directory. params | string | JSON-encoded object containing additional parameters. This field may contain the other parameters listed below. blueprint_archive_url | string | A URL the blueprint to be uploaded should be downloaded from by the manager. May be provided as a key in the params field, or as a field in the querystring. application_file_name | string | The main blueprint file name in the blueprint’s archive. May be provided as a key in the params field, or as a field in the querystring. visibility | string | Optional parameter, defines who can see the blueprint (default: tenant). May be provided as a key in the params field. async_upload | boolean | Optional parameter, setting it to True means the REST service won’t wait for the upload workflow to complete, allowing a batch upload (default: False). May be provided as a key in the params field. Supported for Conductor Manager 5.2 and above. labels | list | Labels to apply to the blueprint - a list of objects containing the keys key and value. May be provided as a key in the params field.

Valid visibility values are:

private: The resource is visible to the user that created the resource, the tenant’s managers and the system’s admins.
tenant: The resource is visible to all users in the current tenant. (Default value)
global: The resource is visible to all users in all tenants across the manager.

Response

A Blueprint resource.

Validate Blueprint

Request Example

# validate a blueprint at blueprint_archive_url
$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -F 'params={"blueprint_archive_url": "http://url/to/archive.zip", application_file_name": "<filename>.yaml", "visibility": "<visibility>"}' \
    "http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>/validate"

# validate a  blueprint from uploaded archive
$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -F blueprint_archive=@<blueprint_archive>.tar.gz \
    -F 'params={"application_file_name": "<filename>.yaml", "visibility": "<visibility>"}' \
    "http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>"

# Using ConductorClient
client.blueprints.validate(
    'path/to/blueprint.yaml',
    '<blueprint-id>',
    visibility='<visibility>'
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>/validate'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'application_file_name': '<blueprint-id>.yaml',
    'blueprint_archive_url': 'https://url/to/archive/master.zip',
    'visibility': '<visibility>'
}
response = requests.put(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)

PUT "{manager-ip}/api/v3.1/blueprints/{blueprint-id}/validate"

Validates a blueprint with Conductor’s manager. The call expects an “application/octet-stream” content type where the content is a zip/tar.gz/bz2 archive. It is possible to upload a blueprint from a URL by specifying the URL in the blueprint_archive_url request body property.

URI Parameters

blueprint-id: The id of the uploaded blueprint.

Request Body

The request body is the same as in the Blueprint Upload endpoint.

Response

An Execution resource, representing the upload_blueprint workflow execution that will validate the blueprint. Users should follow that execution to completion, and examine its status, error, and logs, to see if the blueprint validated successfully, and if not - what are the invalid parts.

List Blueprints

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/blueprints?_include=id"

# Using ConductorClient
blueprints = client.blueprints.list(_include=['id'])
for blueprint in blueprints:
    print blueprint

# Using requests
url = "http://<manager-ip>/api/v3.1/blueprints"
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "hello-world"
    },
    {
      "id": "hello-world-2"
    },
    {
      "id": "hello-world-3"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 3
    }
  }
}

GET "{manager-ip}/api/v3.1/blueprints"

Lists all blueprints.

Response

Field	Type	Description
`items`	list	A list of `Blueprint` resources.

Delete Blueprint

Request Example

$ curl -X DELETE \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/blueprints/<blueprint-id>?force=false"

# Using ConductorClient
client.blueprints.delete(blueprint_id='<blueprint-id>', force=False)

# Using requests
url = 'http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>?force=false'
headers = {'Tenant': '<manager-tenant>'}
requests.delete(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)

DELETE "{manager-ip}/api/v3.1/blueprints/{blueprint-id}"

Deletes a specific blueprint.

URI Parameters

Property	Type	Description
`blueprint_id`	string	The id of the blueprint to delete.
`force`	bool	Delete the blueprint, even if there are blueprints that are currently using it.

Response

No content - HTTP code 204.

Download Blueprint

Downloads a specific blueprint as an archive.

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>/archive" > <blueprint-archive-filename>.tar.gz

# Using ConductorClient
client.blueprints.download(blueprint_id='<blueprint-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>/archive'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
with open('<blueprint-archive-filename>.tar.gz', 'wb') as blueprint_archive:
    blueprint_archive.write(response.content)

GET "{manager-ip}/api/v3.1/blueprints/{blueprint-id}/archive"

URI Parameters

blueprint-id: The id of the blueprint to download.

Response

The blueprint as an archive using an application/octet-stream content type.

Set Blueprint Visibility

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"visibility": "<visibility>"}' \
    "http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>/set-visibility"

# Python Client
client.blueprints.set_visibility('<blueprint-id>', '<visibility>')

Response Example

{
  "main_file_name": "singlehost-blueprint.yaml",
  "description": "This blueprint installs a simple web server on the manager VM using Conductor's script plugin.\n",
  "tenant_name": "default_tenant",
  "created_at": "2021-03-25T15:51:30.526Z",
  "updated_at": "2021-03-25T15:51:30.526Z",
  "created_by": "admin",
  "private_resource": false,
  "visibility": "global",
  "plan": {
    ...
  },
  "labels": [
    ...
  ],
  "id": "hello-world"
}

PATCH "<manager-ip>/api/v3.1/blueprints/{blueprint-id}/set-visibility"

Update the visibility of the blueprint.

URI Parameters

blueprint-id: The id of the blueprint to update.

Request Body

Property	Type	Description
`visibility`	string	Defines who can see the blueprint. (Required)

Valid values are tenant or global.

Response

A Blueprint resource.

Set Blueprint’s Icon

Request Example

# Update blueprint's icon with <icon_image>.png
$ curl -X PATCH \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -T <icon_image>.png \
    "http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>/icon"

# Remove blueprint's icon
$ curl -X PATCH \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>/icon"

# Python Client: Update blueprint'e icon with PNG file located at <icon_path>
client.blueprints.upload_icon('<blueprint-id>', '<icon_path>')


# Python Client: Remove blueprint'e icon
client.blueprints.remove_icon('<blueprint-id>')

Response Example

{
  "main_file_name": "singlehost-blueprint.yaml",
  "description": "This blueprint installs a simple web server on the manager VM using Conductor's script plugin.\n",
  "tenant_name": "default_tenant",
  "created_at": "2021-03-25T15:51:30.526Z",
  "updated_at": "2021-03-25T15:51:30.526Z",
  "created_by": "admin",
  "private_resource": false,
  "visibility": "tenant",
  "plan": {
    ...
  },
  "labels": [
    ...
  ],
  "id": "hello-world"
}

PATCH "<manager-ip>/api/v3.1/blueprints/{blueprint-id}/icon"

Set blueprint’s icon if icon file is uploaded along the request or remove it otherwise. Supported for Conductor Manager 6.3 and above.

URI Parameters

blueprint-id: The id of the blueprint to update.

Response

A Blueprint resource.

Update (add / delete) Blueprint Labels

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"labels": [{"<key1>": "<val1>"}, {"<key2>": "<val2>"}]}' \
    "http://<manager-ip>/api/v3.1/blueprints/<blueprint-id>"

# Python Client
client.blueprints.update(
blueprint_id='<deployment-id>',
update_dict={'labels': [{'<key1>': '<val1>', '<key2>': '<val2>'}]}
)

Response Example

{
  "main_file_name": "singlehost-blueprint.yaml",
  "description": "This blueprint installs a simple web server on the manager VM using Conductor's script plugin.\n",
  "tenant_name": "default_tenant",
  "created_at": "2021-03-25T15:51:30.526Z",
  "updated_at": "2021-03-25T16:04:20.496Z",
  "created_by": "admin",
  "private_resource": false,
  "visibility": "global",
  "plan": {
    ...
  },
  "labels": [
   {
      "key": "<key1>",
      "value": "<val1>",
      "created_at": "2021-03-25T16:04:20.486Z",
      "creator_id": 0
    },
    {
      "key": "<key2>",
      "value": "<val2>",
      "created_at": "2021-03-25T16:04:20.486Z",
      "creator_id": 0
    }
  ],
  "id": "hello-world"
}

PATCH "<manager-ip>/api/v3.1/blueprints/{blueprint-id}"

Update the blueprint’s labels.

URI Parameters

blueprint-id: The id of the blueprint to update.

Request Body

Property	Type	Description
`labels`	list	A list of the new deployment’s labels (required).

Response

A Blueprint resource.

Get all Blueprints' Labels' Keys

Request Example

$ curl -X GET \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/labels/blueprints"

# Python Client
client.blueprints_labels.list_keys()

Response Example

{
  "metadata": {
    "pagination": {
      "total": 2,
      "size": 1000,
      "offset": 0
    }
  },
  "items": [
    "key1",
    "key2"
  ]
}

GET "<manager-ip>/api/v3.1/labels/blueprints"

Get all blueprints' labels' keys in the specified tenant.

Response

Field	Type	Description
`items`	list	A list of all blueprints' labels' keys.

Get All Blueprints' Labels' Values For a Specified Key

Request Example

$ curl -X GET \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/labels/blueprints/<label-key>"

# Python Client
client.blueprints_labels.list_key_values(label_key='<label-key>')

Response Example

{
  "metadata": {
    "pagination": {
      "total": 1,
      "size": 1000,
      "offset": 0
    }
  },
  "items": [
    "val1"
  ]
}

GET "<manager-ip>/api/v3.1/labels/blueprints/<label-key>"

Get all blueprints' labels' values for the specified key.

Response

Field	Type	Description
`items`	list	A list of all blueprints' labels' values associated with the specified key.

Cluster

The ManagerItem resource

The ManagerItem resource represents a node in the cluster

Attributes:

Attribute	Type	Description
`id`	number	The id of the manager in the cluster.
`hostname`	string	The hostname of this node.
`private_ip`	string	The internal IP of the manager used for internal communication.
`public_ip`	string	The externally accessible IP of this node.
`version`	string	Conductor version of the node.
`edition`	string	Conductor edition: community / premium / spire.
`distribution`	string	Distribution of the OS the node is running on.
`distro_release`	string	Distribution release of the OS the node is running on.
`fs_sync_node_id`	string	Syncthing node ID used for FS replication.
`networks`	dict	A dictionary of the networks associated with the node.
`ca_cert_content`	string	CA certificate used by the manager.

List Cluster Nodes

Request Example

client.manager.get_managers()

$ curl --header -u user:password "http://<manager-ip>/api/v3.1/managers"

Response Example

{
    "items":
    [
        {
            "id": 0,
            "hostname": "node1.openstack.local",
            "private_ip": "172.20.0.2",
            "public_ip": "191.31.72.16",
            "version": "5.0.0",
            "edition": "premium",
            "distribution": "centos",
            "distro_release": "core",
            "fs_sync_node_id": "P56IOI7-MZJNU2Y-IQGDREY-...",
            "networks": {
                "default": "172.20.0.2",
                "network_2": "174.40.0.4"
            },
            "ca_cert_content": "CERT CONTENT"
        }
    ]
}

GET "{manager-ip}/api/v3.1/managers"

Lists all nodes in the cluster.

Response

Field	Type	Description
`items`	list	A list of `ManagerItem` resources

Get Cluster Node

Request Example

client.manager.get_managers("<hostname>")

$ curl --header -u user:password "http://<manager-ip>/api/v3.1/managers/<hostname>"

Response Example

{
    "id": 0,
    "hostname": "node1.openstack.local",
    "private_ip": "172.20.0.2",
    "public_ip": "191.31.72.16",
    "version": "5.0.0",
    "edition": "premium",
    "distribution": "centos",
    "distro_release": "core",
    "fs_sync_node_id": "P56IOI7-MZJNU2Y-IQGDREY-...",
    "networks": {
        "default": "172.20.0.2",
        "network_2": "174.40.0.4"
    },
    "ca_cert_content": "CERT CONTENT"
}

GET "{manager-ip}/api/v3.1/managers/{hostname}"

Fetches the details of a node in the cluster.

URI Parameters

hostname: The hostname of the node to retrieve from the cluster

Response

A ManagerItem resource.

Delete Cluster Node

Request Example

client.manager.remove_manager("<hostname>")

$ curl -X DELETE -u user:password "http://<manager-ip>/api/v3.1/managers/<hostname>"

Response Example

{
    "id": 0,
    "hostname": "node1.openstack.local",
    "private_ip": "172.20.0.2",
    "public_ip": "191.31.72.16",
    "version": "5.0.0",
    "edition": "premium",
    "distribution": "centos",
    "distro_release": "core",
    "fs_sync_node_id": "P56IOI7-MZJNU2Y-IQGDREY-...",
    "networks": {
        "default": "172.20.0.2",
        "network_2": "174.40.0.4"
    },
    "ca_cert_content": "CERT CONTENT"
}

DELETE "{manager-ip}/api/v3.1/managers/{hostname}"

Removes a node from the cluster. The node disconnects from the cluster and disables all cluster mechanisms. You can rejoin it to the cluster. The node is still connected to the DB of the cluster so it is highly recommended to dispose of it once removed. Only admin users can execute this operation.

URI Parameters

hostname: The hostname of the node to remove from the cluster

Response

No content - HTTP code 204.

Cluster Status

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/cluster-status"

# Using ClodifyManager
client.cluster_status.get_status()

# Using requests
url = 'http://<manager-ip>/api/v3.1/cluster-status'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers
)
response.json()

Response Example

{
  "status": "OK",
  "services": {
    "manager": {
      "status": "OK",
      "nodes": {
        "cfy-manager": {
          "status": "OK",
          "version": "5.1",
          "public_ip": "172.20.0.2",
          "private_ip": "172.20.0.2",
          "services": {
            "Blackbox Exporter": {
              "extra_info": {
                "systemd": {
                  "display_name": "Blackbox Exporter",
                  "instances": [
                    {
                      "Description": "Prometheus blackbox exporter (HTTP/HTTPS/TCP pings)",
                      "Id": "blackbox_exporter.service",
                      "state": "running"
                    }
                  ],
                  "unit_id": "blackbox_exporter.service"
                }
              },
              "status": "Active"
            },
            "Cloudify Composer": {
              "extra_info": {
                "systemd": {
                  "display_name": "Cloudify Composer",
                  "instances": [
                    {
                      "Description": "Cloudify Composer service",
                      "Id": "cloudify-composer.service",
                      "state": "running"
                    }
                  ],
                  "unit_id": "cloudify-composer.service"
                }
              },
              "status": "Active"
            },

            ...

          }
        }
      },
      "is_external": false
    },
    "db": {
      "status": "OK",
      "nodes": {
        "cfy-db": {
          "status": "OK",
          "version": "5.1",
          "public_ip": null,
          "private_ip": "172.20.0.2",
          "services": {
            "Node Exporter": {
              "extra_info": {
                "systemd": {
                  "display_name": "Node Exporter",
                  "instances": [
                    {
                      "Description": "Prometheus exporter for hardware and OS metrics",
                      "Id": "node_exporter.service",
                      "state": "running"
                    }
                  ],
                  "unit_id": "node_exporter.service"
                }
              },
              "status": "Active"
            },
            "PostgreSQL 9.5 database server": {
              "extra_info": {
                "systemd": {
                  "display_name": "PostgreSQL 9.5 database server",
                  "instances": [
                    {
                      "Description": "PostgreSQL 9.5 database server",
                      "Id": "postgresql-9.5.service",
                      "state": "running"
                    }
                  ],
                  "unit_id": "postgresql-9.5.service"
                }
              },
              "status": "Active"
            },
            "Prometheus": {
              "extra_info": {
                "systemd": {
                  "display_name": "Prometheus",
                  "instances": [
                    {
                      "Description": "Prometheus monitoring service",
                      "Id": "prometheus.service",
                      "state": "running"
                    }
                  ],
                  "unit_id": "prometheus.service"
                }
              },
              "status": "Active"
            },

            ...

          }
        }
      },
      "is_external": false
    },
    "broker": {
      "status": "OK",
      "nodes": {
        "cfy-manager": {
          "status": "OK",
          "version": "5.1",
          "public_ip": null,
          "private_ip": "172.20.0.2",
          "services": {

            ...

          }
        }
      },
      "is_external": false
    }
  }
}

GET "{manager-ip}/api/v3.1/cluster-status"

Gets Conductor cluster status.

Getting summarised cluster status

Gets summarised cluster status and determines the return code based on it, i.e. return code 200 means: ‘OK’ or ‘Degraded’; return code 500 means: ‘FAIL’.

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/cluster-status?summary=true"

# Using ClodifyManager
client.cluster_status.get_status()

# Using requests
url = 'http://<manager-ip>/api/v3.1/cluster-status'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'summary': 'true'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring
)
response.json()

Response Example

{
  "status": "OK",
  "services": {}
}

GET "{manager-ip}/api/v3.1/cluster-status?summary=true"

Gets summary of Conductor cluster status.

Attributes:

Attribute	Type	Description
`status`	string	The status of the cluster, can be `OK`, `Degraded` or `Fail`.
`services`	object	A dictionary containing the services data of the Conductor cluster.

Deployment Groups

Deployment groups are collections of deployments, that allow operating on multiple deployments in bulk.

The Deployment Group Resource

A deployment group represents an unordered set of deployments.

Attributes:

Attribute	Type	Description
`id`	string	A unique identifier for the group.
`created_at`	datetime	The time when the group was created.
`created_by`	string	Username of the creator of this group.
`tenant_name`	string	The name of the tenant that owns the group.
`visibility`	string	The visibility of the group.
`resource_availability`	string	The availability of the group.
`private_resource`	boolean	If set, the group will only be accessible by its creator (default: False).
`description`	string	A free-form description of the group.
`default_blueprint_id`	string	ID of the blueprint to be used when creating new deployments in this group.
`default_inputs`	dict	Inputs to be used when creating new deployments in this group.
`deployment_ids`	list	IDs of the deployments belonging to this group.
`labels`	list	Labels attached to the group.

List Deployment Groups

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/deployment-groups"

# Using CloudifyClient
groups = client.deployment_groups.list()

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployment-groups'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example

{
  "items": [
    {
        "created_at": "2021-04-26T09:02:05.597Z",
        "created_by": "admin",
        "default_blueprint_id": null,
        "default_inputs": {},
        "deployment_ids": [],
        "description": null,
        "id": "g1",
        "labels": [],
        "private_resource": false,
        "resource_availability": "tenant",
        "tenant_name": "default_tenant",
        "visibility": "tenant"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 1000
    }
  }
}

GET "{manager-ip}/api/v3.1/deployment-groups"

Lists all deployment groups.

Response

Field	Type	Description
`items`	list	A list of `DeploymentGroup` resources.

Get Deployment Group

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/deployment-groups/<group-id>

# Using CloudifyClient
client.deployment_groups.get('<deployment-group-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployment-groups'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example

{
    "created_at": "2021-04-26T09:02:05.597Z",
    "created_by": "admin",
    "default_blueprint_id": "bp1",
    "default_inputs": {"inp1": "value1"},
    "deployment_ids": ["dep1", "dep2", "dep3"],
    "description": "This is a description",
    "id": "g1",
    "labels": [
      {
          "created_at": "2021-04-26T09:44:40.807Z",
          "creator_id": 0,
          "key": "x",
          "value": "y"
      }
    ],
    "private_resource": false,
    "resource_availability": "tenant",
    "tenant_name": "default_tenant",
    "visibility": "tenant"
}

GET "{manager-ip}/api/v3.1/deployment-groups/<group-id>"

Gets a deployment group.

Response

A DeploymentGroup resource.

Create/update Deployment Group

The PUT method creates-or-replaces the deployment group attributes with the ones provided in the request body.

New deployments

This endpoint can also create new deployments. Provide the specification of the deployments to be created as the new_deployments request body field, and new deployments will be created. This specification is a list of objects that can contain the fields:

id - if absent, a new deployment ID will be auto-generated
display_name - sets the display name for the deployment
inputs - these inputs will be used when creating the new deployment, merged with the default_inputs group attribute
labels - the newly-created deployment will contain these labels. By providing labels, it is possible to assign deployment object type, or deployment parents. Note that this means that new_deployments can also be a list of empty objects.
site_name - the newly-created deployments will have that site assigned
runtime_only_evaluation - sets the runtime_only_evaluation flag for the deployment
skip_plugins_validation - sets the skip_plugins_validation flag for the deployment

Visibility and private_resource for the newly-created deployment are inherited from the group.

Deployment ID template

The id parameter is a string that can contain template parameters:

{uuid} - replaced with a new UUID4
{count} - sequential number, increasing for every deployment created by the group
{group_id} - replaced with the Deployment Group ID
{blueprint_id} - ID of the Deployment Group’s default blueprint
{site_name} - the site name passed in the new deployment spec

If there are new deployments created, an ExecutionGroup resource will also be created, containing the new deployments' create_deployment_environment executions.

Adding existing deployments

There’s several ways of adding existing deployments to the group:

deployment_ids - specify the deployments to be added by the deployments' IDs
filter_id - add deployments returned by this filter
filter_rules - add deployments returned by these filter rules
deployments_from_group - add deployments belonging to another group, specified by that group’s ID

Labels

Labels added to the group will also be added to all deployments in the group. New deployments created as part of the group, will inherit the group’s labels. Removing a label from the group will remove it from all deployments in the group.

Request Example

$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"description": "hello", "deployment_ids": ["dep1", "dep2"]}' \
    "http://<manager-ip>/api/v3.1/deployment-groups/<group-id>"

# Using CloudifyClient
client.deployment_groups.put(
    blueprint_id='<blueprint-id>',
    new_deployments=[
      {
        'labels': [{'csys-environment': 'env1'}],
        'id': 'dep-1',
        'inputs': {'inp1': 'value'}
      }
    ],
    labels=[{'<key1': '<val1>', '<key2>': '<val2>'}]
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployment-groups/<group-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
payload ={
    'blueprint_id': '<blueprint-id>',
    'default_inputs': {'inp1': 'value'},
}
response = requests.put(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    json=payload,
)
response.json()

PUT "{manager-ip}/api/v3.1/deployment-groups/{group-id}"

URI Parameters

group-id: The id of the new-or-updated group.

Request Body

Property	Type	Description
`blueprint_id`	string	The ID of the default blueprint for this group.
`default_inputs`	object	Default inputs for creating new deployments in this group.
`description`	string	A freeform description.
`labels`	list	A list of labels to assign to the group.
`visibility`	string	Optional parameter, defines who can see the deployment (default: tenant).
`deployment_ids`	list	A list of deployments this group should contain.
`filter_id`	string	The group will contain deployments returned by this filter.
`filter_rules`	list	The group will contain deployments returned by these filter rules.
`deployments_from_group`	string	The group will contain deployments that belong to this group.
`new_deployments`	list	Create new deployments specified by this list and add them to the group.

Valid visibility values are:

private: The resource is visible to the user that created the resource, the tenant’s managers and the system’s admins.
tenant: The resource is visible to all users in the current tenant. (Default value)
global: The resource is visible to all users in all tenants across the manager. A deployment can only be global if the blueprint from which it was created is also global. Only administrators or users with access to the tenant on which the deployment was created have permissions to execute workflow on it.

Response

A DeploymentGroup resource.

Add or remove deployments from group

Request Example

$ curl -X PATCH \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"add": {"deployment_ids": ["dep1", "dep2"]}, "remove": {"deployment_ids": ["dep3"]}}'
    "http://<manager-ip>/api/v3.1/deployment-groups/<group-id>

client.deployment_groups.add_deployments(
  'group1',
  deployment_ids=['dep1'],
  new_deployments=[{}, {}, {}],
  filter_id='filter1',
  filter_rules=[{'key': 'label1',
                 'values': ['value1', 'value2'],
                 'operator': 'any_of',
                 'type': 'label'}],
  deployments_from_group='group2',
)

client.deployment_groups.add_deployments(
  'group1',
  # the REST client has a `count` shorthand - this is equivalent
  # to `new_deployments` with 10 empty objects
  count=10
)

client.deployment_groups.add_deployments(
  'group1',
  count=20000,
  # the REST client can split creating huge amount of deployments into
  # several requests: in this case it would do 20 PATCH requests behind
  # the scenes
  batch_size=1000,
)

client.deployment_groups.remove_deployments(
  'group1',
  deployment_ids=['dep2'],
  filter_id='filter2',
  filter_rules=[{'key': 'label1',
                 'values': ['value1'],
                 'operator': 'any_of',
                 'type': 'label'}],
  deployments_from_group='group3',
)

PATCH "{manager-ip}/api/v3.1/deployment-groups/{group-id}"

Adding or removing deployments from a group without overwriting the whole group or its contents is done by specifying the deployments to add and to remove in the body of a PATCH request.

The body of that request can contain the objects add or remove, specifying the deployments to be added and deleted. These object contain keys similar to the deployment-adding fields that the PUT request supports.

If a deployment is both added and removed at the same time (possibly using different ways, eg. added by filter but removed by id), it stays removed.

Adding deployments

The add object can contain the following fields (those are the same fields that were available for specifying deployments in the PUT request):

deployment_ids: add deployments specified by their IDs
filter_id: add deployments returned by this filter
filter_rules: add deployments returned by these filter rules
deployments_from_group: add deployments belonging to another group, specified by that group’s ID
new_deployments: create new deployments in the group. Same semantics as in the PUT request.

The time this request would take depends highly on the manager machine and the connection to it, but amounts on the order of 5000 are considered safe, while amounts on the order of 50000 are considered too high.

Removing deployments

The remove object can contain the following fields (these are similar to the ones available in add or in the PUT request, except for new_deployments):

deployment_ids: remove the deployment specified by their IDs
filter_id: remove deployments returned by this filter
filter_rules: remove deployments returned by these filter rules
deployments_from_group: remove deployments belonging to the group given by this ID

Request Body

Property	Type	Description
add	object	Specify the deployments to be added to the group
remove	object	Specify the deployments to be removed from the group

Response

A DeploymentGroup resource.

Delete Deployment Group

Request Example

$ curl -X DELETE \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/deployment-groups/<group-id>

# Using CloudifyClient
client.deployment_groups.delete(
    '<group-id>',
    delete_deployments=False,
    force=False,
    with_logs=False)

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployment-groups/<group-id>'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'delete_logs': True
}
requests.delete(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)

DELETE "{manager-ip}/api/v3.1/deployment-groups/{group-id}"

Deletes a deployment group. If delete_deployments is “true”, also bulk-delete all deployments in the group. In case of deleting deployments, same semantics as in Deployments DELETE apply, regarding live nodes and the force flag

URI Parameters

delete_deployments: if “true”, also delete all deployments belonging to this group
force: Same meaning as in Deployments DELETE
delete_logs: Same meaning as in Deployments DELETE
recursive: Same meaning as in Deployments DELETE

Response

No content - HTTP code 204.

cfy Deployment Group

Usage:

Manage deployment groups

Options:

-h, –help Show this message and exit

Command	Description
`create`	Create a new deployment group
`delete`	Delete a deployment group
`extend`	Add deployments to a group
`labels`	Handle a group’s labels
`list`	List all deployment groups
`shrink`	Remove deployments from a group
`update`	Update a deployment group
`update-deployments`	Update all deployments in the group

cfy deployment groups create

Usage: cfy deployment groups create [OPTIONS] DEPLOYMENT_GROUP_NAME

Option	Description
`-i`, `--inputs TEXT`	Inputs for the deployment (Can be provided as wildcard based paths (*.yaml, /my_inputs/, etc..) to YAML files, a JSON string or as ‘key1=value1;key2=value2’). This argument can be used multiple times
`-b`, `--default-blueprint TEXT`	Default blueprint for this deployment group
`--description TEXT`	Description of this deployment group
`-h`, `--help`	Show this message and exit.

Example:

cfy deployment group create group_test

Output:

Group group_test created

cfy deployment groups delete

Usage: cfy deployment groups delete [OPTIONS] DEPLOYMENT_GROUP_NAME

Option	Description
`--delete-deployments`	Delete all deployments belonging to this group
`-l, --with-logs`	If set, then the deployment’s management workers logs are deleted as well [default: False]
`-f, --force`	Delete the deployment even if there are existing live nodes for it, or existing installations which depend on it
`-h, --help`	Show this message and exit.

example:

cfy deployment group delete group_test

output:

Group group_test deleted

cfy deployment groups extend

Usage: cfy deployment groups extend [OPTIONS] DEPLOYMENT_GROUP_NAME

Option	Description
`-d, --deployment-id TEXT`	Deployment ID to add or remove from the group
`--count INTEGER`	Create this many deployments in the group
`--filter-id TEXT`	Use deployments selected by this filter
`-lr, --labels-rule TEXT`	A labels' filter rule. Labels' filter rules must be one of: <key>=<value>, <key>!=<value>, <key> is-not <value>, <key> is null, <key> is not null. <value> can be a single string or a list of strings of the form [<value1>,<value2>,…]. Any comma and colon in <value> must be escaped with `\`. The labels' keys specified in the filter rules will be saved in lower case.
`-ar, --attrs-rule TEXT`	An attributes' filter rule. Attributes' filter rules must be one of: <key>=<value>, <key>!=<value>, <key> contains <value>, <key> does-not-contain <value<, <key> starts-with <value>, <key> ends-with <value>, <key> is not empty. <value> can be a single string or a list of strings of the form [<value1>,<value2>,…]. Allowed attributes to filter by are: [blueprint_id, created_by, site_name, schedules]. This argument can be used multiple times
`--from-group TEXT`	Use deployments belonging to this group
`--into-environments TEXT`	Add created deployments to the environments already existing in this group. You cannot use this argument with arguments: [count]
`-h, --help`	Show this message and exit.

example:

cfy deployment group extend group_test

output:

Group group_test updated. It now contains &lt:number&gt; deployments

cfy deployment groups labels

Usage: cfy deployment groups labels [OPTIONS] COMMAND [ARGS]…

Options	Description
`--manager TEXT`	Connect to a specific manager by IP or host
`-q, --quiet`	Show only critical logs
`--format`	[plain
`-v, --verbose`	Show verbose output. You can supply this up to three times (i.e. -vvv)
`--json`
`-h, –help \| Show this message and exit.

Commands

add

Add labels to a group

cfy deployment group labels add [OPTIONS] LABELS_LIST DEPLOYMENT_GROUP_NAME LABELS_LIST: <key>:<value>,<key>:<value>

Options	Description
`-t, --tenant-name TEXT`	The name of the tenant of the group. If not specified, the current tenant will be used
`--manager TEXT`	Connect to a specific manager by IP or host
`-q, --quiet`	Show only critical logs
`--format`	[plain
`-v, --verbose`	Show verbose output. You can supply this up to three times (i.e. -vvv)
`--json`
`-h, --help`	Show this message and exit.

example:

cfy deployment group labels add key:value group_test

output:

Adding labels to deployment group group_test...
The following label(s) were added successfully to deployment group group_test:
[
{'key': 'value'}
]

delete

Delete labels from a group

cfy deployment group labels delete [OPTIONS] LABEL DEPLOYMENT_GROUP_NAME LABEL: Can be either <key>:<value> or <key>. If <key> is provided, all labels associated with this key will be deleted from the group.

Options	Description
`-t, --tenant-name TEXT`	The name of the tenant of the group. If not specified, the current tenant will be used
`--manager TEXT`	Connect to a specific manager by IP or host
`-q, --quiet`	Show only critical logs
`--format`	[plain
`-v, --verbose`	Show verbose output. You can supply this up to three times (i.e. -vvv)
`--json`
`-h, --help`	Show this message and exit.

example:

cfy deployment group labels delete key group_test

output:

Deleting labels from deployment group group_test...
The following label(s) were deleted successfully from deployment group group_test:
[
{'key': 'value'}
]

list

List the labels of a group

cfy deployment group labels list [OPTIONS] DEPLOYMENT_GROUP_NAME

Options	Description
`-t, --tenant-name TEXT`	The name of the tenant of the group. If not specified, the current tenant will be used
`--manager TEXT`	Connect to a specific manager by IP or host
`-q, --quiet`	Show only critical logs
`--format`	[plain
`-v, --verbose`	Show verbose output. You can supply this up to three times (i.e. -vvv)
`--json`
`-h, --help`	Show this message and exit.

example:

cfy deployment group labels list group_test

output:

Listing labels of deployment group group_test...

Deployment group labels
-------------------+
| key | values |
-------------------+
-------------------+

cfy deployment groups list

Usage: cfy deployment groups list [OPTIONS]

Options	Description
`-x, --extended-view`	Display results in a vertical table format
`-h, --help`	Show this message and exit.

example:

cfy deployment groups  list

output:

Deployment groups:

+------------+-------------+-------------+----------------------+
| id         | deployments | description | default_blueprint_id |
|------------|-------------|-------------|----------------------|
| group_test | 0           |             |                      |
+------------+-------------+-------------+----------------------+

cfy deployment groups shrink

Usage: cfy deployment groups shrink [OPTIONS] DEPLOYMENT_GROUP_NAME

Option	Description
`-d, --deployment-id TEXT`	Deployment ID to add or remove from the group
`--filter-id TEXT`	Use deployments selected by this filter
`lr, --labels-rule TEXT`	A labels' filter rule. Labels' filter rules must be one of: <key>=<value>, <key>!=<value>, <key> is-not <value>, <key> is null, <key> is not null. <value> can be a single string or a list of strings of the form [<value1>,<value2>,…]. Any comma and colon in <value> must be escaped with `\`. The labels' keys specified in the filter rules will be saved in lower case.
`-ar, --attrs-rule TEXT`	An attributes' filter rule. Attributes' filter rules must be one of: &lt:key>=<value>, <key>!=<value>, <key> contains <value>, <key> does-not-contain <value>, <key> starts-with <value>, <key> ends-with <value>, <key> is not empty. <value> can be a single string or a list of strings of the form [<value1>,<value2>,…]. Allowed attributes to filter by are: [blueprint_id, created_by, site_name, schedules]. This argument can be used multiple times
`--from-group TEXT`	Use deployments belonging to this group
`-h, --help`	Show this message and exit.

example:

cfy deployment groups shrink group_test

output:

Unlinked deployments . Group group_test now has <number> deployments

cfy deployment groups update

Usage: cfy deployment groups update [OPTIONS] DEPLOYMENT_GROUP_NAME

Option	Description
`-i, --inputs TEXT`	Inputs for the deployment (Can be provided as wildcard based paths (*.yaml, /my_inputs/, etc..) to YAML files, a JSON string or as ‘key1=value1;key2=value2’). This argument can be used multiple times
`-b, --default-blueprint TEXT`	Default blueprint for this deployment group
`--description TEXT`	Description of this deployment group
`-h, --help`	Show this message and exit.

example:

cfy deployment groups update group_test

output:

Group group_test updated

cfy deployment groups update-deployments

Usage: cfy deployment groups update-deployments [OPTIONS] GROUP_ID

Update all deployments in the given group.

If updating with a new blueprint, the blueprint must already be uploaded. Arguments have the same meaning as in single-deployment update, except that preview is not supported. This creates an execution-group with an update workflow for each deployment in the group.

Options	Description
`-b, --blueprint-id TEXT`	The unique identifier for the blueprint
`-i, --inputs TEXT`	Inputs for the deployment (Can be provided as wildcard based paths (*.yaml, /my_inputs/, etc..) to YAML files, a JSON string or as ‘key1=value1;key2=value2’). This argument can be used multiple times
`-r, --reinstall-list TEXT`	Node instances ids to be reinstalled as part of deployment update. They will be reinstalled even if the flag –skip-reinstall has been supplied
`-w, --workflow-id TEXT`	The workflow to execute [default: None]
`--skip-install`	Skip install lifecycle operations
`--skip-uninstall`	Skip uninstall lifecycle operations
`--skip-reinstall`	Skip automatically reinstall node-instances that their properties has been modified, as part of a deployment update. Node instances that were explicitly given to the reinstall list will still be reinstalled
`--ignore-failure`	Supply the parameter `ignore_failure` with the value `true` to the uninstall workflow
`--install-first`	In deployment update, perform install workflow and then uninstall workflow. default: uninstall and then install
`--dont-update-plugins`	Don’t update the plugins.
`-f, --force`	Force running the update also in case a deployment is used as a component
`-t, --tenant-name TEXT`	The name of the tenant of the group. If not specified, the current tenant will be used
`--manager TEXT`	Connect to a specific manager by IP or host
`-q, --quiet`	Show only critical logs
`--format`	[plain
`-v, --verbose`	Show verbose output. You can supply this up to three times (i.e. -vvv)
`--json`
`--runtime-only-evaluation`	If set, all intrinsic functions will only be evaluated at runtime, and no intrinsic functions will be evaluated at parse time (such as get_input, get_property)
`--auto-correct-types`	If set, before creating plan for a new deployment, an attempt will be made to cast old inputs' values to the valid types declared in blueprint
`--reevaluate-active-statuses`	If set, before attempting to update, the statuses of previous active update operations will be reevaluated based on relevant executions' statuses. `terminated` executions will be mapped to `successful` updates, while `failed` and any `cancel` statuses will be mapped to `failed`.
`-h, --help`	Show this message and exit.

example:

cfy deployment groups update-deployments group_test

output:

Starting update of all deployments in group group_test

Deployments

The Deployment Resource

Attributes:

Attribute	Type	Description
`blueprint_id`	string	The id of the blueprint the deployment is based on.
`created_at`	datetime	The time when the deployment was created.
`created_by`	string	The name of the user that created the deployment.
`description`	string	Deployment description.
`groups`	object	A dictionary containing the groups definition of deployment.
`id`	string	A unique identifier for the deployment.
`inputs`	object	A dictionary containing key value pairs which represents a deployment input and its provided value.
`outputs`	object	A dictionary containing an outputs definition of a deployment.
`capabilities`	object	A dictionary containing an capabilities definition of a deployment.
`site_name`	string	The name of the site the deployment is assigned to.
`policy_triggers`	object	A dictionary containing policy triggers of a deployment.
`policy_types`	object	A dictionary containing policies of a deployment.
`tenant_name`	string	The name of the tenant that owns the deployment.
`updated_at`	datetime	The time the deployment was last updated at.
`workflows`	list	A list of workflows that can be executed on a deployment.
`labels`	list	A list of the deployment’s labels.
`latest_execution_status`	string	The The deployment latest execution status.
`installation_status`	string	The deployment installation status.
`deployment_status`	string	The overall deployment status.
`sub_services_status`	string	The aggregated sub services(deployments) status.
`sub_environments_status`	string	The aggregated sub environments(deployments) status.
`sub_services_count`	integer	The aggregated sub services count.
`sub_environments_count`	integer	The aggregated sub environments count.
`environment_type`	string	The environment type. Represents the value of `csys-env-type` label attached to deployment.
`create_execution`	string	The ID of the create_deployment_environment execution for this deployment.
`latest_execution`	string	The ID of the most-recent execution on this deployment.
`latest_execution_status`	string	The The deployment latest execution status.
`latest_execution_total_operations`	integer	The total operations for latest execution of deployment.
`latest_execution_finished_operations`	integer	The finished operations for latest execution of deployment.

List Deployments

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/deployments?_include=id"

# Using ConductorClient
deployments = client.deployments.list(_include=['id'])
for deployment in deployments:
  print deployment

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "hello1"
    },
    {
      "id": "hello2"
    },
    {
      "id": "hello3"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/deployments"

Lists all deployments.

Response

Field	Type	Description
`items`	list	A list of `Deployment` resources.

Get Deployment

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/deployments?id=<deployment-id>&_include=id"

# Using ConductorClient
client.deployments.get(deployment_id='<deployment-id>', _include=['id'])

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'id': '<deployment-id>',
    '_include': 'id',
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Get Deployment API supports query string param called all_sub_deployments where the default value is True which means the values for sub_services_count and sub_environments_count will contain the numbers of deployments attached to this deployment recursively. Otherwise, if all_sub_deployments is False it will only contains the first level of deployments (services/environments)

Response Example

{
  "items": [
    {
      "id": "hello1"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/deployments?id={deployment-id}"

Gets a deployment.

URI Parameters

deployment-id: The id of the deployment.

Response

A Deployment resource.

Create Deployment

Request Example

$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"blueprint_id": "<blueprint-id>", "inputs": {...}, "visibility": "<visibility>", "site_name": "<site name>", "labels": [{"<key1>": "<val1>"}, {"<key2>": "<val2>"}]}' \
    "http://<manager-ip>/api/v3.1/deployments/<deployment-id>?_include=id"

# Using ConductorClient
client.deployments.create(
    blueprint_id='<blueprint-id>',
    deployment_id='<deployment-id>',
    inputs={...},
    visibility='<visibility>',
    site_name='<site name>',
    labels=[{'<key1': '<val1>', '<key2>': '<val2>'}]
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments/<deployment-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'_include': 'id'}
payload ={
    'blueprint_id': '<blueprint-id>',
    'inputs': {...},
    'visibility': '<visibility>',
    'site_name': '<site name>',
    'labels': [{'<key1>': '<val1>'}, {'<key2>': '<val2>'}]
}
response = requests.put(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Response Example

{
  "id": "hello4"
}

PUT -d '{"blueprint_id": "<blueprint-id>", "inputs": {...}}' "{manager-ip}/api/v3.1/deployments/{deployment-id}"

Creates a new deployment.

URI Parameters

deployment-id: The id of the new deployment.

Request Body

Property	Type	Description
`blueprint_id`	string	The id of the blueprint the new deployment will be based on (required).
`inputs`	object	The dictionary containing key value pairs which represents the deployment inputs.
`site_name`	string	The name of the site to assign the new deployment to.
`labels`	list	A list of labels to assign to the new deployment.
`private_resource`	boolean	Optional parameter, if set to True the uploaded resource will only be accessible by its creator. Otherwise, the resource is accessible by all users that belong to the same tenant (default: False).
`skip_plugins_validation`	boolean	Optional parameter, determines whether to validate if the required deployment plugins exist on the manager (default: False).
`visibility`	string	Optional parameter, defines who can see the deployment (default: tenant).

Valid visibility values are:

private: The resource is visible to the user that created the resource, the tenant’s managers and the system’s admins.
tenant: The resource is visible to all users in the current tenant. (Default value)
global: The resource is visible to all users in all tenants across the manager. A deployment can only be global if the blueprint from which it was created is also global. Only administrators or users with access to the tenant on which the deployment was created have permissions to execute workflow on it.

Response

A Deployment resource.

Delete Deployment

Request Example

$ curl -X DELETE \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/deployments/<deployment-id>?_include=id&delete_logs=True"

# Using ConductorClient
client.deployments.delete(deployment_id='<deployments-id>',
                          with_logs=False)

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments/<deployment-id>'
headers = {'content-type': 'application/json'}
querystring = {
    'delete_logs': True
}
requests.delete(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)

DELETE "{manager-ip}/api/v3.1/deployments/{deployment-id}"

Deletes a deployment.

An error is raised if the deployment has any live node instances, or there are installations which depend on this deployment. In order to ignore this validation, the force argument in the URI can be used.

URI Parameters

deployment-id: The id of the deployment.
delete_logs: Determines whether to delete the deployment logs, default: false.
force: Specifies whether to force deployment deletion even if there are existing live nodes for it, or existing installations which depend on it. Default: false
recursive: Also delete all service deployments that use the selected deployment as their environment. Default: false

Response

No content - HTTP code 204.

Set Deployment Visibility

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"visibility": "<visibility>"}' \
    "http://<manager-ip>/api/v3.1/deployments/<deployment-id>/set-visibility"

# Python Client
client.deployments.set_visibility('<deployment-id>', '<visibility>')

Response Example

{
  "inputs": {
    ...
  },
  "permalink": null,
  "description": "deployment_1",
  "blueprint_id": "blueprint_1",
  "policy_types": {
    ...
  },
  "tenant_name": "default_tenant",
  "created_at": "2017-12-17T09:28:22.800Z",
  "updated_at": "2017-12-17T09:29:20.750Z",
  "created_by": "admin",
  "policy_triggers": {
    ...
  },
  "private_resource": false,
  "visibility": "tenant",
  "groups": {
    ...
  },
  "workflows": {
    ...
  },
  "id": "deployment_1",
  "outputs": {
    ...
  },
  "labels": [
    ...
  ]
}

PATCH "<manager-ip>/api/v3.1/deployments/{deployment-id}/set-visibility"

Update the visibility of the deployment.

URI Parameters

deployment-id: The id of the deployment to update.

Request Body

Property	Type	Description
`visibility`	string	Defines who can see the deployment. (Required)

Valid values are tenant or global.

Response

A Deployment resource.

Set Deployment Site

Request Example

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"site_name": "<site name>"}' \
    "http://<manager-ip>/api/v3.1/deployments/<deployment-id>/set-site"

# Python Client
client.deployments.set_site('<deployment-id>', site_name='<site name>', detach_site=False)

Response Example

{
  "inputs": {
    ...
  },
  "permalink": null,
  "description": "deployment_1",
  "blueprint_id": "blueprint_1",
  "tenant_name": "default_tenant",
  "created_at": "2017-12-17T09:28:22.800Z",
  "updated_at": "2017-12-17T09:29:20.750Z",
  "created_by": "admin",
  "site_name": "a site name",
  "private_resource": false,
  "visibility": "tenant",
  "groups": {
    ...
  },
  "workflows": {
    ...
  },
  "id": "deployment_1",
  "outputs": {
    ...
  },
  "labels": [
    ...
  ]
}

POST "<manager-ip>/api/v3.1/deployments/{deployment-id}/set-site"

Update the site of the deployment.

URI Parameters

deployment-id: The id of the deployment to update.

Request Body

Property	Type	Description
`site_name`	string	The site name to assign the deployment.
`detach_site`	Boolean	Clear site relation from the deployment.

Response

A Deployment resource.

The Deployment Update Resource

Attributes:

Attribute	Type	Description
`id`	string	A unique identifier for the deployment update.
`deployment_id`	string	The id of the deployment.
`old_blueprint_id`	string	The id of the deployment’s blueprint before the update.
`new_blueprint_id`	string	The id of the deployment’s blueprint after the update.
`old_inputs`	string	The inputs of the deployment before the update.
`new_inputs`	string	The inputs of the deployment after the update.
`state`	string	The state of this update (“updating”, “executing_workflow”, “finalizing”, “successful”, “failed”, or “preview”).
`tenant_name`	string	The name of the tenant the deployment belongs to.
`created_at`	datetime	The time when the deployment update was started.
`created_by`	string	The name of the user that started the deployment update.
`execution_id`	string	The id of the execution performing the update.
`private_resource`	boolean	Is the deployment private.
`visibility`	string	The visibility of the deployment.
`resource_availability`	string	The availability of the deployment.
`deployment_update_nodes`	object	The list of the nodes in the deployment update.
`deployment_update_node_instances`	object	A dict containing the node instances in the deployment update.
`modified_entity_ids`	object	A dict containing the modified entities.
`steps`	object	The list of deployment update steps.
`deployment_plan`	object	A dict of the deployment plan.
`deployment_update_deployment`	object	A dict of the raw deployment.
`central_plugins_to_install`	list	A list of the plugins that are executed by the central deployment agent and will be installed.
`central_plugins_to_uninstall`	list	A list of the plugins that are executed by the central deployment agent and will be uninstalled.

Update Deployment

Request Example

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"skip_install": "<skip_install>", "skip_uninstall": "<skip_uninstall>", "skip_reinstall": "<skip_reinstall>", "force": "<force>", "ignore_failure": "<ignore_failure>", "install_first": "<install_first>", "blueprint_id": "<blueprint_id>", "inputs": "<inputs>", "reinstall_list": "<reinstall_list>", "update_plugins": "<update_plugins>"}' \
    "http://<manager-ip>/api/v3.1/deployment-updates/<deployment-id>/update/initiate"

# Python Client
client.deployment_updates.update_with_existing_blueprint(skip_install="<skip_install>", skip_uninstall="<skip_uninstall>", skip_reinstall="<skip_reinstall>", force="<force>", ignore_failure="<ignore_failure>", install_first="<install_first>", blueprint_id="<blueprint_id>", inputs="<inputs>", reinstall_list="<reinstall_list>")

Response Example

{
  "old_inputs": {
    ...
  },
  "new_inputs": {
    ...
  },
  "state": "successful",
  "deployment_id": "deployment_1",
  "old_blueprint_id": "blueprint_1",
  "new_blueprint_id": "blueprint_2",
  "steps": [
    ...
  ],
  "tenant_name": "default_tenant",
  "created_at": "2017-12-17T09:28:22.800Z",
  "created_by": "admin",
  "execution_id": "f92754a0-4cf4-4baa-80d3-0602f03f2b91",
  "deployment_update_deployment": {
    ...
  },
  "private_resource": false,
  "visibility": "tenant",
  "resource_availability": "tenant",
  "modified_entity_ids": {
    ...
  },
  "deployment_plan": {
    ...
  },
  "id": "deployment_1-b22cd6b3-6dc1-4215-b9c0-404155eea939",
  "deployment_update_node_instances": {
    ...
  }
  "deployment_update_nodes": [
    ...
  ],
  "central_plugins_to_install": [
    ...
  ],
  "central_plugins_to_uninstall": [
    ...
  ]
}

POST "<manager-ip>/api/v3.1/deployment-updates/<deployment-id>/update/initiate"

Update the deployment, supported for Conductor Manager 4.4 and above. Since Conductor 7.0, previously deprecated PUT method is no longer supported.

URI Parameters

deployment-id: The id of the deployment to update.

Request Body

Property	Type	Description
`blueprint_id`	string	The id of the blueprint to use for the update
`skip_install`	boolean	Determines whether to skip installing node instances in update workflow
`skip_install`	boolean	Determines whether to skip uninstalling node instances in update workflow
`skip_reinstall`	boolean	Determines whether to reinstall the node instances whose properties or operations are modified in the deployment update
`skip_drift_check`	boolean	If set, do not run check_drift as part of the update
`force_reinstall`	boolean	Reinstall all changed instances, instead of running the update operations
`skip_heal`	boolean	Do not run check_status and heal before the update
`force`	boolean	Force running update even if previous update failed
`ignore_failure`	boolean	Ignore operation failures while unisntalling node instances in update workflow
`install_first`	boolean	Install new node instances before reinstalling removed ones (default: first uninstall, then install)
`inputs`	object	Dictionary containing inputs to update in the deployment
`reinstall_list`	object	List of IDs for node instances to reinstall (even if skip_reinstall is true)
`preview`	boolean	If set, does not perform the update and returns the steps this update would make (default: False). Supported for Conductor Manager 5.0 and above.
`runtime_only_evaluation`	boolean	sets the `runtime_only_evaluation` flag for the deployment

Response

A Deployment Update resource.

Get Deployment-Update

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/deployment-updates/<deployment-update-id>?_include=id"

# Using ConductorClient
deployment_update = client.deployment_updates.get(update_id)

Response Example

{
  "old_inputs": {
    ...
  },
  "new_inputs": {
    ...
  },
  "state": "successful",
  "deployment_id": "deployment_1",
  "old_blueprint_id": "blueprint_1",
  "new_blueprint_id": "blueprint_2",
  "steps": [
    ...
  ],
  "tenant_name": "default_tenant",
  "created_at": "2017-12-17T09:28:22.800Z",
  "created_by": "admin",
  "execution_id": "f92754a0-4cf4-4baa-80d3-0602f03f2b91",
  "deployment_update_deployment": {
    ...
  },
  "private_resource": false,
  "visibility": "tenant",
  "resource_availability": "tenant",
  "modified_entity_ids": {
    ...
  },
  "deployment_plan": {
    ...
  },
  "id": "deployment_1-b22cd6b3-6dc1-4215-b9c0-404155eea939",
  "deployment_update_node_instances": {
    ...
  }
  "deployment_update_nodes": [
    ...
  ],
  "central_plugins_to_install": [
    ...
  ],
  "central_plugins_to_uninstall": [
    ...
  ]
}

GET "{manager-ip}/api/v3.1/deployment-updates/<deployment-update-id>"

Get a deployment update.

Response

A Deployment Update resource.

List Deployment Updates

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/deployment-updates?_include=id"

# Using ConductorClient
deployment_updates = client.deployment_updates.list(
        sort=sort_by,
        is_descending=descending,
        _all_tenants=all_tenants,
        _search=search,
        _offset=pagination_offset,
        _size=pagination_size,
        deployment_id=deployment_id
    )

Response Example

{
  "items": [
    {
      "id": "update1"
    },
    {
      "id": "update2"
    },
    {
      "id": "update3"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/deployment-updates"

Lists deployment updates.

Response

Field	Type	Description
`items`	list	A list of `Deployment Update` resources.

Get Deployment Outputs

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/deployments/<deployment-id>/outputs"

# Using ConductorClient
client.deployments.outputs.get(deployment_id='<deployment-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments/<deployment-id>/outputs'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example

{
  "deployment_id": "dep",
  "outputs": {
    "output_1": "node_vbs4o4",
    "output_2": "some_value"
  }
}

GET "{manager-ip}/api/v3.1/deployments/{deployment-id}/outputs"

Gets deployment outputs.

URI Parameters

deployment-id: The id of the deployment.

Response

A DeploymentOutput resource.

Get Deployment Capabilities

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/deployments/<deployment-id>/capabilities"

# Using ConductorClient
client.deployments.capabilities.get(deployment_id='<deployment-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments/<deployment-id>/capabilities'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example

{
  "deployment_id": "dep",
  "capabilities": {
    "capability_1": "node_vbs4o4",
    "capability_2": "some_capability"
  }
}

GET "{manager-ip}/api/v3.1/deployments/{deployment-id}/capabilities"

Gets deployment capabilities.

URI Parameters

deployment-id: The id of the deployment.

Response

A DeploymentOutput resource.

Get Inter Deployment Dependencies List

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/deployments/inter-deployment-dependencies"

# Using ConductorClient
client.inter_deployment_dependencies.list()

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments/inter-deployment-dependencies'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example

{
  "items": [
    {
      "dependency_creator": "nodes.jboss.operations.cloudify.interfaces.lifecycle.stop.inputs.fabric_env.key_filename.get_capability",
      "tenant_name": "default_tenant",
      "created_at": "2020-04-27T06:51:29.543Z",
      "visibility": "tenant",
      "private_resource": false,
      "target_deployment_id": null,
      "resource_availability": "tenant",
      "created_by": "admin",
      "id": "769589d1-51bf-4f18-bcc5-726fa667a10a",
      "source_deployment_id": "jboss-app"
    },
    {
      "dependency_creator": "component.infrastructure_vkd2zx",
      "tenant_name": "default_tenant",
      "created_at": "2020-04-27T06:51:43.124Z",
      "visibility": "tenant",
      "private_resource": false,
      "target_deployment_id": "infrastructure_vkd2zx",
      "resource_availability": "tenant",
      "created_by": "admin",
      "id": "7392a4ad-484c-4b6f-aa42-75d78e884918",
      "source_deployment_id": "jboss-app"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 1000
    }
  }
}

GET "{manager-ip}/api/v3.1/deployments/inter-deployment-dependencies"

Gets an inter deployment dependencies list.

Create Inter Deployment Dependency

Request Example

$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"dependency_creator": "<dependency_creator>", "source_deployment": "<source_deployment>", "target_deployment": "<target_deployment>"}' \
    "http://<manager-ip>/api/v3.1/deployments/inter-deployment-dependencies"

# Using ConductorClient
client.inter_deployment_dependencies.create(
    dependency_creator='<dependency_creator>',
    source_deployment='<source_deployment>',
    target_deployment='<target_deployment>'
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments/inter-deployment-dependencies'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
payload ={
    'dependency_creator': '<dependency_creator>',
    'source_deployment': '<source_deployment>',
    'target_deployment': '<target_deployment>'
}
response = requests.put(
    url,
    auth=('<manager-username>', '<manager-password>'),
    headers=headers,
    json=payload,
)
response.json()

Response Example

{
  "dependency_creator": "component.infrastructure_vkd2zx",
  "tenant_name": "default_tenant",
  "created_at": "2020-04-27T08:24:45.938Z",
  "visibility": "tenant",
  "private_resource": false,
  "target_deployment_id": "infrastructure_vkd2zx",
  "resource_availability": "tenant",
  "created_by": "admin",
  "id": "451f2d61-448a-47db-a786-aa8b64c905ed",
  "source_deployment_id": "jboss-app"
}

PUT -d '{"dependency_creator": "<dependency_creator>", "source_deployment": "<source_deployment>", "target_deployment": "<target_deployment>"}'

Creates a new inter deployment dependency.

Delete Inter Deployment Dependency

Request Example

$ curl -X DELETE \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"dependency_creator": "<dependency_creator>", "source_deployment": "<source_deployment>", "target_deployment": "<target_deployment>"}' \
    "http://<manager-ip>/api/v3.1/deployments/inter-deployment-dependencies"

# Using ConductorClient
client.inter_deployment_dependencies.delete(
    dependency_creator='<dependency_creator>',
    source_deployment='<source_deployment>',
    target_deployment='<target_deployment>'
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments/inter-deployment-dependencies'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
payload ={
    'dependency_creator': '<dependency_creator>',
    'source_deployment': '<source_deployment>',
    'target_deployment': '<target_deployment>'
}
response = requests.delete(
    url,
    auth=('<manager-username>', '<manager-password>'),
    headers=headers,
    json=payload,
)
response.json()

Response Example

{
  "dependency_creator": "component.infrastructure_vkd2zx",
  "tenant_name": "default_tenant",
  "created_at": "2020-04-27T08:24:45.938Z",
  "visibility": "tenant",
  "private_resource": false,
  "target_deployment_id": "infrastructure_vkd2zx",
  "resource_availability": "tenant",
  "created_by": "admin",
  "id": "451f2d61-448a-47db-a786-aa8b64c905ed",
  "source_deployment_id": "jboss-app"
}

DELETE -d '{"dependency_creator": "<dependency_creator>", "source_deployment": "<source_deployment>", "target_deployment": "<target_deployment>"}'

Deletes an inter deployment dependency.

Update (add / delete) Deployment Labels

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"labels": [{"<key1>": "<val1>"}, {"<key2>": "<val2>"}]}' \
    "http://<manager-ip>/api/v3.1/deployments/<deployment-id>"

# Python Client
client.deployments.update_labels(
deployment_id='<deployment-id>',
labels=[{'<key1>': '<val1>', '<key2>': '<val2>'}]
)

Response Example

{
  "inputs": {
    ...
  },
  "permalink": null,
  "description": "deployment_1",
  "blueprint_id": "blueprint_1",
  "policy_types": {
    ...
  },
  "tenant_name": "default_tenant",
  "created_at": "2020-11-29T11:18:01.324Z",
  "updated_at": "2020-11-29T11:18:01.324Z",
  "created_by": "admin",
  "policy_triggers": {
    ...
  },
  "private_resource": false,
  "visibility": "tenant",
  "groups": {
    ...
  },
  "workflows": {
    ...
  },
  "id": "deployment_1",
  "outputs": {
    ...
  },
  "labels": [
    {
      "key": "key2",
      "value": "val2",
      "created_at": "2020-11-29T11:19:03.324Z",
      "creator_id": 0
    },
    {
      "key": "key1",
      "value": "val1",
      "created_at": "2020-11-29T11:19:03.324Z",
      "creator_id": 0
    }
  ]
}

PATCH "<manager-ip>/api/v3.1/deployments/{deployment-id}"

Update the deployment’s labels.

URI Parameters

deployment-id: The id of the deployment to update.

Request Body

Property	Type	Description
`labels`	list	A list of the new deployment’s labels (required).

Response

A Deployment resource.

Get all Deployments' Labels' Keys

Request Example

$ curl -X GET \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/labels/deployments"

# Python Client
client.deployments_labels.list_keys()

Response Example

{
  "metadata": {
    "pagination": {
      "total": 2,
      "size": 1000,
      "offset": 0
    }
  },
  "items": [
    "key1",
    "key2"
  ]
}

GET "<manager-ip>/api/v3.1/labels/deployments"

Get all deployments' labels' keys in the specified tenant.

Response

Field	Type	Description
`items`	list	A list of all deployments' labels' keys.

Get All Deployments' Labels' Values For a Specified Key

Request Example

$ curl -X GET \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/labels/deployments/<label-key>"

# Python Client
client.deployments_labels.list_key_values(label_key='<label-key>')

Response Example

{
  "metadata": {
    "pagination": {
      "total": 1,
      "size": 1000,
      "offset": 0
    }
  },
  "items": [
    "val1"
  ]
}

GET "<manager-ip>/api/v3.1/labels/deployments/<label-key>"

Get all deployments' labels' values for the specified key.

Response

Field	Type	Description
`items`	list	A list of all deployments' labels' values associated with the specified key.

Events

The Event Resource

Attributes:

Attribute	Type	Description
`blueprint_id`	string	Blueprint id
`deployment_id`	string	Deployment id
`error_causes`	[ErrorCause]	List of errors that happened while executing a given task (only for `cloudify_event` items)
`event_type`	string	Event type name (only for `cloudify_event` items)
`execution_id`	string	Execution id
`level`	string	Log level (only for `cloudify_log` items)
`logger`	string	Logger id (only for `cloudify_log` items)
`message`	string	Message text
`node_instance_id`	string	Node instance id
`node_name`	string	Node name
`operation`	string	Operation path (only available in operation events)
`reported_timestamp`	ISO 8601	The time at which the event occurred on the executing machine
`timestamp`	ISO 8601	The time at which the event was logged on the management machine
`type`	string	Indicates whether the resource is a `cloudify_event` or a `cloudify_log`
`workflow_id`	string	Workflow id
`manager_name`	string	The name of the manager that emitted this event
`agent_name`	string	The name of the agent that emitted this event

The ErrorCause object

Attribute	Type	Description
`message`	string	Error message
`traceback`	string	Stack trace at the point where the exception was raised
`type`	string	Exception type

List events

Lists all events

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u user:<manager-password> \
    "http://<manager_ip>/api/v3.1/events"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager-ip>',
    username='<manager-username>',
    password='<manager-password>',
    tenant='<manager-tenant>')
events = client.events.list(include_logs=True)
for event in events:
    print event

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager-ip>/api/v3.1/events'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(url, auth=HTTPBasicAuth('user', '<manager-password>'), headers=headers)
response.json()

Response Example

{
  "items": [
    {
      "node_instance_id": "vm_ke9e2d",
      "operation": "cloudify.interfaces.cloudify_agent.create",
      "blueprint_id": "linuxbp1",
      "timestamp": "2017-03-22T11:42:00.484Z",
      "message": "Successfully configured cfy-agent",
      "level": "info",
      "node_name": "vm",
      "workflow_id": "install",
      "reported_timestamp": "2017-03-22T11:41:59.169Z",
      "deployment_id": "linuxdp1",
      "type": "cloudify_log",
      "execution_id": "19ce78d6-babc-4a18-ba8e-74b853f2b387",
      "logger": "22e710c6-18b8-4e96-b8a3-2104b81c5bfc",
      "manager_name": "manager-1",
      "agent_name": null
    },
    {
      "node_instance_id": "vm_ke9e2d",
      "event_type": "task_succeeded",
      "operation": "cloudify.interfaces.cloudify_agent.create",
      "blueprint_id": "linuxbp1",
      "timestamp": "2017-03-22T11:42:00.788Z",
      "message": "Task succeeded 'cloudify_agent.installer.operations.create'",
      "node_name": "vm",
      "workflow_id": "install",
      "error_causes": null,
      "reported_timestamp": "2017-03-22T11:42:00.083Z",
      "deployment_id": "linuxdp1",
      "type": "cloudify_event",
      "execution_id": "19ce78d6-babc-4a18-ba8e-74b853f2b387",
      "manager_name": "manager-1",
      "agent_name": null
    },
    {
      "node_instance_id": "vm_ke9e2d",
      "event_type": "task_failed",
      "operation": "cloudify.interfaces.cloudify_agent.create",
      "blueprint_id": "linuxbp1",
      "timestamp": "2017-03-22T11:43:02.132Z",
      "message": "Task failed 'cloudify_agent.installer.operations.create' -> ERROR_MESSAGE",
      "node_name": "vm",
      "workflow_id": "install",
      "error_causes": [
        {
          "message": "ERROR_MESSAGE",
          "traceback": "Traceback (most recent call last):\n  File \"/opt/mgmtworker/env/lib/python2.7/site-packages/cloudify/dispatch.py\", line 624, in main\n
  File \"/opt/mgmtworker/env/lib/python2.7/site-packages/cloudify/dispatch.py\", line 389, in handle\n  File \"/opt/mgmtworker/env/lib/python2.7/site-packages/t
estmockoperations/tasks.py\", line 476, in execution_logging\n    raise NonRecoverableError('ERROR_MESSAGE', causes=causes)\nNonRecoverableError: ERROR_MESSAGE\n",
          "type": "NonRecoverableError"
        }
      ],
      "reported_timestamp": "2017-03-22T11:43:01.823Z",
      "deployment_id": "linuxdp1",
      "type": "cloudify_event",
      "execution_id": "19ce78d6-babc-4a18-ba8e-74b853f2b387",
      "manager_name": "manager-1",
      "agent_name": null
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 10000
    }
  }
}

GET "{manager-ip}/api/v3.1/events"

List events within a time range

GET "{manager-ip}/api/v3.1/events?_range=timestamp,[time_start],[time_end]"

Parameter	Type	Description
`time_start`	ISO 8601	optional value to begin range with.
`time_end`	ISO 8601	optional value to end range with.

all events within a time range:

GET "/api/v3.1/events?_range=timestamp,<time_start>,<time_end>"

all events since a given time:

GET "/api/v3.1/events?_range=timestamp,<time_start>,

all events until a given time:

GET "/api/v3.1/events?_range=timestamp,,<time_end>"

List events with filters

GET "{manager-ip}/api/v3.1/events?<filter>"

Allowed filters:

blueprint_id
deployment_id
execution_id
event_type (only returns cloudify-event items)
level (only returns cloudify-log items)
message(SQL’s LIKE style pattern expected)
include_logs(Include also logs in the response, defaults to False)

Multiple filters can be passed in the same request:

Filters of the same type will be combined using a logical OR operator
Filters of differnt type will be combined using a logical AND operator.

Response

Field	Type	Description
`items`	list	A list of `Event` resources.
`metadata`	object	Pagination metadata

Execution Groups

The Execution Group Resource

Attributes:

Attribute	Type	Description
`id`	string	A unique identifier for the group.
`created_at`	datetime	The time when the group was created.
`created_by`	string	Username of the creator of this group.
`tenant_name`	string	The name of the tenant that owns the group.
`visibility`	string	The visibility of the group.
`resource_availability`	string	The availability of the group.
`private_resource`	boolean	If set, the group will only be accessible by its creator (default: False).
`workflow_id`	string	The workflow that all executions in this group are running.
`concurrency`	integer	How many concurrent executions will this group run.
`deployment_group_id`	string	The ID of the deployment group that this execution group was started from.
`execution_ids`	list	IDs of all executions belonging to this group
`status`	string	Aggregate status of the executions in this group.

List Execution Groups

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/execution-groups

# Using CloudifyClient
groups = client.execution_groups.list()
groups_for_group = client.execution_groups.list(deployment_group_id='g1')

Response Example

{
  "items": [
    {
        "concurrency": 5,
        "created_at": "2021-04-27T10:29:10.350Z",
        "created_by": "admin",
        "deployment_group_id": "g1",
        "execution_ids": [
            "f89a7998-eb29-44fb-a5da-f565405ac6b2"
        ],
        "id": "9159be07-6741-482c-ab99-9ee6894122b9",
        "private_resource": false,
        "resource_availability": "tenant",
        "status": "terminated",
        "tenant_name": "default_tenant",
        "visibility": "tenant",
        "workflow_id": "create_deployment_environment"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 1000
    }
  }
}

GET "{manager-ip}/api/v3.1/execution-groups"

Lists all execution groups.

Query Parameters

deployment_group_id: Filter execution group by their creator deployment group ID

Response

Field	Type	Description
`items`	list	A list of `ExecutionGroup` resources.

Get Execution

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/execution-groups/<group-id>"

# Using CloudifyClient
client.execution_groups.get('<group-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/execution-groups/<execution_id>'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example

{
    "concurrency": 5,
    "created_at": "2021-04-27T10:29:10.350Z",
    "created_by": "admin",
    "deployment_group_id": "g1",
    "execution_ids": [
        "f89a7998-eb29-44fb-a5da-f565405ac6b2"
    ],
    "id": "9159be07-6741-482c-ab99-9ee6894122b9",
    "private_resource": false,
    "resource_availability": "tenant",
    "status": "terminated",
    "tenant_name": "default_tenant",
    "visibility": "tenant",
    "workflow_id": "create_deployment_environment"
}

GET "{manager-ip}/api/v3.1/executions/{execution-id}"

Gets an execution.

This is useful for polling execution group status, which works similarly to polling a single execution status. The execution group status is:

pending if all the executions are pending
started if some executions are started, even if there are already finished executions
terminated if all executions have ended and none have failed
failed if all executions have ended, and at least one have failed

Response

An ExecutionGroup resource.

Start multiple executions - start an Execution Group

Request Example

$ curl -X POST \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"deployment_group_id": "<group-id>", "workflow_id": "install"}' \
    "http://<manager_ip>/api/v3.1/execution-groups"

# Using CloudifyClient
client.execution_groups.start(
  deployment_id='<deployment-id>',
  workflow_id='install',
  default_parameters={'param1': 'value'},
  parameters={'deployment_id1': {'param1': 'override'}},
  concurrency=10,
)

POST -d '{"deployment_group_id": "<group-id>", "workflow_id": "<workflow-id>"}' "{manager-ip}/api/v3.1/execution-groups"

Starts an execution group. This starts an execution for every deployment in the target deployment group.

Request Body

Property	Type	Description
`workflow_id`	string	The workflow id/name to execute.
`deployment_group_id`	string	Start an execution for every deployment in this group.
`default_parameters`	object	Parameters for all executions in the group.
`parameters`	object	Parameter overrides keyed by deployment ID
`force`	boolean	Same meaning as for a single execution start
`concurrency`	integer	Run up to this many executions at a time

Specifying parameters

When deciding the parameters to use for each execution in the group, the default_parameters are merged with overrides from parameters. parameters is an object mapping deployment ID to an object containing parameter overrides. For each deployment in the deployment group, the overrides are merged with the default parameters.

Response

An ExecutionGroup resource.

Cancel/Resume an Execution Group

Request Example

curl -X POST \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"action": "cancel"}'
    "http://<manager-ip>/api/v3.1/execution-groups/<group-id>"

# Using CloudifyClient
client.execution_groups.cancel('<group-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/execution-groups/<group-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
payload ={'action': 'cancel'}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    json=payload,
)
response.json()

POST -d '{"action":"<action-method>"}' "{manager-ip}/api/v3.1/execution-groups/{group-id}"

Cancels or resumes an execution group.

This cancels or resumes all the executions belonging to this group.

When cancelling, executions that are still queued, will be put in the cancelled state immediately. When resuming, executions that never started to run, will have the resume flag set nonetheless.

Each action’s semantics are the same as in their single-execution case.

URI Parameters

group-id: The id of the execution group.

Request Body

Property	Type	Description
`action`	string	The method to perform: `cancel`, `force-cancel`, `kill`, `resume`, or `force-resume`.

Response

An ExecutionGroup resource.

Attach target success/failure groups

Request Example

curl -X PATCH \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"success_group_id": "g1"}'
    "http://<manager-ip>/api/v3.1/execution-groups/<group-id>"

# Using CloudifyClient
client.execution_groups.set_target_group(
    '<group-id>',
    success_group='g1',
    failed_group='g2'
)

PATCH -d '{"success_group_id":"<dep-group>"}' "{manager-ip}/api/v3.1/execution-groups/{group-id}"

Set target deployment groups, success and failure: deployments, for which the execution in this execution-group succeeds, will be added to the “success” target deployment group. Deployments, for which the execution in this execution-group fails, will be added to the “failure” target deployment group.

If an execution is cancelled, the deployment will be added to neither group.

The target group must already exist.

URI Parameters

group-id: The id of the execution group.

Request Body

Property	Type	Description
`success_group_id`	string	The “success” target deployment group ID
`failure_group_id`	string	The “failure” target deployment group ID

Response

An ExecutionGroup resource.

Change execution-group concurrency

Request Example

curl -X PATCH \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"concurrency": 15}'
    "http://<manager-ip>/api/v3.1/execution-groups/<group-id>"

# Using CloudifyClient
client.execution_groups.set_concurrency(
    '<group-id>',
    concurrency=15,
)

PATCH -d '{"concurrency":15}' "{manager-ip}/api/v3.1/execution-groups/{group-id}"

Set the concurrency parameter of the execution group. De-queueing executions will use the new setting. Note: setting concurrency to 0, effectively pauses the group.

URI Parameters

group-id: The id of the execution group.

Request Body

Property	Type	Description
`concurrency`	integer	The new concurrency setting, a nonnegative integer

Response

An ExecutionGroup resource.

Execution Schedules

The Execution Schedule Resource

Attributes:

Attribute	Type	Description
`id`	string	The name of the execution schedule.
`deployment_id`	string	The id of the deployment to which the scheduled execution is related.
`workflow_id`	string	The id of the workflow which the scheduled execution runs.
`parameters`	object	A dict of the workflow parameters passed when starting the scheduled execution.
`created_at`	datetime	The time the execution schedule was created at.
`next_occurrence`	datetime	The calculated next time in which the scheduled workflow should be executed at.
`since`	datetime	The earliest time the scheduled workflow should be executed at.
`until`	datetime	The latest time the scheduled workflow may be executed at (optional).
`stop_on_fail`	boolean	Whether the scheduler should stop attempting to run the execution once it failed (False by default).
`enabled`	boolean	Whether this schedule is currently enabled (True by default).

List Execution Schedules

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/execution-schedules?_include=id,deployment_id,workflow_id,next_occurrence"

# Using CloudifyClient
execution_schedules = client.execution_schedules.list(_include=['id', 'deployment_id', 'workflow_id', 'next_occurrence'])
for schedule in execution_schedules:
  print(schedule)

# Using requests
url = 'http://<manager-ip>/api/v3.1/execution-schedules'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id,deployment_id,workflow_id,next_occurrence'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)

Response Example

{
  "items": [
    {
      "id": "dep_a",
      "next_occurrence": "2021-03-08T18:47:00.000Z",
      "workflow_id": "install",
      "deployment_id": "dep"
    },
    {
      "id": "dep_b",
      "next_occurrence": "2021-03-09T18:47:00.000Z",
      "workflow_id": "uninstall",
      "deployment_id": "dep"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/execution-schedules"

Lists all execution schedules.

Get Execution Schedule

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/executions-schedules/<schedule-id>?
    deployment_id=<deployment-id>&
    _include=id,deployment_id,workflow_id,next_occurrence"

# Using CloudifyClient
client.execution_schedules.get(
    schedule_id='<schedule_id>',
    deployment_id='<deployment_id>',
    _include=['id', 'deployment_id', 'workflow_id', 'next_occurrence']
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/executions-schedules/<schedule_id>'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'deployment_id': '<deployment-id>',
    '_include': 'id,deployment_id,workflow_id,next_occurrence'
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "id": "dep_a",
  "next_occurrence": "2021-03-08T10:16:00.000Z",
  "workflow_id": "install",
  "deployment_id": "dep"
}

GET "{manager-ip}/api/v3.1/execution-schedules/{schedule-id}?deployment_id={deployment-id}"

Gets an execution schedule.

URI Parameters

schedule-id: The id of the execution schedule.
deployment-id: The id of the deployment to which the schedule belongs.

Response

An ExecutionSchedule resource.

Create Execution Schedule

Request Example

$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"workflow_id": "install", "since": "2021-1-1 12:00:00",
    "until": "2022-1-1 12:00:00", "recurrence": "1 day"}' \
    "http://<manager-ip>/api/v3.1/execution-schedules/<schedule-id>?
    deployment_id=<deployment-id>&_include=id"

# Using CloudifyClient
client.execution_schedules.create(
    schedule_id='<schedule-id>',
    deployment_id='<deployment-id>',
    workflow_id='install',
    since='2021-1-1 12:00:00',
    until='2022-1-1 12:00:00',
    recurrence='1 day',
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/execution-schedules/<schedule-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'deployment_id': '<deployment-id>', '_include': 'id'}
payload ={
    'workflow_id': 'install',
    'since': '2021-1-1 12:00:00',
    'until': '2022-1-1 12:00:00',
    'recurrence': '1 day',
}
response = requests.put(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Response Example

{
  "id": "custom-sched"
}

PUT -d '{"workflow_id": "install", ...}' "{manager-ip}/api/v3.1/execution-schedules/{schedule-id}?deployment_id={deployment-id}"

Creates a new execution schedule.

URI Parameters

schedule-id: The id of the new execution schedule.
deployment-id: The id of the deployment for which to schedule the workflow.

Request Body

Property	Type	Description
`workflow_id`	string	The workflow id/name that the schedule should execute.
`execution_arguments`	object	A dictionary of arguments passed directly to the workflow execution.
`parameters`	object	A dictionary containing parameters to be passed to the execution when starting it.
`since`	string	A string representing the earliest date and time this workflow should be executed at, of the format `%Y-%m-%d %H:%M:%S`. Must be provided if no `rrule` is given.
`until`	string	A string representing the latest date and time this workflow may be executed at, of the format `%Y-%m-%d %H:%M:%S` (optional).
`recurrence`	string	A string representing the frequency with which to run the execution, e.g. `2 weeks`. Must be provided if no `rrule` is given and `count` is other than 1.
`count`	integer	Maximum number of times to run the execution. If left empty, there’s no limit on repetition.
`weekdays`	string	A list of strings representing the weekdays on which to run the execution, e.g. `['su', 'mo', 'tu']`. If left empty, the execution will run on any weekday.
`rrule`	string	A string representing a scheduling rule in the iCalendar format, e.g. `RRULE:FREQ=DAILY;INTERVAL=3`, which means “run every 3 days”. Optional. Mutually exclusive with `recurrence`, `count` and `weekdays`.
`slip`	integer	Maximum time window after the target time has passed, in which the scheduled execution can run (in minutes). If not provided, defaults to 0.
`stop_on_fail`	boolean	If set to true, once the execution has failed, the scheduler won’t make further attempts to run it. If not provided, defaults to `false`.

Valid execution arguments are:

allow_custom_parameters (boolean): Specifies whether to allow custom parameters, which are not present in the parameters schema of the workflow.
force (boolean): Specifies whether to force the workflow execution in case there is already a running execution.
dry_run (boolean): If set to true, no actual actions will be performed.
wait_after_fail (integer): When a task fails, wait this many seconds for already-running tasks to return.
queue (boolean): Whether to queue the execution if it can’t run. Useless in schedules: all executions which cannot run will be queued. See Executions for more details on these.

Valid recurrence expressions are of the form <integer> minutes|hours|days|weeks|months|years. These can be also written without a space after the number, without the final s, or using the short forms min|h|d|w|mo|y.

Valid weekdays expressions are a list containing any of su|mo|tu|we|th|fr|sa. These may be optionally prefixed by 1 to 4 or l- (for “last”) signifying a “complex weekday”, e.g. 2mo for “the 2nd Monday of a month” or l-fr for “the last Friday of a month”. Complex weekdays can only be used in tandem with a months or years recurrence.

Response

An ExecutionSchedule resource.

Update Execution Schedule

Request Example

$ curl -X PATCH \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"since": "2021-1-1 12:00:00", "until": "2022-1-1 12:00:00", "recurrence": "1 day", "enabled": True}' \
    "http://<manager-ip>/api/v3.1/execution-schedules/<schedule-id>?
    deployment_id=<deployment-id>&_include=id"

# Using CloudifyClient
client.execution_schedules.update(
    schedule_id='<schedule-id>',
    deployment_id='<deployment-id>',
    since='2021-1-1 12:00:00',
    until='2022-1-1 12:00:00',
    recurrence='1 day',
    enabled=True,
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/execution-schedules/<schedule-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'deployment_id': '<deployment-id>', '_include': 'id'}
payload ={
    'since': '2021-1-1 12:00:00',
    'until': '2022-1-1 12:00:00',
    'recurrence': '1 day',
    'enabled': True,
}
response = requests.patch(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Response Example

{
  "id": "custom-sched"
}

PATCH -d '{"since": "2021-1-1 12:00:00", "until": "2022-1-1 12:00:00", ...}' "{manager-ip}/api/v3.1/execution-schedules/{schedule-id}?deployment_id={deployment-id}"

Updates an existing execution schedule.

URI Parameters

schedule-id: The id of the execution schedule to update.
deployment-id: The id of the deployment to which the schedule belongs.

Request Body

All fields below are optional.

Property	Type	Description
`since`	string	A string representing the earliest date and time this workflow should be executed at, of the format `%Y-%m-%d %H:%M:%S`.
`until`	string	A string representing the latest date and time this workflow may be executed at, of the format `%Y-%m-%d %H:%M:%S`.
`recurrence`	string	A string representing the frequency with which to run the execution, e.g. `2 weeks`.
`count`	integer	Maximum number of times to run the execution.
`weekdays`	string	A list of strings representing the weekdays on which to run the execution, e.g. `['su', 'mo', 'tu']`.
`rrule`	string	A string representing a scheduling rule in the iCalendar format, e.g. `RRULE:FREQ=DAILY;INTERVAL=3`, which means “run every 3 days”. Mutually exclusive with `recurrence`, `count` and `weekdays`.
`slip`	integer	Maximum time window after the target time has passed, in which the scheduled execution can run (in minutes).
`stop_on_fail`	boolean	If set to true, once the execution has failed, the scheduler won’t make further attempts to run it.
`enabled`	boolean	Set to false to make the scheduler ignore this schedule, until set to true again.

Response

An ExecutionSchedule resource.

Delete Execution Schedule

Request Example

$ curl -X DELETE \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/executions-schedules/<schedule-id>?deployment_id=<deployment-id>"

# Using CloudifyClient
client.execution_schedules.delete(
    schedule_id='<schedule-id>',
    deployment_id='<deployment-id>'
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/executions-schedules/<schedule-id>'
headers = {'content-type': 'application/json'}
querystring = {'deployment_id': '<deployment-id>'}
requests.delete(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)

DELETE "{manager-ip}/api/v3.1/executions-schedules/{schedule-id}?deployment_id={deployment-id}"

Deletes an execution schedule.

URI Parameters

schedule-id: The id of the execution schedule.
deployment-id: The id of the deployment to which the schedule belongs.

Response

No content - HTTP code 204.

Executions

The Execution Resource

Attributes:

Attribute	Type	Description
`blueprint_id`	string	The id of the blueprint the execution is in the context of.
`created_at`	datetime	The time the execution was queued at.
`ended_at`	datetime	The time the execution ended in successful, failed or cancelled state.
`created_by`	string	The name of the user that created the execution.
`deployment_id`	string	The id of the deployment the execution is in the context of.
`error`	string	The execution’s error message on execution failure.
`id`	string	A unique identifier for the execution.
`is_system_workflow`	boolean	true if the execution is of a system workflow.
`parameters`	object	A dict of the workflow parameters passed when starting the execution.
`status`	string	The executions status.
`tenant_name`	string	The name of the tenant that owns the execution.
`workflow_id`	string	The id/name of the workflow the execution is of.
`started_at`	datetime	The time the execution was started at.
`scheduled_for`	datetime	The time this execution is scheduled to start at.

List Executions

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/executions?_include=id

# Using CloudifyClient
executions = client.executions.list(_include=['id'])
for execution in executions:
  print execution

# Using requests
url = 'http://<manager-ip>/api/v3.1/executions'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)

Response Example

{
  "items": [
    {
      "id": "dab3d7ac-fef0-4b8b-912f-5611cc8f20b5"
    },
    {
      "id": "ca3d7413-c8af-41a3-b864-571cef25899b"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/executions"

Lists all executions.

Response

Field	Type	Description
`items`	list	A list of `Execution` resources.

Get Execution

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/executions/<execution-id>?_include=id"

# Using CloudifyClient
client.executions.get(execution_id='<execution_id>', _include=['id'])

# Using requests
url = 'http://<manager-ip>/api/v3.1/executions/<execution_id>'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "id": "ca3d7413-c8af-41a3-b864-571cef25899b"
}

GET "{manager-ip}/api/v3.1/executions/{execution-id}"

Gets an execution.

URI Parameters

execution-id: The id of the execution.

Response

An Execution resource.

Start Execution

Request Example

$ curl -X POST \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"deployment_id": "<deployment-id>", "workflow_id": "install"}' \
    "http://<manager_ip>/api/v3.1/executions?_include=id"

# Using CloudifyClient
client.executions.start(deployment_id='<deployment-id>', workflow_id='install')

# Using requests
url = 'http://<manager-ip>/api/v3.1/executions'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'_include': 'id'}
payload ={
    'deployment_id': '<deployment-id>',
    'workflow_id': 'install',
}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Response example

{
  "id": "33dd51d4-5e24-4034-8ed6-2150cdbd98f7"
}

POST -d '{"deployment_id":{deployment-id}, "workflow_id":"<workflow-id>"}' "{manager-ip}/api/v3.1/executions"

Starts an execution.

Request Body

Property	Type	Description
`workflow_id`	string	The workflow id/name to execute.
`deployment_id`	string	The id of the deployment the workflow should be executed on.
`allow_custom_parameters`	boolean	Specifies whether to allow custom parameters, which are not present in the parameters schema of the workflow, to be passed when starting the execution (default=false).
`parameters`	object	A dictionary containing parameters to be passed to the execution when starting it.
`force`	boolean	Specifies whether to force the workflow execution in a case where there is already a running execution in the context of the same deployment or system wide workflow (default=false).
`queue`	boolean	If set, executions that can’t currently run will be queued and run automatically when possible.
`schedule`	string	The time (including timezone) this workflow will be executed at; expected format: YYYYMMDDHHMM+HHMM or YYYYMMDDHHMM-HHMM. i.e: 201801032230-0500 (Jan-03-18 10:30pm EST).

Response

An Execution resource.

Cancel Execution

Request Example

curl -X POST \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"deployment_id": "dep", "action": "cancel"}'
    "http://<manager-ip>/api/v3.1/executions/<execution-id>?_include=id"

# Using CloudifyClient
client.executions.cancel(execution_id='<execution-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/executions/<execution-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'_include': 'id'}
payload ={'deployment_id': 'dep', 'action': 'cancel'}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Example Response

{
  "id": "e7821510-c536-47f3-8fe7-691a91dc91ff"
}

POST -d '{"deployment_id":{deployment-id}, "action":"<action-method>"}' "{manager-ip}/api/v3.1/executions/{execution-id}"

Cancels an execution.

If passing cancel as the action fails to cancel the execution, force-cancel can be passed which will then kill the process running the execution.

URI Parameters

execution-id: The id of the execution.

Request Body

Property	Type	Description
`action`	string	The cancellation method to perform: `cancel` or `force-cancel`

Response

An Execution resource.

Update Execution

Request Example

curl -X PATCH \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"status": "cancelled"}' \
    "http://<manager-ip>/api/v3.1/executions/<execution-id>?_include=id"

# Using CloudifyClient
client.executions.update(execution_id='<execution_id>', status='cancelled')

# Using requests
url = 'http://<manager-ip>/api/v3.1/executions/<execution-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'_include': 'id'}
payload ={'status': 'cancelled'}
response = requests.patch(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Example Response

{
  "id": "21236984-9d1f-445e-8bca-f923175441f1"
}

PATCH "{manager-ip}/api/v3.1/executions/{execution-id}"

Updates an execution.

URI Parameters

execution-id: The id of the execution.

Request Body

Property	Type	Description
`status`	string	The new status of the execution.

Response

An Execution resource.

Delete Executions

Request Example

curl -X DELETE \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"keep_last": <num_executions>}' \
    "http://<manager-ip>/api/v3.1/executions"

# Using CloudifyClient
client.executions.delete(keep_days=<num_days>, all_tenants=True)

# Using requests
url = 'http://<manager-ip>/api/v3.1/executions'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'deployment_id': 'id'}
payload = {'to_datetime': <date>}
response = requests.delete(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring, 
    json=payload,   
)
response.json()

Example Response

{
  "items": [
    {
      "id": "dab3d7ac-fef0-4b8b-912f-5611cc8f20b5"
    },
    {
      "id": "ca3d7413-c8af-41a3-b864-571cef25899b"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 0
    }
  }
}

DELETE "{manager-ip}/api/v3.1/executions"

Deletes finished executions.

Request Body

Property	Type	Description
`to_datetime`	datetime	Until which date (timestamp) to delete executions.
`keep_last`	integer	How many most recent executions to keep from deletion.

these fields are mutually exclusive

Response

Field	Type	Description
`items`	list	A count of `Execution` resources deleted by the command.

Filters

The Filter Resource

A Filter resource is a set of filter-rules that can be used to filter a list of resources, based on their labels and attributes. A filter rule is a dictionary of the following form:

{
 "key": "<key>",
 "values": [<list of values>],
 "operator": "<LabelsOperator>" or "<AttrsOperator>",
 "type": "<FilterRuleType>"
}

<LabelsOperator> can be one of: “any_of”, “not_any_of”, “is_null”, “is_not_null”, or “is_not”.

<AttrsOperator> can be one of: “any_of”, “not_any_of”, “contains”, “not_contains”, “starts_with”, “ends_with”, “is_not_empty”.

<FilterRuleType> can be either “label” or “attribute”. If “label” is provided, then the operator must be a <LabelsOperator>, and if “attribute” is provided, then the operator must be an <AttrsOperator>.

E.g. filtering by the following filter rules, will return all deployments whose creator name starts with “alice” or “bob”, and have the label environment:aws assigned to them.

[
 {
  "key": "created_by",
  "values": ["alice", "bob"],
  "operator": "starts-with",
  "type": "attribute"
 },
 {
  "key": "environment",
  "values": ["aws"],
  "operator": "any_of",
  "type": "label"
 }
]

Filters can be used currently for deployments and blueprints.

Attributes:

Attribute	Type	Description
`id`	string	The filter’s ID, unique per tenant.
`value`	list	A list of the filter’s filter-rules.
`labels_filter_rules`	list	A list of the filter’s filter-rules of type `label`.
`attrs_filter_rules`	list	A list of the filter’s filter-rules of type `attribute`.
`visibility`	string	Defines who can see the filter. Can be private, tenant or global.
`created_at`	datetime	The time when the filter was created.
`updated_at`	datetime	The time the filter was last updated at.
`tenant_name`	string	The name of the tenant that owns the filter.

List Filters

Request Example

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/filters/<resource>"

<resource> can be either deployments or blueprints.

# Using Cloudify client
client.deployments_filters.list()
# Or
client.blueprints_filters.list()

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/filters/<resource>' # `<resource>` can be either `deployments` or `blueprints`
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example

{
  "metadata": {
    "pagination": {
      "total": 1,
      "size": 1000,
      "offset": 0
    },
    "filtered": null
  },
  "items": [
    {
      "id": "new_filter",
      "visibility": "tenant",
      "created_at": "2021-03-25T11:48:56.525Z",
      "value": [
        {
          "key": "os",
          "values": [
            "windows"
          ],
          "operator": "any_of",
          "type": "label"
        },
        {
          "key": "created_by",
          "values": [
            "bob"
          ],
          "operator": "starts_with",
          "type": "attribute"
        }
      ],
      "updated_at": "2021-03-25T11:48:56.525Z",
      "tenant_name": "default_tenant",
      "created_by": "admin",
      "resource_availability": "tenant",
      "private_resource": false,
      "labels_filter_rules": [
        {
          "key": "os",
          "values": [
            "windows"
          ],
          "operator": "any_of",
          "type": "label"
        }
      ],
      "attrs_filter_rules": [
        {
          "key": "created_by",
          "values": [
            "bob"
          ],
          "operator": "starts_with",
          "type": "attribute"
        }
      ]
    }
  ]
}

GET "{manager_ip}/api/v3.1/filters/<resource>"

List all filters of a resource. Resource can be either deployments of blueprints.

Response

Field	Type	Description
`items`	list	A list of `Filter` resources.

Get Filter

Request Example

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/filters/<resource>/<filter_id>"

<resource> can be either deployments or blueprints.

# Using Cloudify client
client.deployments_filters.get('<filter_id>')
# Or
client.blueprints_filters.get('<filter_id>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/filters/<resource>/<filter_id>' # `<resource>` can be either `deployments` or `blueprints`
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example

{
  "id": "new_filter",
  "visibility": "tenant",
  "created_at": "2021-03-25T11:48:56.525Z",
  "value": [
    {
      "key": "os",
      "values": [
        "windows"
      ],
      "operator": "any_of",
      "type": "label"
    },
    {
      "key": "created_by",
      "values": [
        "bob"
      ],
      "operator": "starts_with",
      "type": "attribute"
    }
  ],
  "updated_at": "2021-03-25T11:48:56.525Z",
  "tenant_name": "default_tenant",
  "created_by": "admin",
  "resource_availability": "tenant",
  "private_resource": false,
  "labels_filter_rules": [
    {
      "key": "os",
      "values": [
        "windows"
      ],
      "operator": "any_of",
      "type": "label"
    }
  ],
  "attrs_filter_rules": [
    {
      "key": "created_by",
      "values": [
        "bob"
      ],
      "operator": "starts_with",
      "type": "attribute"
    }
  ]
}

GET "{manager_ip}/api/v3.1/filters/<resource>/{filter_id}"

Retrieves a specific resource’s filter. Resource can be either deployments of blueprints.

URI Parameters

filter_id: The ID of the filter to retrieve.

Response

A Filter resource.

Create Filter

Request Example

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"filter_rules": <filter_rules_list>, "visibility": "<visibility>"}' \
    "http://<manager_ip>/api/v3.1/filters/<resource>/<filter_id>"

<resource> can be either deployments or blueprints.

# Using Cloudify client
client.deployments_filters.create(filter_id="<the new filter's id>", 
                                  filter_rules=[...], 
                                  visibility="<the filter's visibility>")
# Or
client.blueprints_filters.create(filter_id="<the new filter's id>", 
                                 filter_rules=[...], 
                                 visibility="<the filter's visibility>")

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/filters/<resource>/<filter_id>' # `<resource>` can be either `deployments` or `blueprints`
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
payload = {
    'filter_rules': [...],
    'visibility': "<the filter's visibility>"
}
response = requests.put(
    url,
    auth=auth,
    headers=headers,
    json=payload
)
response.json()

Response Example

{
  "id": "new_filter",
  "visibility": "tenant",
  "created_at": "2021-03-25T12:10:24.607Z",
  "value": [
    {
      "key": "created_by",
      "values": [
        "admin"
      ],
      "operator": "any_of",
      "type": "attribute"
    }
  ],
  "updated_at": "2021-03-25T12:10:24.607Z",
  "tenant_name": "default_tenant",
  "created_by": "admin",
  "resource_availability": "tenant",
  "private_resource": false,
  "labels_filter_rules": [
    
  ],
  "attrs_filter_rules": [
    {
      "key": "created_by",
      "values": [
        "admin"
      ],
      "operator": "any_of",
      "type": "attribute"
    }
  ]
}

PUT -d '{"filter_rules": <filter_rules_list>, "visibility": <visibility>}' "{manager_ip}/api/v3.1/filters/<resource>/{filter_id}"

Creates a resource’s filter. Resource can be either deployments of blueprints.

URI Parameters

filter_id: The ID of the filter to create.

Request Body

Property	Type	Description
`filter_rules`	list	The filter’s rules list as described above.
`visibility`	string	Optional parameter, defines who can see the filter (default: tenant).

Valid visibility values are:

private: The filter is visible to the user that created the filter, the tenant’s managers and the system’s admins.
tenant: The filter is visible to all users in the current tenant. (Default value)
global: The filter is visible to all users in all tenants across the manager.

Response

A Filter resource.

Update Filter

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"filter_rules": <new_filter_rules_list>, "visibility": "<new_visibility>"}' \
    "http://<manager_ip>/api/v3.1/filters/<resource>/<filter_id>"

<resource> can be either deployments or blueprints.

# Using Cloudify client
client.deployments_filters.update(filter_id="<the updated filer's ID>", 
                                  new_filter_rules=[...], 
                                  new_visibility="<the new filter's visibility>")
# Or
client.blueprints_filters.update(filter_id="<the updated filer's ID>", 
                                 new_filter_rules=[...], 
                                 new_visibility="<the new filter's visibility>")

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/filters/<resource>/<filter_id>' # `<resource>` can be either `deployments` or `blueprints`
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager_tenant>',
}
payload = {
    'filter_rules': [...],
    'visibility': "<the new filter's visibility>"
}
response = requests.patch(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example

{
  "id": "filter1",
  "visibility": "tenant",
  "created_at": "2021-03-25T12:10:24.607Z",
  "value": [
    {
      "key": "created_by",
      "values": [
        "bob"
      ],
      "operator": "any_of",
      "type": "attribute"
    }
  ],
  "updated_at": "2021-03-25T12:41:03.350Z",
  "tenant_name": "default_tenant",
  "created_by": "admin",
  "resource_availability": "tenant",
  "private_resource": false,
  "labels_filter_rules": [
    
  ],
  "attrs_filter_rules": [
    {
      "key": "created_by",
      "values": [
        "bob"
      ],
      "operator": "any_of",
      "type": "attribute"
    }
  ]
}

PATCH -d '{"filter_rules": <new_filter_rules_list>, "visibility": <new_visibility>}' "{manager_ip}/api/v3.1/filters/<resource>/{filter_id}"

Updates a resource’s filter. Resource can be either deployments of blueprints.

URI Parameters

filter_id: The ID of the filter to update.

Request Body

Property	Type	Description
`filter_rules`	list	The new filter’s rules list as described above.
`visibility`	string	Optional parameter, defines who can see the filter (default: tenant).

Response

A Filter resource.

Delete Filter

Request Example

$ curl -X DELETE \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/filters/<resource>/<filter_id>"

<resource> can be either deployments or blueprints.

# Using Cloudify client
client.deployments_filters.delete('<filter_id>')
# Or
client.blueprints_filters.delete('<filter_id>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/filters/<resource>/<filter_id>' # `<resource>` can be either `deployments` or `blueprints`
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
requests.delete(
    url,
    auth=auth,
    headers=headers,
)

DELETE "{manager_ip}/api/v3.1/filters/<resource>/{filter_id}"

Deletes a resource’s filter. Resource can be either deployments of blueprints

URI Parameters

filter_id: The ID of the filter to delete.

Response

No content - HTTP code 204.

License

The License Resource

Attributes:

Attribute	Type	Description
`id`	string	A unique identifier for the license.
`customer_id`	string	The id of the customer the license was issued for.
`expiration_date`	datetime	The expiration date of the license.
`license_edition`	string	The edition of the license (Spire/ Premium)
`trial`	boolean	true if the license is a trial license.
`cloudify_version`	string	The maximal Conductor version the license is valid for
`capabilities`	object	A list of capabilities the license supports.
`expired`	boolean	true if the license has expired.

Upload License

Request Example

$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    --data-binary @/<license_path>
    "<manager-ip>/api/v3.1/license"

# Using CloudifyClient
license = client.license.upload(license_path)

# Using requests
url = 'http://<manager-ip>/api/v3.1/license'
headers = {'Tenant': '<manager-tenant>',
           'Content-Type': 'application/json'}
response = requests.put(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers
)

Response Example

{
"expiration_date": "2018-11-24T00:00:00.000Z",
"cloudify_version": "4.6",
"license_edition": "Spire",
"capabilities": [
    "Mock1",
     "Mock2"
     ],
"trial": false,
"customer_id": "CloudifyMock",
"expired": true
}

PUT "{manager-ip}/api/v3.1/license"

Upload a license.

Response

A License resource.

List License

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/license"

# Using CloudifyClient
license = client.license.list()

# Using requests
url = 'http://<manager-ip>/api/v3.1/license'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers
)

Response Example

{
   "items":[
      {
         "expiration_date":"2018-11-24T00:00:00.000Z",
         "cloudify_version":"4.6",
         "license_edition":"Spire",
         "capabilities":[
            "Mock1",
            "Mock2"
         ],
         "trial":false,
         "customer_id":"CloudifyMock",
         "expired":true
      }
   ],
   "metadata":{
      "pagination":{
         "total":1,
         "offset":0,
         "size":1000
      }
   }
}

GET "{manager-ip}/api/v3.1/license"

List license.

Response

Field	Type	Description
`items`	list	A `License` resource.

Delete License

Request Example

$ curl -X DELETE \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/license"

# Using CloudifyClient
import requests

license = client.license.delete()

# Using requests
url = 'http://<manager-ip>/api/v3.1/license'
headers = {'Tenant': '<manager-tenant>'}
requests.delete(
   url,
   auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
   headers=headers
)

Manager

The following REST API calls provide information about Conductor’s manager.

Status

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/status"

# Using ClodifyManager
client.manager.get_status()

# Using requests
url = 'http://<manager-ip>/api/v3.1/status'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers
)
response.json()

Response Example

{
  "status": "OK",
  "services": {
    "PostgreSQL": {
      "status": "Active",
      "is_remote": false,
      "extra_info": {
        "systemd": {
          "instances": [
            {
              "LoadState": "loaded",
              "Description": "PostgreSQL 9.5 database server",
              "state": "running",
              "MainPID": 39,
              "Id": "postgresql-9.5.service",
              "ActiveState": "active",
              "SubState": "running"
            }
          ],
          "display_name": "PostgreSQL",
          "unit_id": "postgresql-9.5.service"
        }
      }
    },
    "RabbitMQ": {
      "status": "Active",
      "is_remote": false,
      "extra_info": {
        "systemd": {
          "instances": [
            {
              "LoadState": "loaded",
              "Description": "RabbitMQ Service",
              "state": "running",
              "MainPID": 351,
              "Id": "cloudify-rabbitmq.service",
              "ActiveState": "active",
              "SubState": "running"
            }
          ],
          "display_name": "RabbitMQ",
          "unit_id": "cloudify-rabbitmq.service"
        },
        "connection_check": "OK"
      }
    },
    "Cloudify Console": {
      "status": "Active",
      "is_remote": false,
      "extra_info": {
        <Console's status data>
      }
    },
    "Manager Rest-Service": {
      "status": "Active",
      "is_remote": false,
      "extra_info": {
        <Rest-Service's status data>
      }
    },
    "AMQP-Postgres": {
      "status": "Active",
      "is_remote": false,
      "extra_info": {
        <AMQP-Postgres's status data>
      }
    },
    "Webserver": {
      "status": "Active",
      "is_remote": false,
      "extra_info": {
        <Webserver's status data>
      }
    },
    "Cloudify Composer": {
      "status": "Active",
      "is_remote": false,
      "extra_info": {
        <Composer's status data>
      }
    },
    "Management Worker": {
      "status": "Active",
      "is_remote": false,
      "extra_info": {
        <Management worker's status data>
      }
    }
  }
}

GET "{manager-ip}/api/v3.1/status"

Gets Conductor manager status.

Getting summarised manager status

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/status?summary=true"

# Using ClodifyManager
client.manager.get_status()

# Using requests
url = 'http://<manager-ip>/api/v3.1/status'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'summary': 'true'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring
)
response.json()

Response Example

{
  "status": "OK",
  "services": {}
}

GET "{manager-ip}/api/v3.1/status?summary=true"

Gets summary of Conductor manager status.

Attributes:

Attribute	Type	Description
`status`	string	The status of the manager, can be `OK` or `Fail`.
`services`	object	A dictionary containing Service resources, representing a service running in the manager.

The Service Object:

Attribute	Type	Description
`instances`	list	List of Instance resources representing the instances of a service running in a manager in a DBus structure.
`display_name`	string	The service name.

The Instance Object:

Attribute	Type	Description
`LoadState`	string	Contains a state value that reflects whether the configuration file of this unit has been loaded.
`Description`	string	The description of the service instance.
`state`	string	The state of the service instance (unknown, down, up, finish).
`MainPID`	integer	The process id of the main service instance process.
`Id`	string	The id of the service instance.
`ActiveState`	string	Contains a state value that reflects whether the unit is currently active or not. The following states are currently defined: active, reloading, inactive, failed, activating, deactivating.
`SubState`	string	Encodes states of the same state machine that `ActiveState` covers, but knows more fine-grained states that are unit-type-specific.

Information about the instance fields can be found in the DBus reference.

Version

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/version?_include=version"

# Using CloudifyClient
client.manager.get_version()

# Using requests
url = 'http://<manager-ip>/api/v3.1/version'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'version'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "version": "4.0.1"
}

GET "{manager-ip}/api/v3.1/version"

Gets Conductor manager version information.

Attributes:

Attribute	Type	Description
`date`	ISO 8601	The date and time of the build the manager was built of.
`commit`	string	Git commit hash of the REST service code base used by the manager.
`version`	string	The version of Conductor manager.
`build`	string	Build number.
`edition`	string	Software edition (either `community` or `premium`)

Node Instances

The NodeInstance Resource

Attributes:

Attribute	Type	Description
`created_by`	string	The name of the user that created the node instance.
`deployment_id`	string	The id of the deployment the node instance belongs to.
`node_id`	string	The id of the node of which this is an instance.
`host_id`	string	The Compute node instance id the node is contained within.
`id`	string	The id of the node instance.
`relationships`	list	The relationships the node has with other nodes.
`runtime_properties`	object	The runtime properties of the node instance.
`state`	string	The node instance state.
`tenant_name`	string	The name of the tenant that owns the node instance.
`version`	integer	A version attribute used for optimistic locking when updating the node instance.

List Node Instances

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/node-instances&_include=id"

# Using CloudifyClient
instances = client.node_instances.list(_include=['id'])
for instance in instances:
    print instance

# Using requests
url = 'http://<manager-ip>/api/v3.1/node-instances'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "http_web_server_tfq3nt"
    },
    {
      "id": "vm_m7nmd7"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/node-instances"

Lists all node instances.

Response

Field	Type	Description
`items`	list	A list of `NodeInstance` resources.

Get Node Instance

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/node-instances/<node-instance-id>&_include=id"

# Using CloudifyClient
client.node_instances.get('http_web_server_tfq3nt', _include=['id'])

# Using requests
url = 'http://<manager-ip>/api/v3.1/node-instances/<node-instance-id>'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "id": "http_web_server_tfq3nt"
}

GET "{manager-ip}/api/v3.1/node-instances/{node-instance-id}"

Gets a node instance.

URI Parameters

node-instance-id: The id of the node instance.

Response

A NodeInstance resource.

Update Node Instance

Requests Example

$ curl -X PATCH \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"version": 0, "runtime_properties": {"key": "value"}}' \
    "http://<manager-ip>/api/v3.1/node-instances/<node-instance-id>?_include=id,runtime_properties"

# Using CloudifyClient
client.node_instances.update(
    node_instance_id='<node-instance-id>',
    version=0,
    runtime_properties={'key': 'value'},
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/node-instances/<node-instance-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager_tenant>',
}
querystring = {'_include': 'id,runtime_properties'}
payload = {'version': 0, 'runtime_properties': {'key': 'value'}}
response = requests.patch(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Response Example

{
  "runtime_properties": {
    "key": "value"
  },
  "id": "http_web_server_tfq3nt"
}

PATCH "{manager-ip}/api/v3.1/node-instances/{node-instance-id}"

Updates a node instance.

URI Parameters

node-instance-id: The id of the node instance.

Request Body

Property	Type	Description
`runtime_properties`	object	A dictionary containing the updated runtime properties of the node instance.
`state`	string	The new state of the node instance.
`version`	integer	The node instance current version (used for optimistic locking).

The version property should be set to the current value of the node instance. The version is auto incremented by Conductor on every update.

Response

A NodeInstance resource.

Nodes

The Node Resource

Attributes:

Attribute	Type	Description
`actual_number_of_instances`	integer	The number of deployed node instances the node has. This number accounts for scaled groups.Note: this attribute appears in the CLI table as `number_of_instances`.
`actual_planned_number_of_instances`	integer	The number of node instances specified for this node in the deployment.This number accounts for scaled groups.Note: this attribute appears in the CLI table as `planned_number_of_instances`.
`blueprint_id`	string	The id of the blueprint the node belongs to.
`deploy_number_of_instances`	integer	Default number of instances on deploy.
`deployment_id`	string	The id of the deployment the node belongs to.
`host_id`	string	The Compute node name the node is contained within.
`id`	string	The name of the node.
`max_number_of_instances`	integer	Maximum number of instances.
`min_number_of_instances`	integer	Minimum number of instances.
`number_of_instances`	integer	The number of deployed node instances the node has. This number does not account for scaled groups.
`operations`	object	The operations the node exposes.
`planned_number_of_instances`	integer	The number of node instances specified for this node in the deployment.This number does not account for scaled groups.
`plugins_to_install`	list	A list of required plugins to install in order to execute the node’s operations.
`plugins`	list	A list of plugins the node is using for executing its operations.
`properties`	object	The properties of the node.
`relationships`	list	The relationships the node has with other nodes.
`tenant_name`	string	The name of the tenant that owns the node.
`type_hierarchy`	list	The type hierarchy of the node (ancestors).
`type`	string	The type of the node.
`unavailable_instances`	integer	Amount of instances that failed their status check.
`drifted_instances`	integer	Amount of instances that have configuration drift.

id and deployment_id are combined together for uniquely identifying a node.

List Nodes

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/nodes?_include=id"

# Using CloudifyClient
nodes = client.nodes.list(_include=['id'])
for node in nodes:
    print node

# Using request
url = 'http://<manager-ip>/api/v3.1/nodes'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "http_web_server"
    },
    {
      "id": "vm"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/nodes"

Lists all nodes.

URI Parameters

For filtering, or returning additional data, the following parameters can be provided in the querystring:

deployment_id - return nodes of this deployment
id - return only the node matching this id
evaluate_functions - evaluate intrinsic functions
_instance_counts - count unavailable and drifted instances. This is only available when used together with deployment_id. When this is set, the unavailable_instances and drifted_instances fields are populated.

Response

Field	Type	Description
`items`	list	A list of `Node` resources.

Operations

The Operation Resource

# Include this code when using the Cloudify Python client-
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager-ip>',
        username='<manager-username>',
        password='<manager-password>')

Represents a stored operation, as part of a tasks graph

Attributes:

Attribute	Type	Description
`id`	string	Unique identifier of this operation
`name`	string	Name of this operation
`state`	string	The state of this operation, eg. PENDING, SENT or SUCCEEDED
`dependencies`	list	IDs of the operations that this operation depends on
`type`	string	Type of this operation, eg. RemoteWorkflowTask, LocalWorkflowTask or SubgraphTask
`parameters`	dict	Parameters as serialized by the operation class, to be used when reconstructing the operation
`tasks_graph`	string	ID of the tasks graph this operation belongs to
`manager_name`	string	The name of the manager that executed this operation
`agent_name`	string	The name of the agent that executed this operation

List operations

Request Example

$ curl -u user:password "http://<manager-ip>/api/v3.1/operations?graph_id=123"

client.operations.list(graph_id)

Response Example

[
    {
        "id": "operation-id",
        "state": "PENDING",
        "dependencies": [],
        "type": "SubgraphTask",
        "name": "my-subgraph",
        "parameters": {},
        "manager_name": "manager-1",
        "agent_name": null
    }
]

GET "{manager-ip}/api/v3.1/operations"

Lists operations. To be used when filtering by a tasks graph id. This is the primary method of bulk-requesting operations when resuming a workflow.

Query Parameters

Property	Type	Description
`graph_id`	string	Filter operations by this tasks graph

Create operation

Request Example

$ curl -u user:password -X PUT \
    -d '{"name": "abc", "graph_id": "123", "dependencies": [], "type": "RemoteWorkflowTask"}' \
    "http://<manager-ip>/api/v3.1/operations/<operation_id>"

client.operations.create(operation_id, graph_id, name, type, parameters, dependencies)

Response Example

{
    "id": "operation-id",
    "state": "PENDING",
    "dependencies": [],
    "type": "SubgraphTask",
    "name": "my-subgraph",
    "parameters": {}
}

PUT "{manager-ip}/api/v3.1/operations/{operation-id}" Creates a single operation. State defaults to PENDING. Note that instead of using this method, it is faster to create many operations in bulk while creating the tasks graph.

Request Body

Property	Type	Description
`name`	string	Name of the operation
`graph_id`	string	ID of the tasks graph this operation belongs to
`state`	string	The state of this operation, eg. PENDING, SENT or SUCCEEDED
`dependencies`	list	IDs of the operations that this operation depends on
`type`	string	Type of this operation, eg. RemoteWorkflowTask, LocalWorkflowTask or SubgraphTask
`parameters`	dict	Parameters as serialized by the operation class, to be used when reconstructing the operation

Update operation

Request Example

$ curl -u user:password -X PATCH \
    -d '{"state": "FAILED"}' \
    "http://<manager-ip>/api/v3.1/operations/<operation_id>"

client.operations.update(operation_id, state)

Response Example

{
    "id": "operation-id",
    "state": "FAILED",
    "dependencies": [],
    "type": "SubgraphTask",
    "name": "my-subgraph",
    "parameters": {}
}

PATCH "{manager-ip}/api/v3.1/operations/{operation-id}" Updates the state of an operation. Other attributes are immutable.

Request Body

Property	Type	Description
`state`	string	The state of this operation, eg. PENDING, SENT or SUCCEEDED

Delete operation

Request Example

$ curl -u user:password -X DELETE \
    "http://<manager-ip>/api/v3.1/operations/<operation_id>"

client.operations.delete(operation_id)

DELETE "{manager-ip}/api/v3.1/operations/{operation-id}" Deletes an operation. Note that operations which are terminated should still be stored in persistent storage, and should have their state updated to SUCCEEDED or FAILED rather than be deleted.

Response

No content - HTTP code 204.

Permissions

The permissions endpoints allow assigning and removing specific permissions from roles.

The Permission resource

Attributes:

Attribute	Type	Description
`permission`	string	The name of the permission, eg. “blueprint_list”
`role`	string	The role that has the permission, eg. “operations”

List all permissions

Request Example

$ curl -X GET \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/permissions"

permissions = client.permissions.list()

for p in permissions:
    print("role ", p['role'], " has permission ", p['permission'])

Response Example

{
  "items": [
    {"role": "operations", "permission": "agent_list"},
    {"role": "operations", "permission": "agent_create"},
    {"role": "operations", "permission": "agent_update"},
    ...
  ],
  "metadata": {
    "pagination": {
      "total": 128,
      "offset": 0,
      "size": 1000
    }
  }
}

GET "{manager-ip}/api/v3.1/permissions"

Lists all permissions, assigned to all roles.

Response

List of Permission resources.

List permission for a given role

Request Example

$ curl -X GET \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/permissions/<role-name>"

permissions = client.permissions.list(role='<role-name>')

Response Example

{
  "items": [
    {"role": "operations", "permission": "agent_list"},
    {"role": "operations", "permission": "agent_create"},
    {"role": "operations", "permission": "agent_update"},
    ...
  ],
  "metadata": {
    "pagination": {
      "total": 128,
      "offset": 0,
      "size": 1000
    }
  }
}

GET "{manager-ip}/api/v3.1/permissions/{role-name}"

Lists all permissions, assigned to the given role.

Response

List of Permission resources.

Assign permission for a role

Request Example

$ curl -X PUT \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/permissions/<role-name>/<permission-name>"

permissions = client.permissions.add(
    permission='blueprint_list',
    role='viewer'
)

PUT "{manager-ip}/api/v3.1/permissions/{role-name}/{permission-name}"

Add a permission to a role. Users who have this role assigned will immediately be able to use endpoints that require the added permission.

Response

The newly-created Permission resource.

Remove permission from a role

Request Example

$ curl -X DELETE \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/permissions/<role-name>/<permission-name>"

permissions = client.permissions.delete(
    permission='blueprint_list',
    role='viewer'
)

DELETE "{manager-ip}/api/v3.1/permissions/{role-name}/{permission-name}"

Remove a permission from a role. Users who have this role will immediately be prevented from using endpoints that require the removed permission (unless they also have another role that allows it).

Response

No content.

Plugins

The Plugin Resource

Attributes:

Attribute	Type	Description
`archive_name`	string	The plugin archive file name.
`blueprint_labels`	dict	The blueprint labels which describe blueprints using this plugin.
`created_by`	string	The user who created the plugin.
`distribution_release`	string	The OS distribution release name the plugin was compiled on. ‘None’ in-case the plugin is cross platform.
`distribution_version`	string	The OS distribution version the plugin was compiled on. ‘None’ in-case the plugin is cross platform.
`distribution`	string	The OS distribution the plugin was compiled on. ‘None’ in-case the plugin is cross platform.
`excluded_wheels`	list	a list of wheels that were excluded from the plugin package.
`id`	string	The ID assigned to the plugin upon upload.
`installation_state`	list	The state of plugin installation (usually either empty list or ‘[“installed”]').
`package_name`	string	The python package name.
`package_source`	string	The python package source, i.e git, pip etc.
`package_version`	string	The python package version.
`resource_tags`	dict	The resource tags which for this plugin.
`supported_platform`	string	The supported platform for the plugin package, ‘any’ if the plugin is compatible with all platforms.
`supported_py_versions`	list	a list of python platforms supported by the plugin.
`tenant_name`	string	The name of the tenant that owns the plugin.
`title`	string	The plugin title used e.g. in UI topology view.
`uploaded_at`	ISO 8601	The time and date the plugin was uploaded on to the Conductor-Manager.
`wheels`	list	A list of wheels contained in the plugin package.

List Plugins

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/plugins?_include=id"

# Using CloudifyClient
plugins = client.plugins.list(_include=['id'])
for plugin in plugins:
    print plugin

# Using requests
url = 'http://<manager-ip>/api/v3.1/plugins'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "ecea687a-b7dc-4d02-909d-0400aa23df27"
    },
    {
      "id": "f10a4970-6cfa-4b24-9cab-f85db93204e0"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/plugins"

Lists all plugins.

Response

Field	Type	Description
`items`	list	A list of `Plugin` resources.
`metadata`	dict	Metadata relevant to the list response.

Get Plugin

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/plugins/<plugin-id>?_include=id"

# Using CloudifyClient
client.plugins.get(plugin_id='<plugin-id'>', _include=['id'])

# Using requests
url = 'http://<manager-ip>/api/v3.1/plugins/<plugin-id>'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "id": "ecea687a-b7dc-4d02-909d-0400aa23df27"
}

GET "{manager-ip}/api/v3.1/plugins/{plugin-id}"

Gets a plugin.

URI Parameters

plugin-id: The id of the plugin.

Response

A Plugin resource.

Update Plugin

Request Example

# curl -X PATCH \
    --header "Content-Type: application/json" \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"creator": <new-owner>, "blueprint_labels": <new-blueprint-labels>, "labels": <new-labels>}', "resource_tags": <new-resource-tags> \
    "http://<manager-ip>/api/v3.1/plugins/<plugin-id>"

# Using CloudifyClient
client.plugins.update(plugin_id='<plugin-id>',
                      creator='<new-owner>',
                      blueprint_labels='<new-blueprint-labels>',
                      labels='<new-labels>',
                      resource_tags='<new-resource-tags>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/plugins/<plugin-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
payload = {
    'creator': '<new-owner>',
    'blueprint_labels': '<new-blueprint-labels>',
    'labels': '<new-labels>',
    'resource_tags': '<new-resource-tags>',
}
requests.patch(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    json=payload,
)

PATCH "{manager-ip}/api/v3.1/plugins/{plugin-id}"

Updates (some) plugin’s attributes, currently supported are: creator (user changing this attribute must be granted special set_owner permission), blueprint_labels, labels and resource_tags.

URI Parameters

plugin-id: The id of the plugin.

Request Body

Property	Type	Description
`new-owner`	string	Specifies the new owner of the plugin (optional).
`new-blueprint-labels`	dict	Specifies new blueprint_labels for the plugin (optional).
`new-labels`	dict	Specifies new (deployment) labels for the plugin (optional).
`new-resource-tags`	dict	Specifies new resource tags for the plugin (optional).

Response

A Plugin resource.

Delete Plugin

Request Example

$ curl -X DELETE \
    --header "Content-Type: application/json" \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"force": false}' \
    "http://<manager-ip>/api/v3.1/plugins/<plugin-id>?_include=id"

# Using CloudifyClient
client.plugins.delete(plugin_id='<plugin-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/plugins/<plugin-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'_include': 'id'}
payload = {'force': False}
requests.delete(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)

DELETE "{manager-ip}/api/v3.1/plugins/{plugin-id}"

Deletes a plugin from the Conductor-Manager.

URI Parameters

plugin-id: The id of the plugin.

Request Body

Property	Default	Description
`force`	false	Specifies whether to force plugin deletion even if there are deployments that currently use it.

Response

No content - HTTP code 204.

Upload Plugin

Request Example

$ curl -X POST \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/plugins?plugin_archive_url=http://url/to/archive.wgn&title=<title>&_include=id&visibility=<visibility>"

# Using CloudifyClient
client.plugins.upload(plugin_path='http://url/to/archive.wgn',
                      plugin_title='My Plugin',
                      visibility='<visibility>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/plugins'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'plugin_archive_url': 'http://url/to/archive.wgn',
    'title': 'My Plugin',
    '_include': 'id',
    'visibility': '<visibility>'
}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Example Response

{
  "id": "d80542f4-ec0c-4438-8a29-54cb9a904114"
}

POST "{manager-ip}/api/v3.1/plugins"

Upload a plugin

Request Body

Property	Type	Description
`plugin_path`	string	The plugin archive local path.
`plugin_archive_url`	string	A URL of the plugin archive to be uploaded. The plugin will be downloaded by the manager.
`title`	string	The plugin title, used e.g. in UI topology view (this is an optional parameter).
`visibility`	string	Optional parameter, defines who can see the plugin (default: tenant).

Valid visibility values are:

private: The resource is visible to the user that created the resource, the tenant’s managers and the system’s admins.
tenant: The resource is visible to all users in the current tenant. (Default value)
global: The resource is visible to all users in all tenants across the manager.

Response

The new uploaded Plugin resource.

Download Plugin

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/plugins/<plugin-id>/archive" > <plugin-archive-filename>.wgn

# Using CloudifyClient
client.plugins.download(
   plugin_id='<plugin-id>',
   output_file='<plugin-archive-filename>',
)

# Using Requests
url = 'http://<manager-ip>/api/v3.1/plugins/<plugin-id>/archive'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
with open('<plugin-archive-filename>.wgn', 'wb') as plugin_archive:
    plugin_archive.write(response.content)

GET "{manager-ip}/api/v3.1/plugins/{plugin-id}/archive"

Downloads a plugin.

URI Parameters

plugin-id: The id of the plugin.

Response

The requested plugin archive.

URI Parameters

plugin-id: The id of the plugin to update.

Response

A Plugin resource.

Set Plugin Visibility

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"visibility": "<visibility>"}' \
    "http://<manager-ip>/api/v3.1/plugins/<plugin-id>/set-visibility"

# Python Client
client.plugins.set_visibility('<plugin-id>', '<visibility>')

Response Example

{
  "distribution_release": "core",
  "supported_py_versions": [
    "py27"
  ],
  "uploaded_at": "2017-10-19T14:19:39.727Z",
  "archive_name": "cloudify_openstack_plugin-2.0.1-py27-none-linux_x86_64-centos-Core.wgn",
  "package_name": "cloudify-openstack-plugin",
  "distribution_version": "7.0.1406",
  "tenant_name": "default_tenant",
  "excluded_wheels": [

  ],
  "created_by": "admin",
  "distribution": "centos",
  "package_source": "https://github.com/cloudify-cosmo/cloudify-openstack-plugin/archive/master.tar.gz",
  "private_resource": false,
  "visibility": "global",
  "supported_platform": "linux_x86_64",
  "package_version": "2.0.1",
  "wheels": [
    "keystoneauth1-2.19.0-py2.py3-none-any.whl",
    "python_novaclient-7.0.0-py2.py3-none-any.whl",
     ...
  ],
  "id": "c7f6757e-b48d-4c26-ab91-cfc8c1e4851c"
}

PATCH "<manager-ip>/api/v3.1/plugins/{plugin-id}/set-visibility"

Update the visibility of the plugin.

URI Parameters

plugin-id: The id of the plugin to update.

Request Body

Property	Type	Description
`visibility`	string	Defines who can see the plugin. (Required)

Valid values are tenant or global.

Response

A Plugin resource.

The Plugins Update Resource

Attributes:

Attribute	Type	Description
`id`	string	A unique identifier for the plugins update.
`state`	string	The state of this update (“updating”, “executing_workflow”, “finalizing”, “successful”, “failed”, or “no_changes_required”).
`blueprint_id`	string	The id of the blueprint that its deployments will get their plugins updated.
`temp_blueprint_id`	string	The id of the temporary internal blueprint created for the purpose of this plugins update.
`execution_id`	string	The id of the plugins update execution.
`deployments_to_update`	list	A list of deployment IDs that are updated in this plugins update.
`forced`	bool	Whether or not this plugins update was forced on a blueprint which is used as a component.
`created_at`	datetime	The time when the plugins update was started.
`created_by`	string	The name of the user that started the plugins update.
`tenant_name`	string	The name of the tenant the plugins update belongs to.
`visibility`	string	The visibility of the plugins update.
`private_resource`	boolean	Is the plugins update private.
`resource_availability`	string	The availability of the plugins update.

Update Plugins

Request Example

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"plugin_names": "<plugin_names>", "to-latest": "<to-latest>", "all-to-latest": "<all-to-latest>", "to-minor": "<to-minor>", "all-to-minor": "<all-to-minor>", "force": "<force>", "auto-correct-types": "<auto-correct-types>", "reevaluate-active-statuses": "<reevaluate-active-statuses>"}' \
    "<manager-ip>/api/v3.1/plugins-updates/<blueprint-id>/update/initiate"

# Python Client
client.plugins_update.update_plugins(blueprint_id="<blueprint_id>", force="<force>", plugin_names="<plugin_names>", to_latest="<to_latest>", all_to_latest="<all_to_latest>", to_minor="<to_minor>", all_to_minor="<all_to_minor>", mapping="<mapping>", auto_correct_types="<auto_correct_types>", reevaluate_active_statuses="<reevaluate_active_statuses>")

Response Example

{
 "forced": false,
 "blueprint_id": "baddd86fb-864b-483e-a98a-d53e2b728ccd",
 "tenant_name": "default_tenant",
 "created_at": "2019-07-10T07:24:40.520Z",
 "visibility": "tenant",
 "private_resource": false,
 "state": "executing_workflow",
 "temp_blueprint_id": "bbf4b172-3b21-460c-aed8-4f55b55f3b4f",
 "created_by": "admin",
 "deployments_to_update": [
    "dd7b03fb3-8f92-404c-8ddd-d81bd6a2bc9b"
 ],
 "resource_availability": "tenant",
 "id": "ce63a9d6-726b-4ff2-a267-f953af5dc32d",
 "execution_id": "8ec77e89-b418-4472-9b44-fe9d7a7fe163"
}

POST "<manager-ip>/api/v3.1/plugins-updates/<blueprint-id>/update/initiate"

Update the plugins for that blueprint’s deployments.

URI Parameters

blueprint-id: The id of the blueprint that its deployments will get their plugins updated.

Request Body

Property	Type	Description
`plugin_names`	list	Update only the specific plugin in all selected deployments.
`to_latest`	list	List of plugin names to be upgraded to the latest version.
`all_to_latest`	boolean	Update all (selected) plugins to the latest version of a plugin
`to_minor`	list	List of plugin names to be upgraded to the latest minor version.
`all_to_minor`	boolean	Update all (selected) plugins to the latest minor version of a plugin
`force`	boolean	Force running the update also in case a blueprint (for which the update is executed) is used as a component
`auto_correct_types`	boolean	If set, before creating plan for a new deployment, an attempt will be made to cast old inputs’ values to the valid types declared in blueprint.
`reevaluate_active_statuses`	boolean	If set, before attempting to update, the statuses of previous active update operations will be reevaluated based on relevant executions' statuses. This flag is also passed down to the deployment update flows and has a similar effect on those.

Response

A Plugins Update resource.

Get Plugins-Update

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/plugins-updates/<plugins-update-id>?_include=id"

# Using CloudifyClient
plugins_update = client.plugins_update.get(plugins_update_id=plugins_update_id)

Response Example

{
 "forced": false,
 "blueprint_id": "baddd86fb-864b-483e-a98a-d53e2b728ccd",
 "tenant_name": "default_tenant",
 "created_at": "2019-07-10T07:24:40.520Z",
 "visibility": "tenant",
 "private_resource": false,
 "state": "executing_workflow",
 "temp_blueprint_id": "bbf4b172-3b21-460c-aed8-4f55b55f3b4f",
 "created_by": "admin",
 "deployments_to_update": [
    "dd7b03fb3-8f92-404c-8ddd-d81bd6a2bc9b"
 ],
 "resource_availability": "tenant",
 "id": "ce63a9d6-726b-4ff2-a267-f953af5dc32d",
 "execution_id": "8ec77e89-b418-4472-9b44-fe9d7a7fe163"
}

GET "<manager-ip>/api/v3.1/plugins-updates/<plugins-update-id>"

Get a plugins update.

Response

A Plugins Update resource.

List Plugins Updates

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/plugins-updates?_include=id"

# Using CloudifyClient
plugins_updates = client.plugins_update.list(
        sort=sort_by,
        is_descending=descending,
        _all_tenants=all_tenants,
        _search=search,
        _offset=pagination_offset,
        _size=pagination_size,
        plugins_update_id=plugins_update_id
    )

Response Example

{
  "items": [
    {
      "id": "update1",
      ...
    },
    {
      "id": "update2",
      ...
    },
    {
      "id": "update3",
      ...
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/plugins-updates"

Lists the plugins updates.

Response

Field	Type	Description
`items`	list	A list of `Plugins Update` resources.

Searches

The /searches/<resource> endpoint is used to get a filtered list of resources based on their labels and certain attributes or constraints.

Search Resources

Resource	Pre-created filter	Attributes which can be used to filter by	Filter by label	Search by
`blueprints`	blueprints filter	id, state, tenant_name, created_by	yes	id
`secrets`		key	no	id (key)
`deployments`	deployments filter	id, blueprint_id, created_by, site_name, schedules, tenant_name, display_name, installation_status	yes	id, display_name
`workflows`	deployments filter	—	deployment’s label	(deployment) id
`capabilities`		—	no	capability value
`scaling-groups`		—	no	scaling_group name
`nodes`		id, type	no	id
`node-types`		id, type	no	type
`node-instances`		id	no	id

For more details on the pre-created filters see the documentation about blueprint filters and deployment filters.

All the search queries can be extended with the _search parameter. The attribute being searched for is indicated in the last column of the above table.

Note: capabilities search will return both the values which are stored in the database (already evaluated) and the ones defined with intrinsic functions (evaluated during the search).

Search with Filtering Rules

Filtering can be done by specifying a pre-created filter ID (for some resources) or by providing a list of filter rules.

A filter rule is a dictionary of the following form:

{
 "key": "<key>",
 "values": [<list of values>],
 "operator": "<LabelsOperator>" or "<AttrsOperator>",
 "type": "<FilterRuleType>"
}

<LabelsOperator> can be one of: “any_of”, “not_any_of”, “is_null” or “is_not_null”.

<AttrsOperator> can be one of: “any_of”, “not_any_of”, “contains”, “not_contains”, “starts_with”, “ends_with”, “is_not_empty”.

<FilterRuleType> can be one of: “label” or “attribute”. If “label” is provided, then the operator must be a <LabelsOperator>, and if “attribute” is provided, then the operator must be an <AttrsOperator>.

E.g. filtering by the following filter rules, will return all items of a resource whose creator name starts with alice or bob, and have the label environment:aws assigned to them.

[
 {
  "key": "created_by",
  "values": ["alice", "bob"],
  "operator": "starts-with",
  "type": "attribute"
 },
 {
  "key": "environment",
  "values": ["aws"],
  "operator": "any_of",
  "type": "label"
 }
]

Search Using Constraints

Alternatively constraints dictionary can be used instead of filter_rules and filter_id to search for the resources matching given constraints. If you want to know more about the constraints, visit this Cloudify Documentation section.

The following constraints can be used to find the blueprints, which have at least these two labels set (environment=k8s and tier=staging) and IDs containing the string cellar and ending with app (e.g. wine_cellar_app).

{
  "labels": [
    {"environment": "k8s"},
    {"tier": "staging"}
  ],
  "name_pattern": {
    "ends_with": "app",
    "contains": "cellar"
  }
}

Search Additional Features

Additionally, a query string can be used to filter out specific resources. In case of blueprints and workflows the _search field name is being used to filter these by id. It is slightly more complicated for deployments. Two fields can be used: _search (to find deployments by id) and _search_name (to find deployments by their display_name). The resulting set of deployments will be the union of both sub-sets.

Request Example

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"filter_rules": <a list of filter rules as described above>}' \
    "https://<manager-ip>/api/v3.1/searches/<resource>?_include=id"

<resource> can be either blueprints, deployments or workflows.

# Using CloudifyClient
deployments = client.deployments.list(filter_rules=[...])
# Or
blueprints = client.blueprints.list(constraints={...})

# Using requests
url = 'https://<manager-ip>/api/v3.1/searches/<resource>' # `<resource>` can be either `blueprints`, `deployments` or `workflows`
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
payload = {'constraints': {...}}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload
)
response.json()

When searching for workflows, the _common_only flag can be used in the query string to list only the workflows which are common between the filtered deployments.

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"filter_rules": <a list of filter rules as described above>}' \
    "https://<manager-ip>/api/v3.1/searches/workflows?_common_only=True"

Search Response

Response Example

{
  "items": [
    {
      "id": "resource1"
    },
    {
      "id": "resource2"
    },
    {
      "id": "resource3"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 0
    }
  }
}

POST "{manager-ip}/api/v3.1/searches/<resource>"

Get a filtered list of resource’s items.

Field	Type	Description
`items`	list	A filtered list of resource’s items.

Secrets

The Secret Resource

A Secret resource is a key-value pair saved per tenant. A user can ensure all secrets (such as credentials to IaaS environments, passwords, etc) are kept in a secured manner, and adhere to isolation requirements between different tenants.

Attributes:

Attribute	Type	Description
`key`	string	The secret’s key, unique per tenant.
`value`	string	The secret’s value.
`schema`	dict	A JSON schema against which the secret will be validated.
`is_hidden_value`	boolean	Determines who can see the value of the secret. If True, the value of the secret is only shown to the user that created the secret and to admins. (default: false). Supported for Cloudify Manager 4.4 and above.
`visibility`	string	Defines who can see the secret. Can be private, tenant or global. Supported for Cloudify Manager 4.3 and above.
`tenant_name`	string	The name of the tenant of the secret.
`provider_name`	string	The secret’s provider name.
`provider_options`	dict	The secret’s provider options.
`created_by`	string	The author of the secret.
`created_at`	datetime	The time when the secret was created.
`updated_at`	datetime	The time the secret was last updated at.

List Secrets

Request Example

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    --cacert <path_to_ca_cert> \
    "https://<manager_ip>/api/v3.1/secrets"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient

client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
    cert='<path_to_ca_cert>',
)
client.secrets.list()

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'https://<manager_ip>/api/v3.1/secrets'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
    verify='<path_to_ca_cert>',
)
response.json()

Response Example

{
    "metadata": {
        "pagination": {
            "total": 1,
            "size": 1000,
            "offset": 0
        },
        "filtered": null
    },
    "items": [
        {
            "key": "<secret_key>",
            "created_at": "2022-12-20T10:02:06.751Z",
            "updated_at": "2022-12-20T10:02:06.751Z",
            "resource_availability": "tenant",
            "visibility": "tenant",
            "tenant_name": "default_tenant",
            "created_by": "admin",
            "is_hidden_value": false,
            "provider_name": null
        }
    ]
}

GET "{manager_ip}/api/v3.1/secrets"

List all secrets.

Response

Field	Type	Description
`items`	list	A list of `Secret` resources without the secret’s value.
`metadata`	dict	Information about pagination result.

Get Secret

Request Example

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    --cacert <path_to_ca_cert> \
    "https://<manager_ip>/api/v3.1/secrets/<secret_key>?_skip_value={true/false}"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient

client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
    cert='<path_to_ca_cert>',
)
client.secrets.get('<secret_key>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'https://<manager_ip>/api/v3.1/secrets/<secret_key>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
querystring = {'_skip_value': False}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
    params=querystring,
    verify='<path_to_ca_cert>',
)
response.json()

Response Example

{
    "created_at": "2022-12-20T10:02:06.751Z",
    "visibility": "tenant",
    "value": "<secret_value>",
    "updated_at": "2022-12-20T10:02:06.751Z",
    "is_hidden_value": false,
    "schema": null,
    "provider_options": null,
    "key": "<secret_key>",
    "provider_name": null,
    "tenant_name": "default_tenant",
    "created_by": "admin",
    "resource_availability": "tenant",
    "private_resource": false
}

GET "{manager_ip}/api/v3.1/secrets/{secret_key}?_skip_value={true/false}"

Retrieves a specific secret.

URI Parameters

secret_key: The key of the secret to retrieve.
_skip_value: (Default: false) Optional parameter, determine if value should be skipped in response.

Response

A Secret resource.

Create Secret

Request Example

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    --cacert <path_to_ca_cert> \
    -d '{"value": "<secret_value>", "update_if_exists": false, "visibility": "<visibility>", "is_hidden_value": false, "schema": {}, "provider_name": "<provider_name>", "provider_options": {}}' \
    "https://<manager_ip>/api/v3.1/secrets/<secret_key>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient

client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
    cert='<path_to_ca_cert>',
)
client.secrets.create(
    '<secret_key>',
    '<secret_value>',
    update_if_exists=False,
    visibility='<visibility>',
    is_hidden_value=False,
    schema={},
    provider_name='<provider_name>',
    provider_options={},
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'https://<manager_ip>/api/v3.1/secrets/<secret_key>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'value': '<secret_value>',
    'update_if_exists': False,
    'visibility': '<visibility>',
    'is_hidden_value': False,
    'schema': {},
    'provider_name': '<provider_name>',
    'provider_options': {},
}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
    verify='<path_to_ca_cert>',
    json=payload,
)
response.json()

Response Example

{
    "created_at": "2022-12-20T11:01:12.406Z",
    "visibility": "tenant",
    "value": "<secret_value_encrypted>",
    "updated_at": "2022-12-20T11:01:12.406Z",
    "is_hidden_value": false,
    "schema": null,
    "provider_options": null,
    "key": "<secret_key>",
    "provider_name": null,
    "tenant_name": "default_tenant",
    "created_by": "admin",
    "resource_availability": "tenant",
    "private_resource": false
}

PUT -d '{"value": "<secret_value>", "update_if_exists": false, "visibility": "<visibility>", "is_hidden_value": false, "schema": {}, "provider_name": "<provider_name>", "provider_options": {}}'

Creates a secret.

URI Parameters

new_secret_key: The key of the secret to create.

Request Body

Property	Type	Description
`value`	string	The secret’s value.
`update_if_exists`	boolean	Update value if secret already exists (optional, defaults to false).
`visibility`	string	Optional parameter, defines who can see the secret (default: tenant). Supported for Cloudify Manager 4.3 and above.
`is_hidden_value`	boolean	Optional parameter, determines who can see the value of the secret. If True, the value of the secret is only shown to the user that created the secret and to admins. (default: false). Supported for Cloudify Manager 4.4 and above.
`schema`	dict	Optional parameter, defines how the secret should be validated.
`provider_name`	string	Optional parameter, defines which provider should be used to get the secret’s value.
`provider_options`	dict	Optional parameter, defines additional options to get the secret’s value via provider.

Valid visibility values are:

private: The resource is visible to the user that created the resource, the tenant’s managers and the system’s admins.
tenant: The resource is visible to all users in the current tenant. (Default value)
global: The resource is visible to all users in all tenants across the manager.

Response

A Secret resource.

Update Secret

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    --cacert <path_to_ca_cert> \
    -d '{"value": "<secret_value>", "visibility": "<visibility>", "is_hidden_value": false, "creator": "<creator_name>", "provider_name": "<provider_name>", "provider_options": {}}' \
    "https://<manager_ip>/api/v3.1/secrets/<secret_key>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient

client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
    cert='<path_to_ca_cert>',
)
client.secrets.update(
    '<secret_key>',
    '<secret_value>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'https://<manager_ip>/api/v3.1/secrets/<secret_key>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {'value': '<secret_value>'}
response = requests.patch(
    url,
    auth=auth,
    headers=headers,
    verify='<path_to_ca_cert>',
    json=payload,
)
response.json()

Response Example

{
    "created_at": "2022-12-20T11:01:12.406Z",
    "visibility": "tenant",
    "value": "<secret_value_encrypted>",
    "updated_at": "2022-12-20T11:38:08.072Z",
    "is_hidden_value": false,
    "schema": null,
    "provider_options": null,
    "key": "<secret_key>",
    "provider_name": null,
    "tenant_name": "default_tenant",
    "created_by": "admin",
    "resource_availability": "tenant",
    "private_resource": false
}

PATCH -d '{"value": "<secret_value>", "visibility": "<visibility>", "is_hidden_value": false, "creator": "<creator_name>", "provider_name": "<provider_name>", "provider_options": {}}' "{manager_ip}/api/v3.1/secrets/{secret_key}"

Updates a secret.

URI Parameters

secret_key: The key of the secret to update.

Request Body

Property	Type	Description
`value`	string	The secret’s new value.
`visibility`	string	Optional parameter, defines who can see the secret (default: tenant). Supported for Cloudify Manager 4.3 and above.
`is_hidden_value`	boolean	Optional parameter, determines who can see the value of the secret. If True, the value of the secret is only shown to the user that created the secret and to admins. (default: false). Supported for Cloudify Manager 4.4 and above.
`creator`	string	The secret’s owner (username).
`provider_name`	string	Optional parameter, defines which provider should be used to get the secret’s value.
`provider_options`	dict	Optional parameter, defines additional options to get the secret’s value via provider.

Response

A Secret resource.

Delete Secret

Request Example

$ curl -X DELETE \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    --cacert <path_to_ca_cert> \
    "https://<manager_ip>/api/v3.1/secrets/<secret_key>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient

client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
    cert='<path_to_ca_cert>',
)
client.secrets.delete('<secret_key>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'https://<manager_ip>/api/v3.1/secrets/<secret_key>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
requests.delete(
    url,
    auth=auth,
    headers=headers,
    verify='<path_to_ca_cert>',
)

DELETE "{manager_ip}/api/v3.1/secrets/{secret_key}"

Deletes a secret.

URI Parameters

secret_key: The key of the secret to delete.

Response

No content - HTTP code 204.

Set Secret Visibility

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    --cacert <path_to_ca_cert> \
    -d '{"visibility": "<visibility>"}' \
    "https://<manager_ip>/api/v3.1/secrets/<secret-key>/set-visibility"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient

client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
    cert='<path_to_ca_cert>',
)
client.secrets.set_visibility(
    '<secret-key>',
    '<visibility>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'https://<manager_ip>/api/v3.1/secrets/<secret-key>/set-visibility'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {'visibility': '<visibility>'}
response = requests.patch(
    url,
    auth=auth,
    headers=headers,
    verify='<path_to_ca_cert>',
    json=payload,
)
response.json()

Response Example

{
    "created_at": "2022-12-20T10:59:08.673Z",
    "visibility": "global",
    "value": "<secret_value_encrypted>",
    "updated_at": "2022-12-20T16:50:29.232Z",
    "is_hidden_value": false,
    "schema": null,
    "provider_options": null,
    "key": "<secret_key>",
    "provider_name": null,
    "tenant_name": "default_tenant",
    "created_by": "admin",
    "resource_availability": "global",
    "private_resource": false
}

PATCH "<manager_ip>/api/v3.1/secrets/{secret-key}/set-visibility"

Update the visibility of the secret.

URI Parameters

secret-key: The key of the secret to update.

Request Body

Property	Type	Description
`visibility`	string	Defines who can see the secret. (Required)

Valid values are tenant or global.

Response

A Secret resource.

Export Secrets

Request Example

 $ curl -X GET \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    --cacert <path_to_ca_cert> \
    "https://<manager_ip>/api/v3.1/secrets/share/export?_passphrase=<passphrase>?non-encrypted=false"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient

client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
    cert='<path_to_ca_cert>',
)
client.secrets.export(
    _passphrase='<passphrase>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'https://<manager_ip>/api/v3.1/secrets/share/export'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
querystring = {'_passphrase': '<passphrase>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
    verify='<path_to_ca_cert>',
    params=querystring,
)
response.json()

Response Example

[
    {
        "key": "<secret_key>",
        "value": "<secret_value_encrypted>",
        "visibility": "global",
        "tenant_name": "default_tenant",
        "is_hidden_value": false,
        "encrypted": true
    },
    {
        "key": "<secret_key>",
        "value": "<secret_value_encrypted>",
        "visibility": "global",
        "tenant_name": "default_tenant",
        "is_hidden_value": false,
        "encrypted": true
    },
    {
        "key": "<secret_key>",
        "value": "<secret_value_encrypted>",
        "visibility": "global",
        "tenant_name": "default_tenant",
        "is_hidden_value": false,
        "encrypted": true
    }
]

GET "<manager_ip>/api/v3.1/secrets/share/export"

Export secretes from the Manager to a file.

URI Parameters

_passphrase: The passphrase used to encrypt or secrets` values, must be 8 characters long.

Response

A list of Secret resources.

Import Secrets

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    --cacert <path_to_ca_cert> \
    -d '{"secrets_list": [{"key": "<secret_key>", "value": "<secret_value>", "visibility": "<visibility>", "tenant_name": "<tenant_name>", "is_hidden_value": false, "encrypted": false}], "tenant_map_dict": {"<tenant_name>": "<tenant_name>"}, "passphrase": "<passphrase>", "override_collisions": false}' \
    "https://<manager_ip>/api/v3.1/secrets/share/import"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient

client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
    cert='<path_to_ca_cert>',
)
client.secrets.import_secrets(
    secrets_list=[
        {
            "key": "<secret_key>",
            "value": "<secret_value>",
            "visibility": "<visibility>",
            "tenant_name": "<tenant_name>",
            "is_hidden_value": False,
            "encrypted": False
        }
    ],
    tenant_map={
        '<tenant_name>': '<tenant_name>',
    },
    passphrase='<passphrase>',
    override_collisions=False,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'https://<manager_ip>/api/v3.1/secrets/share/import'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'secrets_list': [
        {
            "key": "<secret_name>",
            "value": "<secret_value>",
            "visibility": "<visibility>",
            "tenant_name": "<tenant_name>",
            "is_hidden_value": False,
            "encrypted": False
        }
    ],
    'tenant_map_dict': {
        '<tenant_name>': '<tenant_name>',
    },
    'passphrase': '<passphrase>',
    'override_collisions': False,

}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
    verify='<path_to_ca_cet>',
    json=payload,
)
response.json()

Response Example

{
    "colliding_secrets": {},
    "secrets_errors": {}
}

POST "<manager_ip>/api/v3.1/secrets/share/import"

Import secrets from a file to the Manager. Supported for Cloudify Manager 5.0 and above.

Response

An import result in JSON format.

Secrets Providers

The Secrets Provider Resource

A Secrets Provider resource is a set of details and credentials required to get a secret value, saved per tenant. A user can ensure all providers are kept in a secured manner, and adhere to isolation requirements between different tenants.

Attributes:

Attribute	Type	Description
`id`	string	The Secrets Provider’s name, unique per tenant.
`name`	string	The Secrets Provider’s name, unique per tenant.
`type`	string	The Secrets Provider’s type.
`connection_parameters`	dict	The Secrets Provider’s connection parameters (e.g. host, username, password etc).
`visibility`	string	Defines who can see the provider. Can be private, tenant or global. Supported for Cloudify Manager 4.3 and above.
`tenant_name`	string	The name of the tenant of the provider.
`created_by`	string	The author of the provider.
`created_at`	datetime	The time when the provider was created.
`updated_at`	datetime	The time the provider was last updated at.

List Secrets Providers

Request Example

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    --cacert <path_to_ca_cert> \
    "https://<manager_ip>/api/v3.1/secrets-providers"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient

client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
    cert='<path_to_ca_cert>',
)
client.secrets_providers.list()

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'https://<manager_ip>/api/v3.1/secrets-providers'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
    verify='<path_to_ca_cert>',
)
response.json()

Response Example

{
    "metadata": {
        "pagination": {
            "total": 1,
            "size": 1000,
            "offset": 0
        },
        "filtered": null
    },
    "items": [
        {
            "created_at": "2022-12-20T18:04:17.615Z",
            "id": "<provider_name>",
            "visibility": "tenant",
            "name": "<provider_name>",
            "type": "local",
            "connection_parameters": null,
            "updated_at": null,
            "tenant_name": "default_tenant",
            "created_by": "admin",
            "resource_availability": "tenant",
            "private_resource": false
        }
    ]
}

GET "{manager_ip}/api/v3.1/secrets-providers"

List all secrets providers.

Response

Field	Type	Description
`items`	list	A list of `Secrets Provider` resources.
`metadata`	dict	Information about pagination result.

Get Secrets Provider

Request Example

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    --cacert <path_to_ca_cert> \
    "https://<manager_ip>/api/v3.1/secrets-providers/<provider_name>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient

client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
    cert='<path_to_ca_cert>',
)
client.secrets_providers.get('<provider_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'https://<manager_ip>/api/v3.1/secrets-providers/<provider_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
    verify='<path_to_ca_cert>',
)
response.json()

Response Example

{
    "created_at": "2022-12-20T18:04:17.615Z",
    "id": "<provider_name>",
    "visibility": "tenant",
    "name": "<provider_name>",
    "type": "local",
    "connection_parameters": null,
    "updated_at": null,
    "tenant_name": "default_tenant",
    "created_by": "admin",
    "resource_availability": "tenant",
    "private_resource": false
}

GET "{manager_ip}/api/v3.1/secrets-provider/{provider_name}"

Retrieves a specific provider.

URI Parameters

provider_name: The name of the provider to retrieve.

Response

A Secrets Provider resource.

Create Secrets Provider

Request Example

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    --cacert <path_to_ca_cert> \
    -d '{"name": "<provider_name>", "type": "<provider_type>", "connection_parameters": {}, "visibility": "<visibility>"}' \
    "https://<manager_ip>/api/v3.1/secrets-providers"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient

client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
    cert='<path_to_ca_cert>',
)
client.secrets_providers.create(
    name='<provider_name>',
    _type='<provider_type>',
    connection_parameters={},
    visibility='<visibility>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'https://<manager_ip>/api/v3.1/secrets-providers'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'name': '<provider_name>',
    'type': '<provider_type>',
    'connection_parameters': {},
    'visibility': '<visibility>',
}
response = requests.put(
    url,
    auth=auth,
    headers=headers,
    verify='<path_to_ca_cert>',
    json=payload,
)
response.json()

Response Example

{
    "created_at": "2022-12-20T18:31:51.559Z",
    "id": "<provider_name>",
    "visibility": "tenant",
    "name": "<provider_name>",
    "type": "local",
    "connection_parameters": null,
    "updated_at": null,
    "tenant_name": "default_tenant",
    "created_by": "admin",
    "resource_availability": "tenant",
    "private_resource": false
}

PUT -d '{"name": "<provider_name>", "type": "<provider_type>", "connection_parameters": {}, "visibility": "<visibility>"}'

Creates a Secrets Provider.

Request Body

Property	Type	Description
`name`	string	The Secrets Provider’s name.
`type`	string	The Secrets Provider’s type.
`connection_parameters`	dict	The Secrets Provider’s connection parameters (e.g. host, username, password etc).
`visibility`	string	Optional parameter, defines who can see the provider (default: tenant). Supported for Cloudify Manager 4.3 and above.

Valid type values are:

local: Secrets stored in Manager’s database.
vault: Secrets stored in Vault service.
- connection_parameters: {"url": "<vault_url>", "token": "<vault_token>", "path": "<vault_path>"}
cloudify: Secrets stored in remote Manager.
- connection_parameters: {"host": "<manager_host>", "username": "<manager_username>", "password": "<manager_password>", "tenant": "<manager_tenant>"}

Valid visibility values are:

private: The resource is visible to the user that created the resource, the tenant’s managers and the system’s admins.
tenant: The resource is visible to all users in the current tenant. (Default value)
global: The resource is visible to all users in all tenants across the manager.

Response

A Secrets Provider resource.

Update Secrets Provider

Request Example

$ curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    --cacert <path_to_ca_cert> \
    -d '{"type": "<provider_type>", "connection_parameters": {}, "visibility": "<visibility>"}' \
    "https://<manager_ip>/api/v3.1/secrets-providers/<provider_name>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient

client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
    cert='<path_to_ca_cert>',
)
client.secrets_providers.update(
    name='<provider_name>',
    _type='<provider_type>',
    connection_parameters={},
    visibility='<visibility>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'https://<manager_ip>/api/v3.1/secrets-providers/<provider_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'name': '<provider_name>',
    'type': '<provider_type>',
    'connection_parameters': {},
    'visibility': '<visibility>',
}
response = requests.patch(
    url,
    auth=auth,
    headers=headers,
    verify='<path_to_ca_cert>',
    json=payload,
)
response.json()

Response Example

{
    "created_at": "2022-12-20T18:31:13.350Z",
    "id": "<provider_name>",
    "visibility": "global",
    "name": "<provider_name>",
    "type": "local",
    "connection_parameters": null,
    "updated_at": "2022-12-20T19:13:59.079Z",
    "tenant_name": "default_tenant",
    "created_by": "admin",
    "resource_availability": "global",
    "private_resource": false
}

PATCH -d '{"type": "<provider_type>", "connection_parameters": {}, "visibility": "<visibility>"}' "{manager_ip}/api/v3.1/secrets-providers/{provider_name}"

Updates a Secrets Provider.

URI Parameters

provider_name: The name of the provider to update.

Response

A Secrets Provider resource.

Delete Secrets Provider

Request Example

$ curl -X DELETE \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    --cacert <path_to_ca_cert> \
    "https://<manager_ip>/api/v3.1/secrets-providers/<provider_name>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient

client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
    cert='<path_to_ca_cert>',
)
client.secrets_providers.delete('<provider_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'https://<manager_ip>/api/v3.1/secrets-providers/<provider_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
requests.delete(
    url,
    auth=auth,
    headers=headers,
    verify='<path_to_ca_cert>',
)

DELETE "{manager_ip}/api/v3.1/secrets-providers/{provider_name}"

Deletes a Secrets Provider.

URI Parameters

provider_name: The name of the provider to delete.

Response

No content - HTTP code 204.

Test Secrets Provider

Request Example

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    --cacert <path_to_ca_cert> \
    -d '{"name": "<provider_name>", "type": "<provider_type>", "connection_parameters": {}, "test": true}' \
    "https://<manager_ip>/api/v3.1/secrets-providers"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient

client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
    cert='<path_to_ca_cert>',
)
client.secrets_providers.create(
    name='<provider_name>',
    _type='<provider_type>',
    connection_parameters={},
    test=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'https://<manager_ip>/api/v3.1/secrets-providers'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'name': '<provider_name>',
    'type': '<provider_type>',
    'connection_parameters': {},
}
response = requests.put(
    url,
    auth=auth,
    headers=headers,
    verify='<path_to_ca_cert>',
    json=payload,
)
response.json()

PUT -d '{"name": "<provider_name>", "type": "<provider_type>", "connection_parameters": {}, "test": true}'

Test a Secrets Provider.

Response

No content - HTTP code 204.

Sites

The Site Resource

A Site represents a container with a (typically) limited number of nodes. A site can be a mobile cell-tower, or it can be a small branch, or any other logical entity. Sites may be associated with a location which will allow a map view (widget is not available yet) and more advanced capabilities in the future. Sites may contain multiple deployments, which allows for easy grouping and filtering by site.

Attributes:

Attribute	Type	Description
`name`	string	The site’s name, unique per tenant.
`location`	string	The location of the site, expected format: “latitude, longitude” such as “32.071072, 34.787274”.
`visibility`	string	Defines who can see the site. Can be private, tenant or global.
`tenant_name`	string	The name of the tenant that owns the site.
`created_at`	datetime	The time when the site was created.
`created_by`	string	The name of the user that created the site.

List Sites

Request Example

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/sites"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>'
)
client.sites.list()

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/sites'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example

{
    "items": [
        {
            "created_at": "2019-06-12T10:52:45.858Z",
            "created_by": "admin",
            "location": "41.8333925, -88.0121478",
            "name": "Chicago",
            "visibility": "tenant",
            "tenant_name": "default_tenant"
        },
        {
            "created_at": "2019-06-12T10:53:06.968Z",
            "created_by": "admin",
            "location": "25.7823404, -80.3695441",
            "name": "Chicago",
            "visibility": "tenant",
            "tenant_name": "default_tenant"
        },
        {
            "created_at": "2019-06-12T10:53:32.838Z",
            "created_by": "admin",
            "location": "32.080327, 34.767420",
            "name": "Tel-Aviv",
            "visibility": "tenant",
            "tenant_name": "default_tenant"
        }
    ],
    "metadata": {
        "pagination": {
            "offset": 0,
            "size": 1000,
            "total": 3
        }
    }
}

GET "{manager_ip}/api/v3.1/sites"

List all sites.

Response

Field	Type	Description
`items`	list	A list of `Site` resources.

Get Site

Request Example

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/sites/<site_name>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>',
)
client.sites.get(<site_name>)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/sites/<site_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example

{
    "created_at": "2019-06-12T10:53:32.838Z",
    "created_by": "admin",
    "location": "32.080327, 34.767420",
    "name": "Tel-Aviv",
    "visibility": "tenant",
    "tenant_name": "default_tenant"
}

GET "{manager_ip}/api/v3.1/sites/{site_name}"

Retrieves a specific site.

URI Parameters

site_name: The name of the site to retrieve.

Response

A Site resource.

Create Site

Request Example

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"location": "<site_location>", "visibility": "<visibility>"}' \
    "http://<manager_ip>/api/v3.1/sites/<site_name>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>',
)
client.sites.create(
    '<site_name>',
    location='<site_location>',
    visibility='<visibility>'
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/sites/<site_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'name': '<site_name>',
    'location': '<site_location>',
    'visibility': '<visibility>'
}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example

{
    "created_at": "2019-06-13T12:38:37.747Z",
    "created_by": "admin",
    "name": "Tel-Aviv",
    "location": "32.080327, 34.767420",
    "visibility": "tenant",
    "tenant_name": "default_tenant"
}

PUT -d '{"location": "<site_location>", "visibility": "<visibility>"}' "{manager_ip}/api/v3.1/sites/{site_name}"

Creates a site.

URI Parameters

site_name: The name of the site to create.

Request Body

Property	Type	Description
`location`	string	Optional parameter, the location of the site, expected format: “latitude, longitude” such as “32.071072, 34.787274”.
`visibility`	string	Optional parameter, defines who can see the site (default: tenant)

Valid visibility values are:

private: The resource is visible to the user that created the resource, the tenant’s managers and the system’s admins.
tenant: The resource is visible to all users in the current tenant. (Default value)
global: The resource is visible to all users in all tenants across the manager.

Response

A Site resource.

Update Site

Request Example

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"new_name": "<site_new_name>", "location": "<site_location>", "visibility": "<visibility>"}' \
    "http://<manager_ip>/api/v3.1/sites/<site_name>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>',
)
client.sites.update(
    '<site_name>',
    location='<site_location>',
    visibility='<visibility>',
    new_name='<site_new_name>'
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/sites/<site_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {'new_name': '<site_new_name>', 'location': '<site_location>', 'visibility': '<visibility>'}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example

{
    "created_at": "2019-06-13T12:38:37.747Z",
    "created_by": "admin",
    "name": "Tel-Aviv",
    "location": "32.080327, 34.767420",
    "visibility": "tenant",
    "tenant_name": "default_tenant"
}

POST -d '{"new_name": "<site_name>", "location": "<site_location>", "visibility": "<visibility>"}' "{manager_ip}/api/v3.1/sites/{site_name}"

Updates a site.

URI Parameters

site_name: The name of the site to update.

Request Body

Property	Type	Description
`new_name`	string	Optional parameter, the new name of the site
`location`	string	Optional parameter, the location of the site, expected format: “latitude, longitude” such as “32.071072, 34.787274”.
`visibility`	string	Optional parameter, defines who can see the site

Valid visibility values are:

tenant: The resource is visible to all users in the current tenant.
global: The resource is visible to all users in all tenants across the manager.

Response

A Site resource.

Delete Site

Request Example

$ curl -X DELETE \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/sites/<site_name>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager_ip>',
        username='<manager_username>',
        password='<manager_password>',
        tenant='<manager_tenant>',
)
client.sites.delete(<site_name>)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/sites/<site_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
requests.delete(
    url,
    auth=auth,
    headers=headers,
)

DELETE "{manager_ip}/api/v3.1/sites/{site_name}"

Deletes a site.

URI Parameters

site_name: The name of the site to delete.

Response

No content - HTTP code 204.

Snapshots

The Snapshot Resource

Attributes:

Attribute	Type	Description
`created_at`	ISO 8601	The time the snapshot was uploaded to or created on the manager.
`error`	string	Message of an error if snapshot creation failed.
`id`	string	A unique identifier of the snapshot.
`status`	string	Status of the snapshot. One of created/failed/uploading/uploaded.

List Snapshots

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/snapshots?_include=id"

# Using CloudifyClient
snapshots = client.snapshots.list(_include=['id'])
for snapshot in snapshots:
    print snapshot

# Using requests
url = 'http://<manager-ip>/api/v3.1/snapshots'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "snapshot1"
    },
    {
      "id": "snapshot2"
    },
    {
      "id": "snapshot3"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3.1/snapshots"

Lists all snapshots.

Response

Attribute	Type	Description
`items`	list	A list of Snapshot resources.

Create Snapshot

Requests Example

$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>"

# Using CloudifyClient
client.snapshots.create(
    snapshot_id='<snapshot-id>',
    include_credentials=False,
)


# Using requests
url = 'http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
payload = {}
response = requests.put(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    json=payload,
)
response.json()

Response Example

{
  "status": "pending",
  "parameters": {
    "config": {
      "postgresql_db_name": "cloudify_db",
      "default_tenant_name": "default_tenant",
      "postgresql_bin_path": "/usr/pgsql-9.5/bin/",
      "failed_status": "failed",
      "postgresql_username": "cloudify",
      "db_port": 9200,
      "postgresql_password": "cloudify",
      "created_status": "created",
      "db_address": "localhost",
      "file_server_root": "/opt/manager/resources",
      "postgresql_host": "localhost"
    },
    "include_credentials": true,
    "snapshot_id": "snapshot4"
  },
  "is_system_workflow": true,
  "blueprint_id": null,
  "tenant_name": "default_tenant",
  "created_at": "2017-05-11T16:16:45.948Z",
  "created_by": "admin",
  "private_resource": false,
  "workflow_id": "create_snapshot",
  "error": "",
  "deployment_id": null,
  "id": "bb9cd6df-7acd-4649-9fc1-fe062759cde8"
}

PUT "{manager-ip}/api/v3.1/snapshots/{snapshot-id}"

Creates a new snapshot.

URI Parameters

snapshot-id: The id of the new snapshot.

Request Body

Property	Type	Description
`include_credentials`	string	Specifies whether agent SSH keys (including those specified in uploaded blueprints) should be included in the created snapshot (Default: false).
`include_logs`	string	Specifies whether logs should be included in the created snapshot (Default: true).above.**
`include_events`	string	Specifies whether events should be included in the created snapshot (Default: true).
`queue`	boolean	If set, snapshot-creation-workflow that can`t currently run will be queued and run automatically when possible.

Response

An Execution resource representing the create snapshot workflow execution.

Delete Snapshot

Requests Example

$ curl -X DELETE \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>"

# Using CloudifyClient
client.snapshots.delete(snapshot_id='<snapshot-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>'
headers = {'Tenant': '<manager-tenant>'}
requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)

DELETE "{manager-ip}/api/v3.1/snapshots/{snapshot-id}"

Deletes an existing snapshot.

URI Parameters

snapshot-id: The id of the snapshot to be deleted.

Response

No content - HTTP code 204.

Restore Snapshot

Requests Example

curl -s -X POST \
    --header "Content-Type: application/json" \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"force": false, "restore_certificates": false, "no_reboot": false}' \
    "http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>/restore"

# Using CloudifyClient
client.snapshots.restore(snapshot_id='<snapshot-id>')

# Using requests
url = 'http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>/restore'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
payload = {
    'force': False,
    'restore_certificates': False,
    'no_reboot': False
}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    json=payload,
)
response.json()

Example Response

{
  "status": "pending",
  "tenant_name": "default_tenant",
  "created_at": "2017-05-11T17:23:30.779Z",
  "created_by": "admin",
  "private_resource": false,
  "error": "",
  "id": "1cadbb76-4532-4eae-a139-80bff328944d"
}

POST "{manager-ip}/api/v3.1/snapshots/{snapshot-id}/restore"

Restores the specified snapshot on the manager.

URI Parameters

snapshot-id: The id of the snapshot to be restored.

Request Body

Property	Default	Description
`force`	false	Specifies whether to force restoring the snapshot on a manager that already contains blueprints/deployments.
`restore_certificates`	false	Specifies whether to try and restore the certificates from the snapshot and use them to override the current Manager certificates, in the event that snapshot’s certificates metadata does not match the current Manager’s certificates metadata. Useful when there are live agents from the Manager from which the snapshot was created that you want to control with the current Manager. After execution the Manager will automatically reboot - unless the `no_reboot` property is `True`.
`no_reboot`	false	Only relevant when the `restore_certificates` property is `True`. Specifies whether to the automatic reboot at the end of the snapshot restore execution. It is not recommended to use this option since the Manager will not function well after certificates restore without a reboot. In that case, you must manually reboot the machine.

Response

An Execution resource representing the restore snapshot workflow execution.

Download Snapshot

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>/archive" > <snapshot-archive-filename>.zip

# Using CloudifyClient
client.snapshots.download(
    snapshot_id='<snapshot-id>',
    output_file='<snapshot-archive-filename>.zip',
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/snapshots/<snapshot-id>/archive'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
with open('<snapshot-archive-filename>.wgn', 'wb') as snapshot_archive:
    snapshot_archive.write(response.content)

GET "{manager-ip}/api/v3.1/snapshots/{snapshot-id}/archive"

Downloads an existing snapshot.

URI Parameters

snapshot-id: The id of the snapshot to be downloaded.

Response

A streamed response (content type application/octet-stream), which is a zip archive containing the snapshot data.

Upload Snapshot

Request Example

$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/snapshots/archive?snapshot_archive_url=http://url/to/archive.zip"

# Using CloudifyClient
client.snapshots.upload(
    snapshot_id='<snapshot-id>',
    snapshot_path='http://url/to/archive.zip',
)

# Using requests
url = 'http://<manager-ip>/api/v3.1/snapshots/archive'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'snapshot_archive_url': 'http://url/to/archive.zip'}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "status": "uploaded",
  "tenant_name": "default_tenant",
  "created_at": "2017-05-11T18:13:25.912Z",
  "created_by": "admin",
  "private_resource": false,
  "error": "",
  "id": "snapshot5"
}

PUT "{manager-ip}/api/v3.1/snapshots/{snapshot-id}/archive"

Uploads a snapshot to the Conductor Manager. The call expects a application/octet-stream content type where the content is a zip archive. It is possible to upload a snapshot from a URL by specifying the URL in the snapshot_archive_url request body property.

URI Parameters

snapshot-id: The id of the snapshot to be uploaded.

Request Body

Property	Type	Description
`snapshot_archive_url`	string	Optional parameter specifying a url to a snapshot that will be uploaded to the manager.

Response

A Snapshot resource.

Snapshot-Restore Status

Request Example

$ curl -X GET "http://<manager-ip>/api/v3.1/snapshot-status"

# Using CloudifyClient
client.snapshots.get_status()

# Using requests
url = 'http://<manager-ip>/api/v3.1/snapshot-status'
response = requests.get(url)
response.json()

Response Example

{
  "status": "No `restore_snapshot` workflow currently running.",
}

GET "{manager-ip}/api/v3.1/snapshot-status"

This method returns the status of the restore_snapshot workflow (whether or not it’s in progress).

Summaries

The summary resource

Attributes:

Attribute	Type	Description
`_target_field`	string	The field to generate a summary on. Valid fields are listed for each sub-resource.
`_sub_field`	string	Optional sub-field to summarise on. Valid fields are identical to those for `_target_field`.

All attributes for filtering the specific resources are also supported, e.g. filtering blueprints by blueprint_id or filtering deployments by deployment_id. See documentation for each resource to find applicable filtering attributes.

Summarize Blueprints

Valid fields: tenant_name, visibility

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/blueprints?_target_field=tenant_name&_all_tenants=true"

With sub-field

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/blueprints?_target_field=tenant_name&_sub_field=visibility&_all_tenants=true"

# Using CloudifyClient
summaries = client.summary.blueprints.get(_target_field='blueprint_id')
for summary in summaries:
    print(summary)

# Using request
url = 'http://<manager-ip>/api/v3.1/summary/blueprints'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_target_field': 'blueprint_id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "blueprints": 3,
      "tenant_name": "test1"
    },
    {
      "blueprints": 3,
      "tenant_name": "test2"
    },
    {
      "blueprints": 3,
      "tenant_name": "default_tenant"
    }
  ],
  "metadata": {
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 3
    }
  }
}

With sub-field

{
  "items": [
    {
      "blueprints": 3,
      "by visibility": [
        {
          "blueprints": 3,
          "visibility": "tenant"
        }
      ],
      "tenant_name": "test1"
    },
    {
      "blueprints": 3,
      "by visibility": [
        {
          "blueprints": 3,
          "visibility": "tenant"
        }
      ],
      "tenant_name": "test2"
    },
    {
      "blueprints": 3,
      "by visibility": [
        {
          "blueprints": 3,
          "visibility": "tenant"
        }
      ],
      "tenant_name": "default_tenant"
    }
  ],
  "metadata": {
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 3
    }
  }
}

GET "{manager-ip}/api/v3.1/summary/blueprints?_target_field={target-field}&_sub_field={optional sub-field}"

Get a summary of blueprints based on the target field and optional sub-field.

Response

Field	Type	Description
`items`	list	A list of blueprint summaries based on the target field and optional sub-field.

Summarize Deployments

Valid fields: blueprint_id, tenant_name, visibility

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/deployments?_target_field=blueprint_id"

With sub-field

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/deployments?_target_field=tenant_name&_sub_field=blueprint_id&_all_tenants=true"

# Using CloudifyClient
summaries = client.summary.deployments.get(_target_field='blueprint_id')
for summary in summaries:
    print(summary)

# Using request
url = 'http://<manager-ip>/api/v3.1/summary/deployments'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_target_field': 'blueprint_id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "blueprint_id": "s",
      "deployments": 5
    },
    {
      "blueprint_id": "sga",
      "deployments": 2
    }
  ],
  "metadata": {
    "pagination": {
      "size": 1000,
      "total": 2,
      "offset": 0
    }
  }
}

With sub-field

{
  "items": [
    {
      "by blueprint_id": [
        {
          "blueprint_id": "s",
          "deployments": 1
        },
        {
          "blueprint_id": "sg",
          "deployments": 3
        },
        {
          "blueprint_id": "sga",
          "deployments": 5
        }
      ],
      "deployments": 9,
      "tenant_name": "test1"
    },
    {
      "by blueprint_id": [
        {
          "blueprint_id": "sga",
          "deployments": 1
        },
        {
          "blueprint_id": "s",
          "deployments": 3
        },
        {
          "blueprint_id": "sg",
          "deployments": 5
        }
      ],
      "deployments": 9,
      "tenant_name": "test2"
    },
    {
      "by blueprint_id": [
        {
          "blueprint_id": "sga",
          "deployments": 3
        },
        {
          "blueprint_id": "s",
          "deployments": 5
        },
        {
          "blueprint_id": "sg",
          "deployments": 1
        }
      ],
      "deployments": 9,
      "tenant_name": "default_tenant"
    }
  ],
  "metadata": {
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 9
    }
  }
}

GET "{manager-ip}/api/v3.1/summary/deployments?_target_field={target-field}&_sub_field={optional sub-field}"

Get a summary of deployments based on the target field and optional sub-field.

Response

Field	Type	Description
`items`	list	A list of deployment summaries based on the target field and optional sub-field.

Summarize Executions

Valid fields: status, blueprint_id, deployment_id, workflow_id, tenant_name, visibility

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/executions?_target_field=blueprint_id"

With sub-field

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/executions?_target_field=tenant_name&_sub_field=workflow_id&_all_tenants=true"

# Using CloudifyClient
summaries = client.summary.executions.get(_target_field='blueprint_id')
for summary in summaries:
    print(summary)

# Using request
url = 'http://<manager-ip>/api/v3.1/summary/executions'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_target_field': 'blueprint_id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "blueprint_id": "sga",
      "executions": 6
    },
    {
      "blueprint_id": "s",
      "executions": 10
    },
    {
      "blueprint_id": "sg",
      "executions": 2
    }
  ],
  "metadata": {
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 3
    }
  }
}

With sub-field

{
  "items": [
    {
      "by workflow_id": [
        {
          "executions": 9,
          "workflow_id": "create_deployment_environment"
        },
        {
          "executions": 1,
          "workflow_id": "create_snapshot"
        },
        {
          "executions": 9,
          "workflow_id": "install"
        },
        {
          "executions": 1,
          "workflow_id": "restore_snapshot"
        }
      ],
      "executions": 20,
      "tenant_name": "default_tenant"
    }
  ],
  "metadata": {
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 4
    }
  }
}

GET "{manager-ip}/api/v3.1/summary/executions?_target_field={target-field}&_sub_field={optional sub-field}"

Get a summary of executions based on the target field and optional sub-field.

Response

Field	Type	Description
`items`	list	A list of execution summaries based on the target field and optional sub-field.

Summarize Node Instances

Valid fields: deployment_id, node_id, host_id, state, tenant_name, visibility

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/node_instances?_target_field=deployment_id"

With sub-field

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/node_instances?_target_field=node_id&_sub_field=state"

# Using CloudifyClient
summaries = client.summary.node_instances.get(_target_field='deployment_id')
for summary in summaries:
    print(summary)

# Using request
url = 'http://<manager-ip>/api/v3.1/summary/node_instances'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_target_field': 'deployment_id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "deployment_id": "s",
      "node_instances": 2
    },
    {
      "deployment_id": "s2",
      "node_instances": 2
    },
    {
      "deployment_id": "s3",
      "node_instances": 2
    },
    {
      "deployment_id": "s4",
      "node_instances": 2
    },
    {
      "deployment_id": "s5",
      "node_instances": 2
    },
    {
      "deployment_id": "sga",
      "node_instances": 51
    },
    {
      "deployment_id": "sga2",
      "node_instances": 51
    }
  ],
  "metadata": {
    "pagination": {
      "total": 7,
      "offset": 0,
      "size": 1000
    }
  }
}

With sub-field

{
  "items": [
    {
      "by state": [
        {
          "node_instances": 42,
          "state": "started"
        }
      ],
      "node_id": "fakeapp1",
      "node_instances": 42
    },
    {
      "by state": [
        {
          "node_instances": 84,
          "state": "started"
        }
      ],
      "node_id": "fakevm2",
      "node_instances": 84
    },
    {
      "by state": [
        {
          "node_instances": 3,
          "state": "started"
        }
      ],
      "node_id": "fakeplatformthing1",
      "node_instances": 3
    },
    {
      "by state": [
        {
          "node_instances": 66,
          "state": "started"
        }
      ],
      "node_id": "fakevm",
      "node_instances": 66
    },
    {
      "by state": [
        {
          "node_instances": 3,
          "state": "started"
        }
      ],
      "node_id": "fakeappconfig1",
      "node_instances": 3
    }
  ],
  "metadata": {
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 5
    }
  }
}

GET "{manager-ip}/api/v3.1/summary/node_instances?_target_field={target-field}&_sub_field={optional sub-field}"

Get a summary of node instances based on the target field and optional sub-field.

Response

Field	Type	Description
`items`	list	A list of node instance summaries based on the target field and optional sub-field.

Summarize Nodes

Valid fields: deployment_id, tenant_name, visibility

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/nodes?_target_field=deployment_id"

With sub-field

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/summary/nodes?_target_field=tenant_name&_sub_field=deployment_id&_all_tenants=true"

# Using CloudifyClient
summaries = client.summary.nodes.get(_target_field='deployment_id')
for summary in summaries:
    print(summary)

# Using request
url = 'http://<manager-ip>/api/v3.1/summary/nodes'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_target_field': 'deployment_id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {"deployment_id": "s", "nodes": 1},
    {"deployment_id": "s2", "nodes": 1},
    {"deployment_id": "s3", "nodes": 1},
    {"deployment_id": "s4", "nodes": 1},
    {"deployment_id": "s5", "nodes": 1},
    {"deployment_id": "sga", "nodes": 5},
    {"deployment_id": "sga2", "nodes": 5}
  ],
  "metadata": {
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 7
    }
  }
}

With sub-field

{
    "items": [
        {
            "by deployment_id": [
                {
                    "deployment_id": "s1",
                    "nodes": 1
                },
                {
                    "deployment_id": "sg1",
                    "nodes": 2
                },
                {
                    "deployment_id": "sg2",
                    "nodes": 2
                },
                {
                    "deployment_id": "sg3",
                    "nodes": 2
                },
                {
                    "deployment_id": "sga1",
                    "nodes": 5
                },
                {
                    "deployment_id": "sga2",
                    "nodes": 5
                },
                {
                    "deployment_id": "sga3",
                    "nodes": 5
                },
                {
                    "deployment_id": "sga4",
                    "nodes": 5
                },
                {
                    "deployment_id": "sga5",
                    "nodes": 5
                }
            ],
            "nodes": 32,
            "tenant_name": "test1"
        },
        {
            "by deployment_id": [
                {
                    "deployment_id": "s1",
                    "nodes": 1
                },
                {
                    "deployment_id": "s2",
                    "nodes": 1
                },
                {
                    "deployment_id": "s3",
                    "nodes": 1
                },
                {
                    "deployment_id": "sg1",
                    "nodes": 2
                },
                {
                    "deployment_id": "sg2",
                    "nodes": 2
                },
                {
                    "deployment_id": "sg3",
                    "nodes": 2
                },
                {
                    "deployment_id": "sg4",
                    "nodes": 2
                },
                {
                    "deployment_id": "sg5",
                    "nodes": 2
                },
                {
                    "deployment_id": "sga1",
                    "nodes": 5
                }
            ],
            "nodes": 18,
            "tenant_name": "test2"
        },
        {
            "by deployment_id": [
                {
                    "deployment_id": "s1",
                    "nodes": 1
                },
                {
                    "deployment_id": "s2",
                    "nodes": 1
                },
                {
                    "deployment_id": "s3",
                    "nodes": 1
                },
                {
                    "deployment_id": "s4",
                    "nodes": 1
                },
                {
                    "deployment_id": "s5",
                    "nodes": 1
                },
                {
                    "deployment_id": "sg1",
                    "nodes": 2
                },
                {
                    "deployment_id": "sga1",
                    "nodes": 5
                },
                {
                    "deployment_id": "sga2",
                    "nodes": 5
                },
                {
                    "deployment_id": "sga3",
                    "nodes": 5
                }
            ],
            "nodes": 22,
            "tenant_name": "default_tenant"
        }
    ],
    "metadata": {
        "pagination": {
            "offset": 0,
            "size": 1000,
            "total": 27
        }
    }
}

GET "{manager-ip}/api/v3.1/summary/nodes?_target_field={target-field}&_sub_field={optional sub-field}"

Get a summary of nodes based on the target field and optional sub-field.

Response

Field	Type	Description
`items`	list	A list of node summaries based on the target field and optional sub-field.

Tasks graphs

The TasksGraph Resource

# Include this code when using the Cloudify Python client-
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager-ip>',
        username='<manager-username>',
        password='<manager-password>')

Represents a stored tasks graph, created as part of an execution.

Attributes:

Attribute	Type	Description
`id`	string	Unique identifier of this tasks graph
`execution_id`	string	ID of the execution that created this tasks graph
`name`	string	A label for this tasks graph, so that multiple graphs for a single execution can be distinguished

List tasks graphs

Request Example

$ curl -u user:password "http://<manager-ip>/api/v3.1/tasks_graphs?execution_id=123&name=abc"

client.tasks_graphs.list(execution_id, name)

Response Example

{
    "id": "aaabbbccc",
    "execution_id": "123",
    "name": "abc"
}

GET "{manager-ip}/api/v3.1/tasks_graphs"

Lists tasks graphs. This is useful when filtering by execution ID.

Query Parameters

Property	Type	Description
`execution_id`	string	Filter tasks graphs for this execution
`name`	string	Filter tasks graphs with this name

Create tasks graph

Request Example

$ curl -u user:password -X POST \
    -d '{"name": "abc", "execution_id": "123"}' \
    "http://<manager-ip>/api/v3.1/tasks_graphs"

client.tasks_graphs.create(execution_id, name, operations=operations)

Response Example

{
    "id": "aaabbbccc",
    "execution_id": "123",
    "name": "abc"
}

POST "{manager-ip}/api/v3.1/tasks_graphs"

Creates a tasks graph. This can optionally also create a tasks graph with operations in it, where operations is a list of dicts containing a representation of each operation, as returned by its dump method. Operations can also be created one-by-one, however this method should be used instead for performance improvement.

Request Body

Property	Type	Description
`execution_id`	string	ID of the current execution
`name`	string	An additional label for the tasks graph to distinguish multiple graphs for the same execution
`operations`	list	Serialized operations to create in this tasks graph

Tenants

The Tenant Resource

The Tenant resource is a logical component that represents a closed environment with its own resources.

Attributes:

Attribute	Type	Description
`id`	integer	Auto increment, unique identifier for the tenant.
`name`	string	The tenant’s name.

List Tenants

Request Example - Get user and user group counts

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/tenants"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.list()

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example - Get user and user group counts

{
  "items": [
    {
      "name": "default_tenant",
      "groups": 0,
      "users": 1
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 0
    }
  }
}

Request Example - Get user and user group details

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/tenants?_get_data=true"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.list(_get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example - Get user and user group details

{
  "items": [
    {
      "name": "default_tenant",
      "groups": {},
      "users": {
        "admin": {
          "tenant-role": "user",
          "roles": [
            "user"
          ]
        }
      }
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager_ip}/api/v3.1/tenants"

List all tenants.

Response

Field	Type	Description
`items`	list	A list of `Tenant` resources.

Get Tenant

Request Example - Get user and user group counts

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/tenants/{tenant_name}"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.get('<tenant_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/<tenant_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example - Get user and user group counts

{
    "name": "<tenant_name>",
    "groups": 0,
    "users": 1
}

Request Example - Get user and user group details

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/tenants/{tenant_name}?_get_data=true"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.get('<tenant_name>', _get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/<tenant_name>?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example - Get user and user group counts

{
  "name": "<tenant_name>",
  "groups": {},
  "users": {
    "admin": {
      "tenant-role": "user",
      "roles": [
        "user"
      ]
    }
  }
}

GET "{manager_ip}/api/v3.1/tenants?name={tenant_name}"

Retrieves a specific tenant.

URI Parameters

tenant_name: The name of the tenant to retrieve.

Response

A Tenant resource.

Create Tenant

Request Example - Get user and user group counts

$ curl -X POST \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/tenants/<new_tenant_name>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.create('<new_tenant_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/<new_tenant_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example - Get user and user group counts

{
    "name": "<new_tenant_name>",
    "groups": 0,
    "users": 0
}

Request Example - Get user and user group details

$ curl -X POST \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/tenants/<new_tenant_name>?_get_data=true"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.create('<new_tenant_name>', _get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/<new_tenant_name>?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
)
response.json()

Response Example - Get user and user group details

{
    "name": "<new_tenant_name>",
    "groups": {},
    "users": {}
}

POST "{manager_ip}/api/v3.1/tenants/{new_tenant_name}"

Creates a tenant.

URI Parameters

new_tenant_name: The name of the tenant to create.

Response

A Tenant resource.

Delete Tenant

Request Example

$ curl -X DELETE \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/tenants/<tenant_name_to_delete>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.delete('<tenant_name_to_delete>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/<tenant_name-to-delete>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
requests.delete(
    url,
    auth=auth,
    headers=headers,
)

DELETE "{manager_ip}/api/v3.1/tenants/{tenant_name_to_delete}"

Delete a tenant.

URI Parameters

tenant_name_to_delete: The name of the tenant to delete.

Response

No content - HTTP code 204.

Add User to Tenant

Request Example - Get user and user group counts

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": "<username_to_add>", "tenant_name": "<tenant_name>", "role": "<role_name>"}' \
    "http://<manager_ip>/api/v3.1/tenants/users"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.add_user(
    '<username_to_add>',
    '<tenant_name>',
    '<role_name>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/users'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'username': '<username_to_add>',
    'role': '<role_name>',
}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group counts

{
    "name": "<tenant_name>",
    "groups": 0,
    "users": 1
}

Request Example - Get user and user group details

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": <username_to_add>, "tenant_name": <tenant_name>, "role": <role_name>}' \
    "http://<manager_ip>/api/v3.1/tenants/users?_get_data=true"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.add_user(
    '<username_to_add>',
    '<tenant_name>',
    '<role_name>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/users?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'username': '<username_to_add>',
    'role': '<role_name>',
}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
    json=payload,
    _get_data=True,
)
response.json()

Response Example - Get user and user group details

{
  "name": "<tenant_name>",
  "groups": {},
  "users": {
    "<username_to_add>": {
      "tenant-role": "<role_name>",
      "roles": [
        "<role_name>"
      ]
    }
  }
}

PUT "{manager_ip}/api/v3.1/tenants/users"

Add a user to a tenant.

Request Body

Property	Type	Description
`username`	string	The user name to add to the tenant.
`tenant_name`	string	The name of the tenant to which to add the user.
`role`	string	The name of the role assigned to the user in the tenant. If not passed the default tenant role will be used.

Valid tenant roles are:

manager - User that can manage tenants
operations - User that can deploy and execute workflows, but cannot manage blueprints or plugins
user - Regular user, can perform actions on tenants resources
viewer - User that can only view tenant resources

Response

A Tenant resource.

Update User in Tenant

Request Example - Get user and user group counts

$ curl -X PATCH \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": "<username_to_update>", "tenant_name": "<tenant_name>", "role": "<role_name>"}' \
     "http://<manager_ip>/api/v3.1/tenants/users"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.update_user(
    '<username_to_update>',
    '<tenant_name>',
    '<role_name>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/users'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'username': '<username_to_update>',
    'role': '<role_name>',
}
response = requests.patch(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group counts

{
    "name": "tenant_name",
    "groups": 0,
    "users": 1
}

Request Example - Get user and user group details

$ curl -X PATCH \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": <username_to_update>, "tenant_name": <tenant_name>, "role": <role_name>}' \
     "http://<manager_ip>/api/v3.1/tenants/users?_get_data=true"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.update_user(
    '<username_to_update>',
    '<tenant_name>',
    '<role_name>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/users?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'username': '<username_to_update>',
    'role': '<role_name>',
}
response = requests.patch(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group details

{
  "name": "<tenant_name>",
  "groups": {},
  "users": {
    "my-user": {
      "tenant-role": "<role_name>",
      "roles": [
        "<role_name>"
      ]
    }
  }
}

PATCH "{manager_ip}/api/v3.1/tenants/users"

Update a user in a tenant.

Request Body

Property	Type	Description
`username`	string	The user name to remove from the tenant.
`tenant_name`	string	The tenant name to add the user into it.
`role`	string	The name of the role assigned to the user in the tenant. If not passed the default tenant role will be used.

Valid tenant roles are:

manager - User that can manage tenants
operations - User that can deploy and execute workflows, but cannot manage blueprints or plugins
user - Regular user, can perform actions on tenants resources
viewer - User that can only view tenant resources

Response

A Tenant resource.

Remove User from Tenant

Request Example

$ curl -X DELETE \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": "<username_to_remove>", "tenant_name": "<tenant_name>"}' \
     "http://<manager_ip>/api/v3.1/tenants/users"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.remove_user('<username_to_remove>', '<tenant_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/users'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'username': '<username_to_remove>',
}
requests.delete(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.remove_user(
    '<username_to_remove>',
    '<tenant_name>'
)

DELETE "{manager_ip}/api/v3.1/tenants/users"

Delete a user from a tenant.

Request Body

Property	Type	Description
`username`	string	The user name to remove from the tenant.
`tenant_name`	string	The tenant name to add the user into it.

Response

No content - HTTP code 204.

Add User-Group to Tenant

Request Example - Get user and user group counts

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"group_name": "<group_name>", "tenant_name": "<tenant_name>", "role": "<role_name>"}' \
    "http://<manager_ip>/api/v3.1/tenants/user-groups"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.add_user_group(
    '<group_name>',
    '<tenant_name>',
    '<role_name>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/user-groups'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'group_name': '<group_name>',
    'role': '<role_name>',
}
response = requests.put(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group counts

{
    "name": "tenant_name",
    "groups": 1,
    "users": 0
}

Request Example - Get user and user group details

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"group_name": "<group_name>", "tenant_name": "<tenant_name>", "role": "<role_name>"}' \
    "http://<manager_ip>/api/v3.1/tenants/user-groups?_get_data=true"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.add_user_group(
    '<group_name>',
    '<tenant_name>',
    '<role_name>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/user-groups?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'group_name': '<group_name>',
    'role': '<role_name>',
}
response = requests.put(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group details

{
  "name": "<tenant_name>",
  "groups": {
    "<group_name>": "<role_name>"
  },
  "users": {}
}

PUT "{manager_ip}/api/v3.1/tenants/user-groups"

Add a user group to a tenant.

Request Body

Property	Type	Description
`group_name`	string	The name of the user group to add to the tenant.
`tenant_name`	string	The name of the tenant to which to add the user group.
`role`	string	The name of the role assigned to the users members of the group. If not passed the default tenant role will be used.

Valid tenant roles are:

manager - User that can manage tenants
operations - User that can deploy and execute workflows, but cannot manage blueprints or plugins
user - Regular user, can perform actions on tenants resources
viewer - User that can only view tenant resources

Response

A Tenant resource.

Update User-Group in Tenant

Request Example - Get user and user group counts

$ curl -X PATCH \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"tenant_name": "<tenant_name>", "group_name": "<group_name>", "role": "<role_name>"}' \
     "http://<manager_ip>/api/v3.1/tenants/user-groups"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.update_user_group(
    '<group_name>',
    '<tenant_name>',
    '<role_name>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/user-groups'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'group_name': '<group_name>',
    'role': '<role_name>',
}
response = requests.patch(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group counts

{
    "name": "tenant_name",
    "groups": 1,
    "users": 0
}

Request Example - Get user and user group details

$ curl -X PATCH \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"tenant_name": "<tenant_name>", "group_name": "<group_name>", "role": "<role_name>"}' \
     "http://<manager_ip>/api/v3.1/tenants/user-groups?_get_data=true"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.update_user_group(
    '<group_name>',
    '<tenant_name>',
    '<role_name>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/user-groups?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'group_name': '<group_name>',
    'role': '<role_name>',
}
response = requests.patch(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)
response.json()

Response Example - Get user and user group details

{
  "name": "<tenant_name>",
  "groups": {
    "<group_name>": "<role_name>"
  },
  "users": {}
}

PATCH "{manager_ip}/api/v3.1/tenants/user-groups"

Update a user group in a tenant.

Request Body

Property	Type	Description
`group_name`	string	The group name to update in the tenant.
`tenant_name`	string	The tenant name to which the user group is assigned.
`role`	string	The name of the role assigned to the user in the tenant. If not passed the default tenant role will be used.

Valid tenant roles are:

manager - User that can manage tenants
operations - User that can deploy and execute workflows, but cannot manage blueprints or plugins
user - Regular user, can perform actions on tenants resources
viewer - User that can only view tenant resources

Response

A Tenant resource.

Remove User-Group from Tenant

Request Example

$ curl -X DELETE \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"group_name": "<group_name>", "tenant_name": "<tenant_name>"}' \
    "http://<manager_ip>/api/v3.1/tenants/user-groups"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.remove_user_group('<group_name>', '<tenant_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/tenants/user-groups'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'tenant_name': '<tenant_name>',
    'group_name': '<group_name>',
}
requests.delete(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.tenants.remove_user_group(
    '<group_name>',
    '<tenant_name>'
)

DELETE "{manager_ip}/api/v3.1/tenants/user-groups"

Delete a user group from a tenant.

Request Body

Property	Type	Description
`group_name`	string	The name of the user group to delete from the tenant.
`tenant_name`	string	The name of the tenant from which to delete the user group.

Response

No content - HTTP code 204.

Tokens

The Tokens Resource

Attributes:

Attribute	Type	Description
`role`	string	The role associated with the token (`admin` or `user`)
`value`	string	The value of the token

Get Token

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3.1/tokens"

# Using CloudifyClient
client.tokens.get()

# Using requests
url = 'http://<manager-ip>/api/v3.1/tokens'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example

{
  "role": "admin",
  "value": "WyIwIiwiZjRmNTUzMWRmYmFmZGZmNTlkNTkyZGY2MjMxYzkyNTEiXQ.C_YU9Q.IhQMlnXZIaCtWUUHH_CzHP4-Bg4"
}

GET "{manager-ip}/api/v3.1/tokens"

Gets a token.

Response

A Token resource.

User Groups

The User Group Resource

The User Group is a group of users.

Attributes:

Attribute	Type	Description
`id`	integer	Auto increment, unique identifier for the tenant.
`ldap_dn`	string	The distinguished name of corresponding LDAP group (if using LDAP).
`name`	string	The name of the user group.

List User Groups

Request Example - Get tenants and users counts

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<password> \
    "http://<manager_ip>/api/v3.1/user-groups"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.list()

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and users counts

{
  "items": [
    {
      "ldap_dn": "ldap_group_dn",
      "tenants": 0,
      "name": "group_name",
      "users": 0
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 0
    }
  }
}

Request Example - Get tenants and users details

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<password> \
    "http://<manager_ip>/api/v3.1/user-groups?_get_data=true"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.list(_get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and users details

{
  "items": [
    {
      "ldap_dn": "ldap_group_dn",
      "tenants": {},
      "name": "group_name",
      "users": []
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager_ip}/api/v3.1/user-groups"

List all user groups.

Response

Field	Type	Description
`items`	list	A list of `Group` resources.

Get User Group

Request Example - Get tenants and users counts

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/user-groups/<group_name>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.get('<group_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups/<group_name>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and users counts

{
  "ldap_dn": "ldap_group_dn",
  "tenants": 0,
  "name": "<group_name>",
  "users": 0
}

Request Example - Get tenants and users details

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/user-groups/<group_name>?_get_data=true"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.get('<group_name>', _get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups/<group_name>?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and users details

{
  "ldap_dn": "ldap_group_dn",
  "tenants": {},
  "name": "<group_name>",
  "users": []
}

GET "{manager_ip}/api/v3.1/user-groups/{group_name}"

Retrieves a specific group.

URI Parameters

group_name: The name of the group to retrieve.

Response

A Group resource.

Create User Group

Request Example - Get tenants and users counts

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"group_name": <group_name>, "ldap_group_dn": <ldap_group_dn>}' \
    "http://<manager_ip>/api/v3.1/user-groups"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.create(
    group_name='<group_name>',
    ldap_group_dn='<ldap_group_dn>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'group_name': '<group_name>',
    'ldap_group_dn': '<ldap_group_dn>',
}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and users counts

{
  "ldap_dn": "<ldap_group_dn>",
  "tenants": 0,
  "name": "<group_name>",
  "users": 0
}

Request Example - Get tenants and users details

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"group_name": <group_name>, "ldap_group_dn": <ldap_group_dn>}' \
    "http://<manager_ip>/api/v3.1/user-groups?_get_data=true"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.create(
    group_name='<group_name>',
    ldap_group_dn='<ldap_group_dn>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'group_name': '<group_name>',
    'ldap_group_dn': '<ldap_group_dn>',
}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and users details

{
  "ldap_dn": "<ldap_group_dn>",
  "tenants": {},
  "name": "<group_name>",
  "users": []
}

POST -d '{"group_name": <group-name>, "ldap_group_dn": <ldap_group_dn>, "role": <group-system-role>}' "{manager-ip}/api/v3.1/user-groups"

Creates a new user group.

Request Body

Property	Type	Description
`group_name`	string	The group name.
`ldap_group_dn`	string	Optional parameter, The distinguishing name of the corresponding LDAP group, if appropriate.
`role`	string	Optional parameter, The name of the system role for the group’s users (default: “default”).

Response

A Group resource.

Delete User Group

Request Example

$ curl -X DELETE \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/user-groups/<user_group_name_to_delete>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.delete('<user_group_name_to_delete>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups/<user_group_name_to_delete>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
requests.delete(
    url,
    auth=auth,
    headers=headers,
)

DELETE "{manager_ip}/api/v3.1/user-groups/{user_group_name_to_delete}"

Deletes a user group.

URI Parameters

user_group_name_to_delete: The name of the user group to delete.

Response

No content - HTTP code 204.

Add User to User Group

Request Example - Get tenants and users counts

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": <username_to_add>, "group_name": <group_name>}' \
    "http://<manager_ip>/api/v3.1/user-groups/users"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.add_user('<username_to_add>', '<group_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups/users'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'username': '<username_to_add>'
    'group_name': '<group_name>',
}
response = requests.put(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and users counts

{
  "ldap_dn": "ldap_group_dn",
  "tenants": 0,
  "name": "<group_name>",
  "users": 1
}

Request Example - Get tenants and users details

$ curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": <username_to_add>, "group_name": <group_name>}' \
    "http://<manager_ip>/api/v3.1/user-groups/users?_get_data=true"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.add_user(
    '<username_to_add>',
    '<group_name>',
    _get_data=True,
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups/users?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'username': '<username_to_add>'
    'group_name': '<group_name>',
}
response = requests.put(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Get tenants and users details

{
  "ldap_dn": "ldap_group_dn",
  "tenants": {},
  "name": "<group_name>",
  "users": [
    "<username_to_add>"
  ]
}

PUT "{manager_ip}/api/v3.1/user-groups/users"

Add a user to user group.

Request Body

Property	Type	Description
`username`	string	The name of the user to add to the group.
`group_name`	string	The name of the group to which to add the user.

Response

A Group resource.

Remove User from User Group

Request Example

$ curl -X DELETE \
    -H "Content-Type: application/json" \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": <username_to_remove>, "group_name": <group_name>}' \
    "http://<manager_ip>/api/v3.1/user-groups/users"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.user_groups.remove_user('<username_to_remove>', '<group_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/user-groups/users'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'username': '<username_to_remove>'
    'group_name': '<group_name>',
}
requests.delete(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

DELETE "{manager-ip}/api/v3.1/user-groups/users"

Delete a user from a user group.

Request Body

Property	Type	Description
`username`	string	The name of the user to remove from the group.
`group_name`	string	The name of the group from which to remove the user.

Response

No content - HTTP code 204.

Users

The User Resource

Attributes:

Attribute	Type	Description
`active`	boolean	Whether the user’s status is active or suspended.
`username`	string	The username.
`first_login_at`	UTCDateTime	Date of first request performed by the user.
`last_login_at`	UTCDateTime	Date of last request performed by the user.
`is_locked`	boolean	Whether the user is temporarily locked out (due to numerous failed login attempts).
`tenant_roles`	set	The roles of the tenant user is associated with.
`role`	string	The role of the user (the first one in case there are many).
`groups`	list	The groups the user belongs to
`tenants`	object	Dictionary of tenants the user is associated with.
`group_system_roles`	object	Dictionary of lists of groups the user is associated with, per the role.
`show_getting_started`	boolean	Whether the user will be displayed the “Getting started” modal upon logging in.

List Users

Request Example - List users (tenants and user groups count)

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/users"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.list()

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - List users (tenants and user groups count)

{
  "items": [
    {
      "active": true,
      "first_login_at": "2021-12-20T16:17:13.673Z",
      "group_system_roles": {},
      "groups": 0,
      "is_locked": false,
      "last_login_at": "2021-12-21T13:05:47.533Z",
      "role": "sys_admin",
      "show_getting_started": false,
      "tenant_roles": null,
      "tenants": 1,
      "username": "admin"
    }
  ],
  "metadata": {
    "filtered": null,
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 1
    }
  }
}

Request Example - List users (tenants and user groups details)

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/users?_get_data=true"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.list(_get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get tenants and user groups details

{
  "items": [
    {
      "active": true,
      "first_login_at": "2021-12-20T16:17:13.673Z",
      "group_system_roles": {},
      "groups": [],
      "is_locked": false,
      "last_login_at": "2021-12-21T13:29:07.079Z",
      "password_hash": null,
      "role": "sys_admin",
      "show_getting_started": false,
      "tenant_roles": {
        "direct": {
          "default_tenant": "user"
        },
        "groups": {}
      },
      "tenants": {
        "default_tenant": {
          "roles": [
            "user"
          ],
          "tenant-role": "user"
        }
      },
      "username": "admin"
    }
  ],
  "metadata": {
    "filtered": null,
    "pagination": {
      "offset": 0,
      "size": 1000,
      "total": 1
    }
  }
}

GET "{manager_ip}/api/v3.1/users"

List all users.

Response

Field	Type	Description
`items`	list	A list of `User` resources.

Get User

Request Example - Get user

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/users/<username>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.get(<username>)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users/<username>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get user

{
    "active": true,
    "first_login_at": "2021-12-20T16:17:13.673Z",
    "group_system_roles": {},
    "groups": 0,
    "is_locked": false,
    "last_login_at": "2021-12-21T13:32:06.194Z",
    "password_hash": null,
    "role": "sys_admin",
    "show_getting_started": false,
    "tenant_roles": null,
    "tenants": 1,
    "username": "admin"
}

Request Example - Get user

$ curl -X GET \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/users/<username>?_get_data=true"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.get('<username>', _get_data=True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users/<username>?_get_data=true'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
response = requests.get(
    url,
    auth=auth,
    headers=headers,
)

Response Example - Get user

{
  "active": true,
  "first_login_at": "2021-12-20T16:17:13.673Z",
  "group_system_roles": {},
  "groups": [],
  "is_locked": false,
  "last_login_at": "2021-12-21T15:48:25.067Z",
  "password_hash": null,
  "role": "sys_admin",
  "show_getting_started": false,
  "tenant_roles": {
    "direct": {
      "default_tenant": "user"
    },
    "groups": {}
  },
  "tenants": {
    "default_tenant": {
      "roles": [
        "user"
      ],
      "tenant-role": "user"
    }
  },
  "username": "admin"
}

GET "{manager_ip}/api/v3.1/users/{username}"

Retrieves a specific user.

URI Parameters

username: The name of the user to retrieve.

Response

A User resource.

Create User

Request Example - Create user

$ curl -X PUT \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"username": <new_username>, "password": <password>, "role": <role_name>}'
    "http://{manager_ip}/api/v3.1/users"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.create(
    '<new_username>',
    '<password>',
    '<role_name>',
)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {
    'username': '<new_username>',
    'password': '<password>',
    'role': '<role_name>',
}
response = requests.put(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Create user

{
  "active": true,
  "first_login_at": "2021-12-20t16:17:13.673z",
  "group_system_roles": {},
  "groups": 0,
  "is_locked": false,
  "last_login_at": "2021-12-21t13:32:06.194z",
  "password_hash": null,
  "role": "sys_admin",
  "show_getting_started": false,
  "tenant_roles": null,
  "tenants": 1,
  "username": "admin"
}

Request Body

Property	Type	Description
`username`	string	The username.
`password`	string	The user password.
`role`	string	The user role. One of the following: `sys_admin`, `default`.

Valid system roles are:

sys_admin - User that can manage Conductor
default - User exists, but has no special permissions

Response

A User resource.

Delete User

Request Example

$ curl -X DELETE \
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    "http://<manager_ip>/api/v3.1/users/<username_to_delete>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.delete('<username_to_delete>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users/<username_to_delete>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
requests.delete(
    url,
    auth=auth,
    headers=headers,
)

DELETE "{manager_ip}/api/v3.1/tenants/{username_to_delete}"

Delete a user.

URI Parameters

username_to_delete: The name of the user to delete.

Response

No content - HTTP code 204.

Set user password

Request Example - Set user password

$ curl -X POST \
    -H "Content-Type: application/json"
    -H "Tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"password": <new_password>}' \
    "http://<manager_ip>/api/v3.1/users/<username>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.set_password('<username>', '<new_password>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users/<username>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {'password': '<new_password>'}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Set user password

{
  "active": true,
  "first_login_at": "2021-12-20T16:17:13.673Z",
  "group_system_roles": {},
  "groups": 0,
  "is_locked": false,
  "last_login_at": "2021-12-21T13:32:06.194Z",
  "password_hash": null,
  "role": "sys_admin",
  "show_getting_started": false,
  "tenant_roles": null,
  "tenants": 1,
  "username": "admin"
}

Specify a password.

URI Parameters

username: The name of the user whose password is to be changed.

Request Body

Property	Type	Description
`password`	string	The new user password.

Response

A User resource.

Set user role

Request Example - Set user role

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"role": <user_role>}' \
    "http://<manager_ip>/api/v3.1/users/<username>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.set_role('<username>', '<new_role_name>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users/<username>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {'role': '<new_role_name>'}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Set user role

{
  "active": true,
  "first_login_at": "2021-12-20T16:17:13.673Z",
  "group_system_roles": {},
  "groups": 0,
  "is_locked": false,
  "last_login_at": "2021-12-21T13:32:06.194Z",
  "password_hash": null,
  "role": "sys_admin",
  "show_getting_started": false,
  "tenant_roles": null,
  "tenants": 1,
  "username": "admin"
}

POST -d '{"role": <new_role_name>}' "{manager_ip}/api/v3.1/users/{username}"

Set a new system role for the user.

URI Parameters

username: The name of the user whose role is to be set.

Request Body

Property	Type	Description
`role`	string	The user role. One of the following: `sys_admin`, `default`.

Valid system roles are:

sys_admin - User that can manage Conductor
default - User exists, but has no special permissions

Response

A User resource.

Set show getting started

Request Example - Set user show getting started parameter

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "tenant: <manager_tenant>" \
    -u <manager_username>:<manager_password> \
    -d '{"show_getting_started": <true|false>}' \
    "http://<manager_ip>/api/v3.1/users/<username>"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager_ip>',
    username='<manager_username>',
    password='<manager_password>',
    tenant='<manager_tenant>',
)
client.users.set_show_getting_started('<username>', True)

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager_ip>/api/v3.1/users/<username>'
auth = HTTPBasicAuth('<manager_username>', '<manager_password>')
headers = {'Tenant': '<manager_tenant>'}
payload = {'show_getting_started': True}
response = requests.post(
    url,
    auth=auth,
    headers=headers,
    json=payload,
)

Response Example - Set user show getting started parameter

{
  "active": true,
  "first_login_at": "2021-12-20T16:17:13.673Z",
  "group_system_roles": {},
  "groups": 0,
  "is_locked": false,
  "last_login_at": "2021-12-21T13:32:06.194Z",
  "password_hash": null,
  "role": "sys_admin",
  "show_getting_started": true,
  "tenant_roles": null,
  "tenants": 1,
  "username": "admin"
}

POST -d '{"show_getting_started": <true|false>}' "{manager_ip}/api/v3.1/users/{username}"

Set the show getting started parameter for the user.

URI Parameters

username: The name of the user for whom to set the show getting started parameter.

Request Body

Property	Type	Description
`show_getting_started`	bool	Whether to show the Getting Started popup at login.

Response

A User resource.

Workflows

The Workflow Resource

Attributes:

Attribute	Type	Description
`name`	string	The name of the workflow (e.g. `install`, `update`)
`created_at`	datetime	The time when the workflow was created.
`parameters`	object	A dictionary containing definitions of the workflow’s parameters.
`plugin`	string	The name of the plugin containing workflow implementation.
`operation`	string	The name of the system task performed by the workflow.
`is_available`	boolean	Whether or not this workflow is currently available for running

List Workflows

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/workflows?id=<deployment_id>"

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3.1/workflows?deployment_group_id=<deployment_group_id>"

# Using CloudifyClient
workflows = client.workflows.list(id='dep1')
for workflow in workflows:
  print workflow

# Using requests
url = 'http://<manager-ip>/api/v3.1/deployments'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'deployment_group_id': 'g1'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "name": "hello1",
      "created_at": "2021-04-27T06:51:29.541Z",
      "parameters": {},
      "plugin": "cloudify-hello-plugin",
      "operation": "",
      "is_available": true
    },
    {
      "name": "hello2"
      "created_at": "2021-04-27T06:51:29.542Z",
      "parameters": {},
      "plugin": "cloudify-hello-plugin",
      "operation": "",
      "is_available": false
    },
    {
      "name": "hello3"
      "created_at": "2021-04-27T06:51:29.543Z",
      "parameters": {},
      "plugin": "cloudify-hello-plugin",
      "operation": "",
      "is_available": true
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 3
    }
  }
}

GET "{manager-ip}/api/v3.1/workflows"

Lists all of the workflows specified for the deployments selected by the additional parameters. A special parameter _filter_id can be used to describe a deployments filter used to select specific deployments.

Response

Field	Type	Description
`items`	list	A list of `Deployment` resources.