Get Information on the Cluster
The Backup Service REST API allows information to be retrieved on a cluster’s active, archived, and imported repositories.
Description
Returns a JSON document that contains subdocuments for active, imported, and archived repositories on the host cluster.
Curl Syntax
curl -X GET http://<backup-node-ip-address-or-domain-name>:8097/cluster/self -u <username>:<password>
Only the host cluster (self
) can be queried.
The username
and password
must be those of a user with the Full Admin
role.
Responses
Success returns 200 OK
, and a JSON document that contains three subdocuments, which respectively correspond to the active, imported, and archived repositories on the cluster.
The information in each subdocument includes an object for each repository.
This object provides:
-
The id of the repository.
-
The name of the plan that the repository uses.
-
The name and uuid of the single bucket to which the plan is dedicated (unless the plan is dedicated to all buckets on the cluster).
-
The location of backed-up data on disk.
-
The names of the individual tasks within the plan; along with their task-type, and their next-scheduled time of running.
If a cluster-name other than self
is specified, 400 Bad Request
is returned, with a message such as the following: {"status":400,"msg":"Remote clusters not supported","extras":"Invalid cluster: se3lf"}
.
If an incorrect URI is otherwise specified, 404 Object Not Found
is returned, with a message such as the following: 404 Object Not Found
.
Failure to authenticate returns 401 Unauthorized
.
An internal error that prevents return of the repository-information returns 500 Internal Server Error
.
Examples
The following call requests the list of repositories currently defined on the cluster:
curl -v -X GET http://127.0.0.1:8091/_p/backup/api/v1/cluster/self \ -u Administrator:password
If successful, the call returns 200 OK
, and an object whose initial part may appear as follows:
{ "name": "self", "imported": { "mergedRepo": { "id": "mergedRepo", "plan_name": "", "state": "imported", "archive": "/Users/user/Documents/mergedRepo", "repo": "7509894b-7138-40fe-917e-9581d298482c", "version": 1, "creation_time": "2020-09-17T10:15:39.025614+01:00", "update_time": "2020-09-17T10:15:39.025614+01:00" } }, "archived": {}, "active": { "hourlyBackupRepo": { "id": "hourlyBackupRepo", "plan_name": "hourlyBackupRepo", "bucket": { "name": "travel-sample", "uuid": "bf5e2d0ec35e7957ed96509b8ed7e13f" }, "state": "paused", "archive": "/Users/user/Documents/backups/hourlyBackupRepo", "repo": "56f42a97-6c52-4e32-8597-b0bfed34af29", "running_one_off": { "restore-3034992d-5d1b-44d5-a9a3-a673b541f430": { "task_name": "restore-3034992d-5d1b-44d5-a9a3-a673b541f430", "status": "running", "start": "2020-09-16T11:06:47.089102+01:00", "end": "0001-01-01T00:00:00Z", "node_runs": [ { "node_id": "1208b19a4d30e0b4c6af96b6448b4969", "status": "running", "start": "2020-09-16T11:06:47.087325+01:00", "end": "0001-01-01T00:00:00Z", "progress": 0, "error_code": 0 } ], "error_code": 0, "type": "RESTORE", "target_cluster": "http://1270.0.1:8091" } }, "version": 1, "health": { "healthy": false, "health_issue": "cannot verify bucket exists: bucket UUIDs don't match `bf5e2d0ec35e7957ed96509b8ed7e13f` != `15b15c78439db91ba73f27ac4d6ba116" }, "creation_time": "2020-09-11T14:10:20.875345+01:00", "update_time": "2020-09-22T10:40:07.112184+01:00" }, "testRepo": { "id": "testRepo", "plan_name": "_hourly_backups", "bucket": { "name": "travel-sample", . . .
The cluster is thus shown to contain a single imported repository, no archived repositories, and a number of active repositories, two of which can be identified in the fragment shown.
See Also
An overview of the Backup Service is provided in Backup Service. A step-by-step guide to using Couchbase Web Console to configure and use the Backup Service is provided in Manage Backup and Restore. Information on using the Backup Service REST API to create a repository is provided in Create a Repository.