Get Information on the Cluster

The Backup Service REST API allows information to be retrieved on a cluster’s active, archived, and imported repositories.

HTTP Methods and URIs

GET /api/v1/cluster/self

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_SERVICE_NODE:$BACKUP_SERVICE_PORT/api/v1/cluster/self
  -u $USERNAME:$PASSWORD

Only the host cluster (self) can be queried.

Required Permissions

Full Admin, Backup Admin, or Read-Only 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:8097/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.