REST API Endpoints

List known nodes in the cluster ¶

GET /v1/state/nodes¶

Some nodes may not be listed if their agents are disconnected from the cluster. IP addresses may be private IP addresses that are not publicly routable.

+ Response JSON Schema

Example: A list of the known nodes in a cluster.

Request

GET /v1/state/nodes
Host: api.example.com
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "uuid": "cf0f0346-17b2-4812-beca-1434997d6c3f",
    "host": "10.0.0.3",
  },
  {
    "uuid": "7ec3c4eb-6b1c-43da-8015-a163f7d15244",
    "host": "10.0.0.4",
  },
]

Response JSON Array of Objects:
	host (string) – (required) Host The IP address of a node in the cluster. uuid (string) – (required) Node The UUID of a node in the cluster.

Lookup a node by its era ¶

GET /v1/state/nodes/by_era/(era)¶

If you are talking to the API from a process on a node then this is the recommended way of figuring out the node UUID. Since eras are reset on reboot, looking up by era means you will never get stale pre-reboot state.

You can discover a node’s era by running the flocker-node-era command-line tool on the relevant node. Make sure you don’t cache this information across reboots!

If the era is unknown you will get a 404 HTTP response. In this case retry until the node UUID is returned.

+ Response JSON Schema

Example: Lookup a node by its era, in this case “56780f44-0499-4153-9352-92344b180021”.

Request

GET /v1/state/nodes/by_era/56780f44-0499-4153-9352-92344b180021
Host: api.example.com
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "cf0f0346-17b2-4812-beca-1434997d6c3f",
}

Response JSON Object:
	uuid (string) – (required) Node The UUID of a node in the cluster.

Get Flocker version ¶

GET /v1/version¶

Get the version of Flocker being run.

+ Response JSON Schema

Example: Retrieve the version of the Flocker cluster.

Request

GET /v1/version HTTP/1.1
Host: api.example.com
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "flocker": "0.4.0"
}

Response JSON Object:
	flocker (string) – (required) Flocker version The software version of Flocker

Get the cluster’s dataset configuration ¶

GET /v1/configuration/datasets¶

Get the cluster’s dataset configuration.

Includes a X-Configuration-Tag header in the response for use with operations that support X-If-Configuration-Matches.

+ Response JSON Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "The output schema for the get_dataset_configuration endpoint.\n",
    "items": {
        "additionalProperties": false,
        "description": "The configuration for a particular dataset.",
        "properties": {
            "dataset_id": {
                "allOf": [
                    {
                        "description": "An opaque identifier, unique across a cluster, identifying a\nparticular dataset or node.  If not specified when creating a dataset, a new\nidentifier will be generated and returned.\n",
                        "maxLength": 36,
                        "minLength": 36,
                        "pattern": "^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-4[A-Fa-f0-9]{3}-[89abAB][A-Fa-f0-9]{3}-[A-Fa-f0-9]{12}$",
                        "title": "Unique identifer",
                        "type": "string"
                    }
                ],
                "description": "An opaque identifier, unique across the cluster, identifying a\nparticular dataset.  If not given, a new identifier will be generated\nand returned.\n",
                "title": "Unique identifier",
                "type": "string"
            },
            "deleted": {
                "description": "If true, this dataset has been deleted and its data is no longer\nguaranteed to exist.\n",
                "title": "Deleted",
                "type": "boolean"
            },
            "maximum_size": {
                "description": "The upper limit on how much data the dataset will be allowed to\nstore, as an integer number of bytes.\n",
                "minimum": 67108864,
                "multipleOf": 1024,
                "title": "Maximum size",
                "type": [
                    "integer",
                    "null"
                ]
            },
            "metadata": {
                "additionalProperties": false,
                "description": "Additional key/value data describing the dataset.  These items are\nnot interpreted by Flocker.  If not given, no metadata will be\nassociated with the new dataset.\n",
                "maxProperties": 16,
                "patternProperties": {
                    "^.{1,256}$": {
                        "maxLength": 256,
                        "type": "string"
                    }
                },
                "title": "Data about a dataset",
                "type": "object"
            },
            "primary": {
                "allOf": [
                    {
                        "description": "An opaque identifier, unique across a cluster, identifying a\nparticular dataset or node.  If not specified when creating a dataset, a new\nidentifier will be generated and returned.\n",
                        "maxLength": 36,
                        "minLength": 36,
                        "pattern": "^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-4[A-Fa-f0-9]{3}-[89abAB][A-Fa-f0-9]{3}-[A-Fa-f0-9]{12}$",
                        "title": "Unique identifer",
                        "type": "string"
                    }
                ],
                "description": "The UUID of the node which will be given the primary manifestation\nof the newly created dataset.\n",
                "title": "Primary manifestation (node UUID)",
                "type": "string"
            }
        },
        "title": "Dataset Configuration",
        "type": "object"
    },
    "type": "array"
}

Example: Get a list of all datasets that have been configured for a deployment. These datasets may or may not actually exist on the cluster.

Request

GET /v1/configuration/datasets HTTP/1.1
Host: api.example.com
Content-Type: application/json

Response

HTTP/1.0 200 OK
Content-Type: application/json

[
  {"dataset_id": "a5f75af7-3fb9-4c1a-81ce-efeeb9f2c788", "primary": "cf0f0346-17b2-4812-beca-1434997d6c3f", "metadata": {}, "deleted": false},
  {"dataset_id": "886ed03a-5606-453a-94a9-a1cbaf35164c", "primary": "cf0f0346-17b2-4812-beca-1434997d6c3f", "metadata": {"name": "demo", "owner": "alice"}, "deleted": false}
]

Response JSON Array of Objects:

Response JSON Array of Objects:
	dataset_id (string) – Unique identifier An opaque identifier, unique across the cluster, identifying a particular dataset. If not given, a new identifier will be generated and returned. deleted (boolean) – Deleted If true, this dataset has been deleted and its data is no longer guaranteed to exist. maximum_size (integer\|null) – Maximum size The upper limit on how much data the dataset will be allowed to store, as an integer number of bytes. metadata (object) – Data about a dataset Additional key/value data describing the dataset. These items are not interpreted by Flocker. If not given, no metadata will be associated with the new dataset. primary (string) – Primary manifestation (node UUID) The UUID of the node which will be given the primary manifestation of the newly created dataset.

dataset_id (string) –
Unique identifier

An opaque identifier, unique across the cluster, identifying a particular dataset. If not given, a new identifier will be generated and returned.
deleted (boolean) –
Deleted

If true, this dataset has been deleted and its data is no longer guaranteed to exist.
maximum_size (integer|null) –
Maximum size

The upper limit on how much data the dataset will be allowed to store, as an integer number of bytes.
metadata (object) –
Data about a dataset

Additional key/value data describing the dataset. These items are not interpreted by Flocker. If not given, no metadata will be associated with the new dataset.
primary (string) –
Primary manifestation (node UUID)

The UUID of the node which will be given the primary manifestation of the newly created dataset.

Create new dataset ¶

POST /v1/configuration/datasets¶

Create a new dataset.

Supports X-If-Configuration-Matches header in the request to ensure creation only happens if the configuration hasn’t changed.

+ Request JSON Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "allOf": [
        {
            "additionalProperties": false,
            "description": "The configuration for a particular dataset.",
            "properties": {
                "dataset_id": {
                    "allOf": [
                        {
                            "description": "An opaque identifier, unique across a cluster, identifying a\nparticular dataset or node.  If not specified when creating a dataset, a new\nidentifier will be generated and returned.\n",
                            "maxLength": 36,
                            "minLength": 36,
                            "pattern": "^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-4[A-Fa-f0-9]{3}-[89abAB][A-Fa-f0-9]{3}-[A-Fa-f0-9]{12}$",
                            "title": "Unique identifer",
                            "type": "string"
                        }
                    ],
                    "description": "An opaque identifier, unique across the cluster, identifying a\nparticular dataset.  If not given, a new identifier will be generated\nand returned.\n",
                    "title": "Unique identifier",
                    "type": "string"
                },
                "deleted": {
                    "description": "If true, this dataset has been deleted and its data is no longer\nguaranteed to exist.\n",
                    "title": "Deleted",
                    "type": "boolean"
                },
                "maximum_size": {
                    "description": "The upper limit on how much data the dataset will be allowed to\nstore, as an integer number of bytes.\n",
                    "minimum": 67108864,
                    "multipleOf": 1024,
                    "title": "Maximum size",
                    "type": [
                        "integer",
                        "null"
                    ]
                },
                "metadata": {
                    "additionalProperties": false,
                    "description": "Additional key/value data describing the dataset.  These items are\nnot interpreted by Flocker.  If not given, no metadata will be\nassociated with the new dataset.\n",
                    "maxProperties": 16,
                    "patternProperties": {
                        "^.{1,256}$": {
                            "maxLength": 256,
                            "type": "string"
                        }
                    },
                    "title": "Data about a dataset",
                    "type": "object"
                },
                "primary": {
                    "allOf": [
                        {
                            "description": "An opaque identifier, unique across a cluster, identifying a\nparticular dataset or node.  If not specified when creating a dataset, a new\nidentifier will be generated and returned.\n",
                            "maxLength": 36,
                            "minLength": 36,
                            "pattern": "^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-4[A-Fa-f0-9]{3}-[89abAB][A-Fa-f0-9]{3}-[A-Fa-f0-9]{12}$",
                            "title": "Unique identifer",
                            "type": "string"
                        }
                    ],
                    "description": "The UUID of the node which will be given the primary manifestation\nof the newly created dataset.\n",
                    "title": "Primary manifestation (node UUID)",
                    "type": "string"
                }
            },
            "title": "Dataset Configuration",
            "type": "object"
        },
        {
            "required": [
                "primary"
            ]
        }
    ],
    "description": "The input schema for the create_dataset endpoint\n",
    "properties": {},
    "type": "object"
}

+ Response JSON Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalProperties": false,
    "description": "The configuration for a particular dataset.",
    "properties": {
        "dataset_id": {
            "allOf": [
                {
                    "description": "An opaque identifier, unique across a cluster, identifying a\nparticular dataset or node.  If not specified when creating a dataset, a new\nidentifier will be generated and returned.\n",
                    "maxLength": 36,
                    "minLength": 36,
                    "pattern": "^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-4[A-Fa-f0-9]{3}-[89abAB][A-Fa-f0-9]{3}-[A-Fa-f0-9]{12}$",
                    "title": "Unique identifer",
                    "type": "string"
                }
            ],
            "description": "An opaque identifier, unique across the cluster, identifying a\nparticular dataset.  If not given, a new identifier will be generated\nand returned.\n",
            "title": "Unique identifier",
            "type": "string"
        },
        "deleted": {
            "description": "If true, this dataset has been deleted and its data is no longer\nguaranteed to exist.\n",
            "title": "Deleted",
            "type": "boolean"
        },
        "maximum_size": {
            "description": "The upper limit on how much data the dataset will be allowed to\nstore, as an integer number of bytes.\n",
            "minimum": 67108864,
            "multipleOf": 1024,
            "title": "Maximum size",
            "type": [
                "integer",
                "null"
            ]
        },
        "metadata": {
            "additionalProperties": false,
            "description": "Additional key/value data describing the dataset.  These items are\nnot interpreted by Flocker.  If not given, no metadata will be\nassociated with the new dataset.\n",
            "maxProperties": 16,
            "patternProperties": {
                "^.{1,256}$": {
                    "maxLength": 256,
                    "type": "string"
                }
            },
            "title": "Data about a dataset",
            "type": "object"
        },
        "primary": {
            "allOf": [
                {
                    "description": "An opaque identifier, unique across a cluster, identifying a\nparticular dataset or node.  If not specified when creating a dataset, a new\nidentifier will be generated and returned.\n",
                    "maxLength": 36,
                    "minLength": 36,
                    "pattern": "^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-4[A-Fa-f0-9]{3}-[89abAB][A-Fa-f0-9]{3}-[A-Fa-f0-9]{12}$",
                    "title": "Unique identifer",
                    "type": "string"
                }
            ],
            "description": "The UUID of the node which will be given the primary manifestation\nof the newly created dataset.\n",
            "title": "Primary manifestation (node UUID)",
            "type": "string"
        }
    },
    "title": "Dataset Configuration",
    "type": "object"
}

Example: Specifying as few parameters as possible, create a new dataset on the cluster. A node is specified to have the primary manifestation for the new dataset. The unique dataset identifier is automatically generated by the server and returned with the response. When the maximum_size parameter is omitted, the dataset will have a default size of 100GiB. The default may change (issue 2679) so it is advisable to always specify the maximum_size.

Request

POST /v1/configuration/datasets HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"primary": "cf0f0346-17b2-4812-beca-1434997d6c3f"}

Response

HTTP/1.1 201 Created
Content-Type: application/json

{"dataset_id": "a5f75af7-3fb9-4c1a-81ce-efeeb9f2c788", "primary": "cf0f0346-17b2-4812-beca-1434997d6c3f", "metadata": {}, "deleted": false}

Example: Create a new dataset with a specified unique identifier instead of letting the server generate it.

Request

POST /v1/configuration/datasets HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"dataset_id": "ad0a05dd-a1ed-449f-b44b-e1e2757bda00", "primary": "cf0f0346-17b2-4812-beca-1434997d6c3f"}

Response

HTTP/1.1 201 Created
Content-Type: application/json

{"dataset_id": "a5f75af7-3fb9-4c1a-81ce-efeeb9f2c788", "primary": "cf0f0346-17b2-4812-beca-1434997d6c3f", "metadata": {}, "deleted": false}

Example: Attempt to create a new dataset with a specified unique identifier that is already assigned to a dataset that exists. This results in a failure to create the dataset and an error response.

Request

POST /v1/configuration/datasets HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"dataset_id": "ad0a05dd-a1ed-449f-b44b-e1e2757bda00", "primary": "cf0f0346-17b2-4812-beca-1434997d6c3f"}

Response

HTTP/1.1 409 Conflict
Content-Type: application/json

{"description": "Specified dataset_id already associated with a dataset."}

Example: Create a new dataset that has an upper bound on the amount of data it will store.

Request

POST /v1/configuration/datasets HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"primary": "cf0f0346-17b2-4812-beca-1434997d6c3f", "maximum_size": 1073741824}

Response

HTTP/1.1 201 Created
Content-Type: application/json

{"dataset_id": "47440eff-e933-4de0-b56c-d3469b61421f", "primary": "cf0f0346-17b2-4812-beca-1434997d6c3f", "maximum_size": 1073741824, "metadata": {}, "deleted": false}

Example: Create a new dataset with some arbitrary key/value data associated with it.

Request

POST /v1/configuration/datasets HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"primary": "cf0f0346-17b2-4812-beca-1434997d6c3f", "metadata": {"name": "demo", "owner": "alice"}}

Response

HTTP/1.1 201 Created
Content-Type: application/json

{"dataset_id": "886ed03a-5606-453a-94a9-a1cbaf35164c", "primary": "cf0f0346-17b2-4812-beca-1434997d6c3f", "metadata": {"name": "demo", "owner": "alice"}, "deleted": false}

Response JSON Object:

Response JSON Object:
	dataset_id (string) – Unique identifier An opaque identifier, unique across the cluster, identifying a particular dataset. If not given, a new identifier will be generated and returned. deleted (boolean) – Deleted If true, this dataset has been deleted and its data is no longer guaranteed to exist. maximum_size (integer\|null) – Maximum size The upper limit on how much data the dataset will be allowed to store, as an integer number of bytes. metadata (object) – Data about a dataset Additional key/value data describing the dataset. These items are not interpreted by Flocker. If not given, no metadata will be associated with the new dataset. primary (string) – Primary manifestation (node UUID) The UUID of the node which will be given the primary manifestation of the newly created dataset.

dataset_id (string) –
Unique identifier

An opaque identifier, unique across the cluster, identifying a particular dataset. If not given, a new identifier will be generated and returned.
deleted (boolean) –
Deleted

If true, this dataset has been deleted and its data is no longer guaranteed to exist.
maximum_size (integer|null) –
Maximum size

The upper limit on how much data the dataset will be allowed to store, as an integer number of bytes.
metadata (object) –
Data about a dataset

Additional key/value data describing the dataset. These items are not interpreted by Flocker. If not given, no metadata will be associated with the new dataset.
primary (string) –
Primary manifestation (node UUID)

The UUID of the node which will be given the primary manifestation of the newly created dataset.

Delete an existing dataset ¶

DELETE /v1/configuration/datasets/(dataset_id)¶

Deletion is idempotent: deleting a dataset multiple times will result in the same response.

Supports X-If-Configuration-Matches header in the request to ensure deletion only happens if the configuration hasn’t changed.

+ Response JSON Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalProperties": false,
    "description": "The configuration for a particular dataset.",
    "properties": {
        "dataset_id": {
            "allOf": [
                {
                    "description": "An opaque identifier, unique across a cluster, identifying a\nparticular dataset or node.  If not specified when creating a dataset, a new\nidentifier will be generated and returned.\n",
                    "maxLength": 36,
                    "minLength": 36,
                    "pattern": "^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-4[A-Fa-f0-9]{3}-[89abAB][A-Fa-f0-9]{3}-[A-Fa-f0-9]{12}$",
                    "title": "Unique identifer",
                    "type": "string"
                }
            ],
            "description": "An opaque identifier, unique across the cluster, identifying a\nparticular dataset.  If not given, a new identifier will be generated\nand returned.\n",
            "title": "Unique identifier",
            "type": "string"
        },
        "deleted": {
            "description": "If true, this dataset has been deleted and its data is no longer\nguaranteed to exist.\n",
            "title": "Deleted",
            "type": "boolean"
        },
        "maximum_size": {
            "description": "The upper limit on how much data the dataset will be allowed to\nstore, as an integer number of bytes.\n",
            "minimum": 67108864,
            "multipleOf": 1024,
            "title": "Maximum size",
            "type": [
                "integer",
                "null"
            ]
        },
        "metadata": {
            "additionalProperties": false,
            "description": "Additional key/value data describing the dataset.  These items are\nnot interpreted by Flocker.  If not given, no metadata will be\nassociated with the new dataset.\n",
            "maxProperties": 16,
            "patternProperties": {
                "^.{1,256}$": {
                    "maxLength": 256,
                    "type": "string"
                }
            },
            "title": "Data about a dataset",
            "type": "object"
        },
        "primary": {
            "allOf": [
                {
                    "description": "An opaque identifier, unique across a cluster, identifying a\nparticular dataset or node.  If not specified when creating a dataset, a new\nidentifier will be generated and returned.\n",
                    "maxLength": 36,
                    "minLength": 36,
                    "pattern": "^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-4[A-Fa-f0-9]{3}-[89abAB][A-Fa-f0-9]{3}-[A-Fa-f0-9]{12}$",
                    "title": "Unique identifer",
                    "type": "string"
                }
            ],
            "description": "The UUID of the node which will be given the primary manifestation\nof the newly created dataset.\n",
            "title": "Primary manifestation (node UUID)",
            "type": "string"
        }
    },
    "title": "Dataset Configuration",
    "type": "object"
}

Example: Delete a dataset.

Request

DELETE /v1/configuration/datasets/886ed03a-5606-453a-94a9-a1cbaf35164c HTTP/1.1
Host: api.example.com
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{"dataset_id": "886ed03a-5606-453a-94a9-a1cbaf35164c", "primary": "7ec3c4eb-6b1c-43da-8015-a163f7d15244", "deleted": true}

Example: An attempt to delete an unknown dataset results in a 404 Not Found response.

Request

DELETE /v1/configuration/datasets/31d50a07-f679-4f95-ae0d-56c93513fbc2 HTTP/1.1
Host: api.example.com
Content-Type: application/json

Response

HTTP/1.1 404 Not Found
Content-Type: application/json

{"description": "Dataset not found."}

Response JSON Object:

Response JSON Object:
	dataset_id (string) – Unique identifier An opaque identifier, unique across the cluster, identifying a particular dataset. If not given, a new identifier will be generated and returned. deleted (boolean) – Deleted If true, this dataset has been deleted and its data is no longer guaranteed to exist. maximum_size (integer\|null) – Maximum size The upper limit on how much data the dataset will be allowed to store, as an integer number of bytes. metadata (object) – Data about a dataset Additional key/value data describing the dataset. These items are not interpreted by Flocker. If not given, no metadata will be associated with the new dataset. primary (string) – Primary manifestation (node UUID) The UUID of the node which will be given the primary manifestation of the newly created dataset.

dataset_id (string) –
Unique identifier

An opaque identifier, unique across the cluster, identifying a particular dataset. If not given, a new identifier will be generated and returned.
deleted (boolean) –
Deleted

If true, this dataset has been deleted and its data is no longer guaranteed to exist.
maximum_size (integer|null) –
Maximum size

The upper limit on how much data the dataset will be allowed to store, as an integer number of bytes.
metadata (object) –
Data about a dataset

Additional key/value data describing the dataset. These items are not interpreted by Flocker. If not given, no metadata will be associated with the new dataset.
primary (string) –
Primary manifestation (node UUID)

The UUID of the node which will be given the primary manifestation of the newly created dataset.

Update an existing dataset ¶

POST /v1/configuration/datasets/(dataset_id)¶

This can be used to:

Move a dataset from one node to another by changing the primary attribute.
In the future this may be used to update metadata, but that is not currently supported.

Supports X-If-Configuration-Matches header in the request to ensure the update only happens if the configuration hasn’t changed.

+ Request JSON Schema

+ Response JSON Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalProperties": false,
    "description": "The configuration for a particular dataset.",
    "properties": {
        "dataset_id": {
            "allOf": [
                {
                    "description": "An opaque identifier, unique across a cluster, identifying a\nparticular dataset or node.  If not specified when creating a dataset, a new\nidentifier will be generated and returned.\n",
                    "maxLength": 36,
                    "minLength": 36,
                    "pattern": "^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-4[A-Fa-f0-9]{3}-[89abAB][A-Fa-f0-9]{3}-[A-Fa-f0-9]{12}$",
                    "title": "Unique identifer",
                    "type": "string"
                }
            ],
            "description": "An opaque identifier, unique across the cluster, identifying a\nparticular dataset.  If not given, a new identifier will be generated\nand returned.\n",
            "title": "Unique identifier",
            "type": "string"
        },
        "deleted": {
            "description": "If true, this dataset has been deleted and its data is no longer\nguaranteed to exist.\n",
            "title": "Deleted",
            "type": "boolean"
        },
        "maximum_size": {
            "description": "The upper limit on how much data the dataset will be allowed to\nstore, as an integer number of bytes.\n",
            "minimum": 67108864,
            "multipleOf": 1024,
            "title": "Maximum size",
            "type": [
                "integer",
                "null"
            ]
        },
        "metadata": {
            "additionalProperties": false,
            "description": "Additional key/value data describing the dataset.  These items are\nnot interpreted by Flocker.  If not given, no metadata will be\nassociated with the new dataset.\n",
            "maxProperties": 16,
            "patternProperties": {
                "^.{1,256}$": {
                    "maxLength": 256,
                    "type": "string"
                }
            },
            "title": "Data about a dataset",
            "type": "object"
        },
        "primary": {
            "allOf": [
                {
                    "description": "An opaque identifier, unique across a cluster, identifying a\nparticular dataset or node.  If not specified when creating a dataset, a new\nidentifier will be generated and returned.\n",
                    "maxLength": 36,
                    "minLength": 36,
                    "pattern": "^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-4[A-Fa-f0-9]{3}-[89abAB][A-Fa-f0-9]{3}-[A-Fa-f0-9]{12}$",
                    "title": "Unique identifer",
                    "type": "string"
                }
            ],
            "description": "The UUID of the node which will be given the primary manifestation\nof the newly created dataset.\n",
            "title": "Primary manifestation (node UUID)",
            "type": "string"
        }
    },
    "title": "Dataset Configuration",
    "type": "object"
}

Example: Update a dataset with a new primary address. This will effectively move the dataset’s contents, making them accessible on the new primary node.

Request

POST /v1/configuration/datasets/886ed03a-5606-453a-94a9-a1cbaf35164c HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"primary": "7ec3c4eb-6b1c-43da-8015-a163f7d15244"}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{"dataset_id": "886ed03a-5606-453a-94a9-a1cbaf35164c", "primary": "7ec3c4eb-6b1c-43da-8015-a163f7d15244", "deleted": false}

Example: An attempt to update an unknown dataset results in a 404 Not Found response.

Request

POST /v1/configuration/datasets/31d50a07-f679-4f95-ae0d-56c93513fbc2 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"primary": "7ec3c4eb-6b1c-43da-8015-a163f7d15244"}

Response

HTTP/1.1 404 Not Found
Content-Type: application/json

{"description": "Dataset not found."}

Request JSON Object:
	primary (string) – Primary manifestation (node UUID) The UUID of the node which will be given the primary manifestation of the newly created dataset.
Response JSON Object:
	dataset_id (string) – Unique identifier An opaque identifier, unique across the cluster, identifying a particular dataset. If not given, a new identifier will be generated and returned. deleted (boolean) – Deleted If true, this dataset has been deleted and its data is no longer guaranteed to exist. maximum_size (integer\|null) – Maximum size The upper limit on how much data the dataset will be allowed to store, as an integer number of bytes. metadata (object) – Data about a dataset Additional key/value data describing the dataset. These items are not interpreted by Flocker. If not given, no metadata will be associated with the new dataset. primary (string) – Primary manifestation (node UUID) The UUID of the node which will be given the primary manifestation of the newly created dataset.

List all leases on datasets ¶

GET /v1/configuration/leases¶

List the currently existing leases on datasets, including which node the lease is for and when if ever the lease will expire.

+ Response JSON Schema

Example: List the leases on datasets in the cluster. Notice how one lease expires in 30 seconds, and one will never expire.

Request

GET /v1/configuration/leases HTTP/1.1
Host: api.example.com
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "dataset_id": "886ed03a-5606-453a-94a9-a1cbaf35164c",
    "node_uuid": "cf0f0346-17b2-4812-beca-1434997d6c3f",
    "expires": null
  },
  {
    "dataset_id": "47440eff-e933-4de0-b56c-d3469b61421f",
    "node_uuid": "7ec3c4eb-6b1c-43da-8015-a163f7d15244",
    "expires": 30
  },
]

Response JSON Array of Objects:
	dataset_id (string) – (required) Dataset An opaque identifier, unique across the cluster, identifying a particular dataset. expires (number\|null) – (required) Lease Expiration The number of seconds until a lease expires, or null to indicate no expiration. node_uuid (string) – (required) Node The UUID of a node in the cluster.

Acquire a lease on a dataset ¶

POST /v1/configuration/leases¶

Acquire a lease on a particular dataset on a particular node. Until the lease is released or expires the dataset will not be deleted or moved to other nodes.

+ Request JSON Schema

+ Response JSON Schema

Example: Acquire a lease that does not expire.

Request

POST /v1/configuration/leases HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "dataset_id": "886ed03a-5606-453a-94a9-a1cbaf35164c",
  "node_uuid": "cf0f0346-17b2-4812-beca-1434997d6c3f",
  "expires": null
}

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "dataset_id": "886ed03a-5606-453a-94a9-a1cbaf35164c",
  "node_uuid": "cf0f0346-17b2-4812-beca-1434997d6c3f",
  "expires": null
}

Example: Acquire a lease that expires in 30 seconds.

Request

POST /v1/configuration/leases HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "dataset_id": "47440eff-e933-4de0-b56c-d3469b61421f",
  "node_uuid": "7ec3c4eb-6b1c-43da-8015-a163f7d15244",
  "expires": 30
}

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "dataset_id": "47440eff-e933-4de0-b56c-d3469b61421f",
  "node_uuid": "7ec3c4eb-6b1c-43da-8015-a163f7d15244",
  "expires": 30
}

Example: If a lease on a particular dataset is for one node, you can’t acquire a lease on the same dataset on a different node.

Request

POST /v1/configuration/leases HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "dataset_id": "47440eff-e933-4de0-b56c-d3469b61421f",
  "node_uuid": "cf0f0346-17b2-4812-beca-1434997d6c3f",
  "expires": null
}

Response

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "description": "Lease already held."
}

Example: If a lease on a particular dataset is re-acquired with the same node you can renew the lease and extend its expiration.

Request

POST /v1/configuration/leases HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "dataset_id": "47440eff-e933-4de0-b56c-d3469b61421f",
  "node_uuid": "7ec3c4eb-6b1c-43da-8015-a163f7d15244",
  "expires": 60
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "dataset_id": "47440eff-e933-4de0-b56c-d3469b61421f",
  "node_uuid": "7ec3c4eb-6b1c-43da-8015-a163f7d15244",
  "expires": 60
}

Request JSON Object:
	dataset_id (string) – (required) Dataset An opaque identifier, unique across the cluster, identifying a particular dataset. expires (number\|null) – (required) Lease Expiration The number of seconds until a lease expires, or null to indicate no expiration. node_uuid (string) – (required) Node The UUID of a node in the cluster.
Response JSON Object:
	dataset_id (string) – (required) Dataset An opaque identifier, unique across the cluster, identifying a particular dataset. expires (number\|null) – (required) Lease Expiration The number of seconds until a lease expires, or null to indicate no expiration. node_uuid (string) – (required) Node The UUID of a node in the cluster.

Release a lease on a dataset ¶

DELETE /v1/configuration/leases/(dataset_id)¶

This will release a lease on a dataset, allowing the dataset to be moved elsewhere, deleted and otherwise modified. Releasing the lease does not modify the dataset in any way, it simply allows other operations to do so.

+ Response JSON Schema

Example: Release a lease on a dataset.

Request

DELETE /v1/configuration/leases/886ed03a-5606-453a-94a9-a1cbaf35164c HTTP/1.1
Host: api.example.com
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "node_uuid": "cf0f0346-17b2-4812-beca-1434997d6c3f",
    "dataset_id": "886ed03a-5606-453a-94a9-a1cbaf35164c",
    "expires": null
}

Response JSON Object:
	dataset_id (string) – (required) Dataset An opaque identifier, unique across the cluster, identifying a particular dataset. expires (number\|null) – (required) Lease Expiration The number of seconds until a lease expires, or null to indicate no expiration. node_uuid (string) – (required) Node The UUID of a node in the cluster.

Get current cluster datasets ¶

GET /v1/state/datasets¶

The result reflects the control service’s knowledge, which may be out of date or incomplete. E.g. a dataset agent has not connected or updated the control service yet.

+ Response JSON Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "An array of state datasets.",
    "items": {
        "additionalProperties": false,
        "description": "The state of a particular dataset.",
        "properties": {
            "dataset_id": {
                "allOf": [
                    {
                        "description": "An opaque identifier, unique across a cluster, identifying a\nparticular dataset or node.  If not specified when creating a dataset, a new\nidentifier will be generated and returned.\n",
                        "maxLength": 36,
                        "minLength": 36,
                        "pattern": "^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-4[A-Fa-f0-9]{3}-[89abAB][A-Fa-f0-9]{3}-[A-Fa-f0-9]{12}$",
                        "title": "Unique identifer",
                        "type": "string"
                    }
                ],
                "description": "An opaque identifier, unique across the cluster, identifying a\nparticular dataset.  If not given, a new identifier will be generated\nand returned.\n",
                "title": "Unique identifier",
                "type": "string"
            },
            "maximum_size": {
                "description": "The upper limit on how much data the dataset will be allowed to\nstore, as an integer number of bytes.\n",
                "minimum": 67108864,
                "multipleOf": 1024,
                "title": "Maximum size",
                "type": [
                    "integer",
                    "null"
                ]
            },
            "path": {
                "description": "The filesystem path where the dataset is mounted on a node.\nCan only be present in cluster state, not in configuration.\n",
                "title": "Node mount path",
                "type": "string"
            },
            "primary": {
                "allOf": [
                    {
                        "description": "An opaque identifier, unique across a cluster, identifying a\nparticular dataset or node.  If not specified when creating a dataset, a new\nidentifier will be generated and returned.\n",
                        "maxLength": 36,
                        "minLength": 36,
                        "pattern": "^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-4[A-Fa-f0-9]{3}-[89abAB][A-Fa-f0-9]{3}-[A-Fa-f0-9]{12}$",
                        "title": "Unique identifer",
                        "type": "string"
                    }
                ],
                "description": "The UUID of the node which will be given the primary manifestation\nof the newly created dataset.\n",
                "title": "Primary manifestation (node UUID)",
                "type": "string"
            }
        },
        "required": [
            "dataset_id"
        ],
        "type": "object"
    },
    "type": "array"
}

Example: Get a list of all datasets in a deployment. This includes manifest (attached) and non-manifest (unattached) datasets. For example, a dataset on a block device that has been created, but is not attached to any machine, is a non-manifest dataset. The primary and path values will not be present for non-manifest datasets.

Request

GET /v1/state/datasets HTTP/1.1
Host: api.example.com
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[{"dataset_id": "47440eff-e933-4de0-b56c-d3469b61421f",
  "primary": "cf0f0346-17b2-4812-beca-1434997d6c3f",
  "maximum_size": 1073741824,
  "path": "/flocker/somearbitrarypath"},
 {"dataset_id": "886ed03a-5606-453a-94a9-a1cbaf35164c",
  "maximum_size": 1073741824}]

Response JSON Array of Objects:

Response JSON Array of Objects:
	dataset_id (string) – (required) Unique identifier An opaque identifier, unique across the cluster, identifying a particular dataset. If not given, a new identifier will be generated and returned. maximum_size (integer\|null) – Maximum size The upper limit on how much data the dataset will be allowed to store, as an integer number of bytes. path (string) – Node mount path The filesystem path where the dataset is mounted on a node. Can only be present in cluster state, not in configuration. primary (string) – Primary manifestation (node UUID) The UUID of the node which will be given the primary manifestation of the newly created dataset.

dataset_id (string) –
(required) Unique identifier

An opaque identifier, unique across the cluster, identifying a particular dataset. If not given, a new identifier will be generated and returned.
maximum_size (integer|null) –
Maximum size

The upper limit on how much data the dataset will be allowed to store, as an integer number of bytes.
path (string) –
Node mount path

The filesystem path where the dataset is mounted on a node. Can only be present in cluster state, not in configuration.
primary (string) –
Primary manifestation (node UUID)

The UUID of the node which will be given the primary manifestation of the newly created dataset.

Install & Docs

REST API Endpoints¶

Communicating with the API¶

Conditional Requests¶

Endpoints¶

List known nodes in the cluster ¶

Lookup a node by its era ¶

Get Flocker version ¶

Get the cluster’s dataset configuration ¶

Create new dataset ¶

Delete an existing dataset ¶

Update an existing dataset ¶

List all leases on datasets ¶

Acquire a lease on a dataset ¶

Release a lease on a dataset ¶

Get current cluster datasets ¶

How could we improve this page?