a9s Service Dashboard

This topic describes how to use the a9s Service Dashboard.

Login

  1. To get the a9s Service Dashboard URL use the command cf service SERVICE-NAME. For example:
$ cf service my-redis
Showing info of service my-redis in org demo / space demo as admin...

name:            my-redis
service:         a9s-redis32
tags:
plan:            redis-single-small
description:     This is a service creating and managing dedicated Redis service instances, powered by the anynines Service Framework
documentation:
dashboard:       https://a9s-redis-dashboard.system.172.28.32.25.xip.io/service-instances/96aaef1d-be67-45fc-a121-25160bf83ab2

This service is not currently shared.

Showing status of last operation from service my-redis...

status:    create succeeded
message:
started:   2018-10-17T11:25:04Z
updated:   2018-10-17T11:29:10Z

There are no bound apps for this service.
  1. Browse to the dashboard URL and authenticate on the redirected page with your Cloud Foundry credentials: authentication-page

  2. Click Authorize to approve the authorization request: authorization-page

Perform a Backup

Open the Service Dashboard for the Service Instance you want to backup, as shown above. Navigate to the Backups page. There you find a panel with Available Backups and a Settings Icon which opens a submenu where you can find a Manually Trigger A Backup button. Click this button to perform a new backup of the Service Instance.

service-dashboard

After a short period of time the backup will be queued. The backup process will start soon.

service-dashboard

NOTE: Depending on the size of the data the backup will take some time.

service-dashboard

Restore a Backup

Open the Service Dashboard for the Service Instance, as shown above, you want to restore a backup that you performed before. Navigate to the Backups page. There you find a panel with Available Backups and a Restore button next to each backup. Click this button to trigger a restore.

service-dashboard

A dialog opens and ask for confirmation. Press the YES button to continue or the No button to abort the restore.

service-dashboard

After a short period of time the restore will be queued. The restore process will start soon.

service-dashboard

NOTE: Depending on the size of the data the restore will take some time.

service-dashboard

Restore History

When a restore is triggered, it is logged and listed as shown below:

service-dashboard

When using a single instance, it is listed as a single entry per restore, as seen before.

In the case of a cluster however, the way that the restores are listed will vary depending on the service in use. This variation can be divided into two groups: master only restore and multi-node restore.

Take for example our a9s-MongoDB service, it does a restore on every node, so these are sequentially generated restores that will appear as multiple restores, but with a fused Backup created at row, as shown below:

service-dashboard

On the other hand, the a9s-PostgreSQL service will only execute the restore on the master node. Therefore only one row is listed, like with the single instance example.

See the following list for further details:

  • a9s-Elasticsearch: master-only restore
  • a9s-MongoDB: multi-node restore
  • a9s-MySQL: master-only restore
  • a9s-PostgreSQL: master-only restore
  • a9s-Messaging: master-only restore
  • a9s-Redis: multi-node restore

Download a backup

To be able to download a performed backup first you have to set a personal encryption key. Otherwise a performed backup is not downloadable.

To set a personal encryption key open the Service Dashboard for the appropriate Service Instance as shown above. Navigate to the Backups page and open the Settings menu by clicking the Settings icon on that panel. Afterwards click on the Set Encryption Key button.

service-dashboard

Enter your personal encryption key in the field Encryption Key and click the Save button. The default minimum length for your personal encryption key is

service-dashboard

After that perform a backup as shown above. If the backup is successfully finished the button Download beside the backup becomes clickable. Click this button to download the corresponding backup.

service-dashboard

NOTE: If you change your personal encryption key again you are not longer able to download performed backups encrypted with your old personal encryption key.

Automatic Reload

To reload the information shown click on the Reload icon in the upper right corner of the dashboard. To enable Automatic Reload of the dashboard information just enable the Switch button next to the Reload icon.

service-dashboard

Update the Service Instance

To update a service instance open the Updates page using the navbar on the top of the dashboard application. Afterwards you will see if there are any updates available for the selected instance.

service-dashboard

Restart/Recreate the Service Instance

To Restart or Recrate a running service instance you are able to use the related buttons in the lower left corner of the dashboard application.

service-dashboard

NOTE: The restart button will trigger a shutdown/turn-on actions on all processes of the current instance. The recreate button will remove and recreate the current instance and its related processes.

API

This topic describes how to use the a9s Service Dashboard API, in order to enable and disable features in the frontend, get information about the service instance or start or restore backups.

How to access the API using cURL

We run the a9s Service Dashboard API protected by the a9s SSO Proxy. This means that in order to access this API, we need first to be authenticated and authorised to access it.

Authentication

To correctly authorise the access when accessing using cURL, the user must first get the token from Cloud Foundry:

$ oauth_token=$(cf oauth-token)
$ bearer_token=$(echo ${oauth_token} | grep bearer)

Then, get the a9s Service Dashboard URL using cf service:

$ cf service <service_name>

This should give you an output like:

Showing info of service my-service in org example / space example as admin...

name:            my-service
service:         a9s-redis
...
dashboard:       https://a9s-redis-dashboard.example.com/service-instances/db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d

Showing status of last operation from service my-service...

status:    create succeeded
...

In the example above, the URL is:

$ url="https://a9s-redis-dashboard.example.com/service-instances/db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d"

Authorization

The user must execute the request with the given token:

$ curl --cookie test.cookie --cookie-jar test.cookie --location --insecure --header "Authorization: ${bearer_token}" "${url}"

Remember to use --location, since the a9s SSO Proxy redirects to the real endpoint. Use --insecure only if running with self generated certificates.

You should also use cookies. The authentication is handled by Cloud Foundry, so when you have a valid token you are authenticated. With this token, the a9s SSO Proxy checks if you are authorized to access the a9s Service Dashboard for the given instance.

Once the user is authorized, this information is stored in the session, which is then stored in the cookie. After this, the requests can be redirected to the a9s Service Dashboard API and the user can access all the provided endpoints as described below.

Headers

The following HTTP Headers are defined for the operations on this API:

HeaderTypeDescription
Authorization*stringA token that is authorized to access the a9s Service Dashboard API for the given Service Instance.

* Headers with an asterisk are REQUIRED.

List Backups and Restores

Lists all available backups as well as the restores that have been applied.

Request

Route

GET /service-instances/:instance_id/backups

:instance_id MUST be the ID of a previously provisioned Service Instance.

cURL
$ curl --cookie test.cookie --cookie-jar test.cookie --location --insecure --header "Authorization: ${bearer_token}" "${url}/backups"

Response

Status CodeDescription
200 OKIf the request has been processed successfully. The response body is below.
Body

For success responses, the following fields are defined:

Response FieldTypeDescription
idintegerThe internal ID of the Service Instance.
instance_idstringThe ID of the Service Instance as defined in the a9s Service Broker or Cloud Foundry.
backupsarray of Backup objectsSchema of backup objects defined below. MAY be empty.
restoresarray of Restore objectsSchema of restore objects defined below. MAY be empty.
Backup Object
Response FieldTypeDescription
idintegerThe internal ID of the backup.
instance_idintegerThe internal ID of the related Service Instance.
backup_agent_taska Backup Agent Task objectSchema of backup agent task objects defined below.
Restore Object
Response FieldTypeDescription
idintegerThe internal ID of the restore.
instance_idintegerThe internal ID of the related Service Instance.
backup_agent_tasksarray of Backup Agent Task objectsSchema of backup agent task objects defined below.
Backup Agent Task Object
Response FieldTypeDescription
idintegerThe internal ID of the task.
task_idintegerThe internal ID of the related backup/restore.
statusstringThe status of the task. The following statuses exist: queued, running, done, failed, deleted.
created_atdatetimeThe date the task was created.
updated_atdatetimeThe date on which the status of the task was last changed.
{
  "id": 85,
  "instance_id": "db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d",
  "backups": [
    {
      "id": 2811,
      "instance_id": 85,
      "backup_agent_task": {
        "id": 2901,
        "task_id": 2811,
        "status": "done",
        "created_at": "2017-06-29T00:30:03.857Z",
        "updated_at": "2017-06-29T00:30:18.091Z"
      }
    }
  ],
  "restores": [
    {
      "id": 84,
      "instance_id": 85,
      "backup_agent_tasks": [
        {
          "id": 843,
          "task_id": 84,
          "status": "done",
          "created_at": "2017-06-20T14:51:08.661Z",
          "updated_at": "2017-06-20T14:51:19.856Z"
        }
      ]
    }
  ]
}

Create Backup

Start a backup process on a given Service Instance.

Request

Route

POST /service-instances/:instance_id/backups

:instance_id MUST be the ID of a previously provisioned Service Instance.

cURL
$ curl --cookie test.cookie --cookie-jar test.cookie --location --insecure --header "Authorization: ${bearer_token}" -X POST "${url}/backups"

Response

Status
Status CodeDescription
201 CreatedIf the backup has been scheduled.
Body

For success responses, the following fields are defined:

Response FieldTypeDescription
idintegerThe ID of the backup.
messagestringA user-facing message that can be used to tell the user that the backup has been scheduled.

Restore Backup

Restores a backup to a given Service Instance.

Request

Route

POST /service-instances/:instance_id/backups/restore

:instance_id MUST be the ID of a previously provisioned Service Instance.

Body
Request FieldTypeDescription
instance_idintegerThe internal ID of the Service Instance.
backup_idintegerThe internal ID of the backup.
cURL
$ curl --cookie test.cookie --cookie-jar test.cookie --location --insecure --header "Authorization: ${bearer_token}" -X POST "${url}/backups/restore" --data "instance_id=85" --data "backup_id=2811"

Response

Status
Status CodeDescription
200 OKIf the restore has been scheduled.
412 Precondition FailedEither instance_id or backup_id does not exist or match.
Body

For success responses, the following fields are defined:

Response FieldTypeDescription
restore_idintegerThe internal ID of the restore.

For error responses, the following fields are defined:

Response FieldTypeDescription
msgstringA user-facing message that can be used to tell the user what went wrong.

Browser Compatibility

a9s Service Dashboard ensures compatibily with the following versions.

If your version is not in the list, you might encounter issues.

  • Edge: 18, 80, 81, 83
  • Firefox: 68, 69, 70, 71, 72, 73, 74, 75, 76
  • Google Chrome: 73, 74, 75, 76, 77, 78, 79, 80, 81, 83
  • Internet Explorer: Not Supported
  • Opera: 60, 62, 63, 64, 65, 66, 67, 68
  • Safari: 12, 13