1. Oracle ZFS Storage Appliance RESTful API Guide, Release OS8.8.x
  2. RESTful API Cloud Service
  3. Cloud Service Operations

Cloud Service Operations

Use cloud service operations to manage backups of Oracle ZFS Storage Appliance snapshots in Oracle Cloud Infrastructure Object Storage. You can list targets and backups in Oracle Cloud Infrastructure Object Storage, remove a target, delete a backup, restore a backup to an appliance, and cancel or restart a cloud service job.

To create a backup, see Create a Snapshot Backup in Snapshot Backup Operations. Backups are full or incremental backups of share snapshots. To create a snapshot, see Snapshot and Clone Operations.

The following parameters are used in the table of cloud service operations:

format

The format in which the backup was saved in Oracle Cloud Infrastructure Object Storage.

The value of format is either zfs or tar. If format is not specified for snapshot backup creation, zfs is the default. The zfs format supports both filesystem and LUN snapshots; the tar format supports only filesystem snapshots. For more information about zfs and tar formats, see Creating a Cloud Backup (CLI) in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

backup-id

The identifier for a copy of an appliance snapshot that is saved in Oracle Cloud Infrastructure Object Storage. The value of backup-id is the value of the id property when you list backups as shown in List Cloud Backups.

For a full snapshot backup, the value of backup-id is pool_id/snapshot_id, as shown in the following example: 

3e035b7e546e0d02/1cbfdb5ff2259b76

For an incremental snapshot backup, the value of backup-id is pool_id/child_snapshot_id-parent_snapshot_id, as shown in the following example: 

6913a5703bee98dc/46be95ced54e99d9-667f3eb88fd209e1
target-id

The Oracle Cloud Infrastructure Object Storage location where a backup is saved. A given backup can be saved to multiple targets. That is, the same backup-id can appear in different target-id locations.

The value of target-id is the value of the target property when you list backups.

job-id

The identifier for a running job. The value of job-id is the value of the id property when you list jobs as shown in List Jobs.

Table 9-1 Cloud Service Commands

Request Append to Path /api/service/v2/services Description

GET

/cloud

List the properties and summary data for targets, backups, and jobs

PUT

/cloud

Modify properties

POST

/cloud/targets

Create a new target

GET

/cloud/targets

List targets

GET

/cloud/targets/target-id

List properties of the specified target

PUT

/cloud/targets/target-id

Modify properties of the specified target

DELETE

/cloud/targets/target-id

Remove the specified target from service

GET

/cloud/backups

List all completed backups of any format

GET

/cloud/backups/format/backup-id/target-id

List the specified backup

DELETE

/cloud/backups/format/backup-id/target-id

Delete the specified backup (submit a job request)

POST

/cloud/backups/format/backup-id/target-id/restore

Restore the specified backup (submit a job request)

GET

/cloud/jobs

List running jobs and recently completed jobs

GET

/cloud/jobs/job-id

List properties of the specified job

PUT

/cloud/jobs/job-id/cancel

Cancel the specified running job

PUT

/cloud/jobs/job-id/restart

Restart the specified aborted job

Enable the Cloud Service

To enable the cloud service, set the status to enable as shown in the following example.

Example Request:

PUT /api/service/v2/services/cloud HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*
Content-Type: application/json
Content-Length: 22

{ "<status>": "enable" }

View the Cloud Service Log File

Use the following request to view the log file for the cloud service:

GET /api/log/v1/logs/appliance-kit-cloud:default HTTP/1.1

List Cloud Service Properties

Example Request:

GET /api/service/v2/services/cloud HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

Example Result:

HTTP/1.1 200 OK
Date: Wed, 24 Jul 2019 20:30:59 GMT
Content-Length: 843
X-Zfssa-Service-Api: 2.0
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8

{
  "service": {
    "href": "/api/service/v2/services/cloud",
    "<status>": "online",
    "tls_version": [
      "TLSv1.1",
      "TLSv1.2"
    ],
    "ciphers": [
      "ECDHE-RSA-AES128-GCM-SHA256",
      "ECDHE-RSA-AES256-GCM-SHA384",
      "DHE-RSA-AES128-GCM-SHA256",
      "DHE-RSA-AES256-GCM-SHA384",
      "AES128-SHA",
      "AES256-SHA",
      "DES-CBC3-SHA"
    ],
    "targets": {
      "href": "/api/service/v2/services/cloud/targets",
      "entries": 2
    },
    "backups": {
      "href": "/api/service/v2/services/cloud/backups",
      "entries": 2548
    },
    "jobs": {
      "href": "/api/service/v2/services/cloud/jobs",
      "entries": 0
    }
  }
}

Modify Cloud Service Properties

Example Request:

PUT /api/service/v2/services/cloud HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*
Content-Type: application/json
Content-Length: 48

{
    "tls_version": [
        "TLSv1.0","TLSv1.1","TLSv1.2"
    ]
}

List Targets

The following example lists all targets.

Example Request:

GET /api/service/v2/services/cloud/targets HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

Example Result:

HTTP/1.1 200 OK
Date: Wed, 24 Jul 2019 21:06:18 GMT
Content-Length: 1086
X-Zfssa-Service-Api: 2.0
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8

{
    "targets": [{
        "bucket": "pl-test",
        "href": "/api/service/v2/services/cloud/targets/target-id1",
        "id": "target-id1",
        "key": true,
        "location": "https://objectstorage.us-ashburn-1.oraclecloud.com",
        "name": "oci-ashburn",
        "online": true,
        "proxy_host": "",
        "proxy_on": false,
        "proxy_password": false,
        "proxy_user": "",
        "tenancy": "ocid1.tenancy.oc1..tenancy-id",
        "user": "ocid1.user.oc1..user-id"
    },{
        "bucket": "pl-test2",
        "href": "/api/service/v2/services/cloud/targets/target-id2",
        "id": "target-id2",
        "key": true,
        "location": "https://objectstorage.us-phoenix-1.oraclecloud.com",
        "name": "oci-phoenix",
        "online": true,
        "proxy_host": "www-proxy.example.com:80",
        "proxy_on": true,
        "proxy_password": false,
        "proxy_user": "",
        "tenancy": "ocid1.tenancy.oc1..tenancy-id",
        "user": "ocid1.user.oc1..user-id"
    }]
}

The following example lists the specified target:

GET /api/service/v2/services/cloud/targets/target-id HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

Create a Target

The following parameters are required to create a cloud target.

Parameter Description

key

An Oracle Cloud Infrastructure account user key for user-id

tenancy-id

An Oracle Cloud Infrastructure account tenancy name OCID

user-id

Your Oracle Cloud Infrastructure account user name OCID

The following example creates a target.

Example Request:

POST /api/service/v2/services/cloud/targets HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=

{
    "name": "oci4",
    "location": "https://objectstorage.us-phoenix-1.oraclecloud.com",
    "user": "ocid1.user.oc1..user-id",
    "bucket": "test-bucket3",
    "tenancy": "ocid1.tenancy.oc1..tenancy-id",
    "key": "key",
    "proxy_on": false,
    "readlimit": -1,
    "writelimit": -1
}

Example Result:

HTTP/1.1 201 Created
Date: Wed, 24 Jul 2019 21:14:39 GMT
Content-Length: 568
X-Zfssa-Service-Api: 2.0
Location: /api/service/v2/services/cloud/targets/target-id
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8

{
    "target": {
        "bucket": "test-bucket3",
        "href": "/api/service/v2/services/cloud/targets/target-id",
        "id": "target-id",
        "key": true,
        "location": "https://objectstorage.us-phoenix-1.oraclecloud.com",
        "name": "oci4",
        "proxy_on": false,
        "readlimit": -1,
        "state": "offline",
        "tenancy": "ocid1.tenancy.oc1..tenancy-id",
        "user": "ocid1.user.oc1..user-id",
        "writelimit": -1
    }
}

Modify a Target

The following table shows the properties that can be modified for a cloud target.

Property Description

name

The name for this cloud target, which must be unique on each Oracle ZFS Storage Appliance

proxy_on

If true, use a proxy for system communications with the internet.

If the value of proxy_on is true, then you must provide a value for proxy_host.

proxy_host

The proxy hostname and port number

proxy_password

Optional. The proxy password

proxy_user

Optional. The proxy username

readlimit

Optional. The maximum rate in bytes per second that data will be read from the cloud target. This value is used when a cloud backup is restored from the cloud. For example, a value of 4194304 limits the read rate from the cloud target to 4 megabytes per second. The value -1 means I/O is not limited.

writelimit

Optional. The maximum rate in bytes per second that data will be written to the cloud target. This value is used when a cloud snapshot is uploaded to a cloud target. For example, a value of 5242880 limits the write rate to the cloud target to 5 megabytes per second. The value -1 means I/O is not limited.

Example Request:

PUT /api/service/v2/services/cloud/targets/target-id HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
User-Agent: curl/7.54.0
Accept: */*
Content-Type: application/json
Content-Length: 19
{
    "proxy_on": true,
    "proxy_host": "www-proxy.example.com:80",
    "readlimit": 4194304,
    "writelimit": 5242880
}

Delete a Target

Before you delete a target, perform the following checks:

  • Check whether a backup to this target is in progress. See List Jobs.

  • Determine whether this target has backups. Use the target filter as shown in List Cloud Backups to list backups that are stored on this target.

The following example removes the specified cloud target from service.

Example Request:

DELETE /api/service/v2/services/cloud/targets/target-id HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

Example Result:

HTTP/1.1 204 No Content
Date: Wed, 24 Jul 2019 21:20:27 GMT
X-Content-Type-Options: nosniff
X-Zfssa-Service-Api: 2.0
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8

List Cloud Backups

Use the following query to list all completed backups of any format, with newer backups listed first. To get information about backups in progress, see List Jobs.

Example Request:

GET /api/service/v2/services/cloud/backups HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

Example Result:

In this example, the first backup listed is the child of the second backup listed. The value of parent of the first backup is the same as the value of dataset of the second backup (app-data-fullsnap), and the value of parent of the second backup is null. A child backup will be the same format as the parent. In this example, both child and parent backups are in tar format. 

HTTP/1.1 200 OK
Date: Wed, 22 Jan 2020 21:22:40 GMT
X-Zfssa-Service-Api: 2.0
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked

{
    "backups": [{
        "target": "target-id2",
        "parent": "app-data-fullsnap",
        "started": "2020-01-06T20:03:32Z",
        "completed": "2020-01-06T20:04:36Z",
        "id": "backup-id2",
        "source": "cloudsnap0",
        "href": "/api/service/v2/services/cloud/backups/tar/backup-id2/target-id2",
        "tier": "standard",
        "dataset": "p1/local/default/app-data@app-data-incsnap",
        "format": "tar",
        "size": 3224982536.0
    },{
        "target": "target-id1",
        "parent": "",
        "started": "2020-01-06T20:01:16Z",
        "completed": "2020-01-06T20:01:17Z",
        "id": "backup-id1",
        "source": "cloudsnap0",
        "href": "/api/service/v2/services/cloud/backups/tar/backup-id1/target-id1",
        "tier": "standard",
        "dataset": "p1/local/default/app-data@app-data-fullsnap",
        "format": "tar",
        "size": 2149988056.0
    }]
}

Use the following request to list the specified backup:

GET /api/service/v2/services/cloud/backups/format/backup-id/target-id HTTP/1.1

List Cloud Backups Query Parameters

The following query parameters are supported for filtering the list of cloud backups. All parameters can be used in the same query. Use an AND operation (&) between the query parameters as shown in the examples that follow the table.

Table 9-2 Query Parameters for Listing Cloud Backups

Property Description

start

The value of start is one of the following:

  • The backup index. Values for this index are from 0 to one less than the value of the entries property in the backups section of the request shown in List Cloud Service Properties.

    Lists the backup selected by the specified index and the oldest backups that were created after the specified backup was created.

  • A time in format %Y-%m-%dT%H:%M:%SZ. This is the same format that is used for the values of the started and completed properties. This time can be any real time up to the current time. For example, 2019-09-00T00:00:00Z is not a real time.

    Lists the oldest backups that were created on or after the specified time.

end

The value of end is a time in format %Y-%m-%dT%H:%M:%SZ. This is the same format that is used for the values of the started and completed properties. This time can be any real time up to the current time. For example, 2019-09-00T00:00:00Z is not a real time.

Lists the newest backups that were created on or before the specified time.

limit

Lists no more than the specified number of backups. The limit parameter has no default value.

target

The value of the target property. Lists the newest backups on that target.

source

The value of the source property. Lists the newest backups on that source.

dataset

The value of the dataset property before the @. For example, for dataset p1/local/default/app-data@app-data-incsnap, specify p1/local/default/app-data or app-data.

Lists the newest backups in the specified dataset.

Note - A request for a dataset backup lists all backups of all datasets that have names that contain the requested dataset name. For example, a request for backups of p1/local/default/app-data@app-data-incsnap will also return backups of datasets named app-data-incsnap, app-data-incsnap-1, and myproj-app-data-incsnap.

format

The value of the format property, either zfs or tar. Lists the newest backups in the specified backup format.

The following example lists the oldest backups starting from the backup with index number 2000. If the value of the entries property in the backups section of the cloud service properties list is 2865, then the following example shows 865 backups: backup 2000 through backup 2864. 

GET /api/service/v2/services/cloud/backups?start=2000

The following example lists only the backup with index number 2000:

GET /api/service/v2/services/cloud/backups?start=2000&limit=1

The following example lists the 500 oldest backups that were created on or after the specified time:

GET /api/service/v2/services/cloud/backups?start=2019-07-12T00:00:00Z&limit=500

The following example lists the 500 newest backups that were created on or before the specified time:

GET /api/service/v2/services/cloud/backups?end=2019-07-12T00:00:00Z&limit=500

The following example lists all backups that were created on or after the specified start time but no later than the specified end time: 

GET /api/service/v2/services/cloud/backups?start=2019-07-11T00:00:00Z&end=2019-07-12T00:00:00Z

The following example lists the newest backups of any dataset with app-data in the name in the tar backup format: 

GET /api/service/v2/services/cloud/backups?dataset=app-data&format=tar

The following example lists the newest backups of any dataset with app-data in the name on the target-id target: 

GET /api/service/v2/services/cloud/backups?dataset=app-data&target=target-id

The following example lists the newest backups of any dataset with app-data in the name on the target-id target that have the cloudsnap0 source: 

GET /api/service/v2/services/cloud/backups?dataset=app-data&target=target-id&source=cloudsnap0

Delete a Cloud Backup

Before you delete a cloud backup, perform the following checks:

  • Check whether a restore of this backup is in progress. See List Jobs.

  • Determine whether this backup has children. Children of this backup have a parent value that is the same as the dataset value of the backup that you want to delete. See List Cloud Backups. To delete a backup that has children backups, specify the force option.

The following example submits a job request to delete the specified backup on the specified target from Oracle Cloud Infrastructure Object Storage. An appliance can operate on any backup on any target that the appliance can access, even if that backup was created on a different appliance.

Compare this operation with Delete a Snapshot Backup, which shows how to delete a share snapshot backup on the appliance.

Example Request:

In the following request, backup backup-id has no children: 

DELETE /api/service/v2/services/cloud/backups/format/backup-id/target-id HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

In the following request, backup backup-id has children backups and the force option is applied: 

DELETE /api/service/v2/services/cloud/backups/format/backup-id/target-id?force=true HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

Example Result:

{
    "action": "job-id"
}

To view the progress of the cloud backup deletion, use List Jobs to view the job with the above job-id.

Restore a Cloud Backup

A cloud backup can be restored on any appliance that has access to that cloud target. The backup can be restored as a newly cloned share on Oracle ZFS Storage Appliance, or the backup can be restored into an existing share.

When a cloud backup with the zfs format contains a snapshot with a retention hold, that hold is preserved when the cloud backup is restored.

The following example submits a job request to restore the specified backup. Specify the pool and project where you want the backup restored. If you want to restore to a new share, specify a name for the new share. If you want to restore to an existing share, specify the name of the share, and specify useshare as true. By default, the value of useshare is false.

To view the progress of the restoration, use List Jobs to view the job with the returned job-id.

If the readlimit property is set for the target, no more than readlimit bytes per second are read from the target. See Create a Target.

Example Request:

In the following request, backup restore6 is a new share: 

POST /api/service/v2/services/cloud/backups/format/backup-id/target-id/restore HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*
Content-Length: 55

{
    "pool":"p1",
    "project":"default",
    "share": "restore6"
}

In the following request, backup restore6 is an existing share on Oracle ZFS Storage Appliance, and the useshare flag is set to true: 

POST /api/service/v2/services/cloud/backups/format/backup-id/target-id/restore HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*
Content-Length: 55

{
    "pool":"p1",
    "project":"default",
    "share": "restore6",
    "useshare": true
}

Example Result:

{
    "action": "job-id"
}

List Jobs

The following example lists all running jobs and recently completed jobs, with the newest job listed first.

Example Request:

GET /api/service/v2/services/cloud/jobs HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

Example Result:

In this example, two backup jobs are saving two different backups to the same target.

HTTP/1.1 200 OK
Date: Wed, 22 Jan 2020 21:37:52 GMT
Content-Length: 983
X-Zfssa-Service-Api: 2.0
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8

{
    "jobs": [{
        "href": "/api/service/v2/services/cloud/jobs/job-id2",
        "op": "backup",
        "target": "target-id",
        "targetName": "oci-ashburn",
        "created": "2020-02-06T16:52:42Z",
        "updated": "2020-02-06T16:52:48Z",
        "id": "job-id2",
        "status": "in-progress",
        "rate": 10002432,
        "transferred": 80019456,
        "estimated_size": 43088792088,
        "dataset": "p1/local/default/f-1",
        "backup": "backup-id2",
        "snapshot": "snap3",
        "format": "tar",
        "details": "uploading backup to zfs/backups/tar/backup-id2/000000001"
    },{
        "href": "/api/service/v2/services/cloud/jobs/job-id1",
        "op": "backup",
        "target": "target-id",
        "targetName": "oci-ashburn",
        "created": "2020-02-06T16:52:28Z",
        "updated": "2020-02-06T16:52:48Z",
        "id": "job-id1",
        "status": "in-progress",
        "rate": 1942,
        "transferred": 3884,
        "estimated_size": 0,
        "dataset": "p1/local/default/f-1",
        "backup": "backup-id1",
        "snapshot": "snap2",
        "format": "zfs",
        "details": "uploading backup to zfs/backups/zfs/backup-id1/000000001"
    }]
}

The following example lists the specified job:

GET /api/service/v2/services/cloud/jobs/job-id2 HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

List Cloud Backup Jobs Query Parameters

The start and limit query parameters are supported for filtering the list of cloud backup jobs.

  • The value of the start parameter is the job index. Values for this index are from 0 to one less than the value of the entries property in the jobs section of the request shown in List Cloud Service Properties.

  • The value of the limit parameter is the maximum number of jobs to list.

Both parameters can be used in the same query. Use an AND operation (&) between the query parameters as shown in the following examples.

The following example lists the 100 newest running jobs and recently completed jobs, with the newest job listed first.

GET /api/service/v2/services/cloud/jobs?limit=100

The following example lists only the oldest running or recently completed job.

GET /api/service/v2/services/cloud/jobs?start=0&limit=1

The following example lists all running jobs and recently completed jobs with a job index number equal to or greater than 4, with the newest job listed first.

GET /api/service/v2/services/cloud/jobs?start=4

Cancel or Restart a Job

The following example cancels the specified cloud service job.

Example Request:

PUT /api/service/v2/services/cloud/jobs/job-id/cancel HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

Example Result:

HTTP/1.1 202 Accepted
Date: Wed, 24 Jul 2019 21:50:29 GMT
Content-Length: 0
X-Zfssa-Service-Api: 2.0
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8

The following example restarts the specified cloud service job.

Example Request:

PUT /api/service/v2/services/cloud/jobs/job-id/restart HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
User-Agent: curl/7.54.0
Accept: */*

Example Result:

HTTP/1.1 202 Accepted
Date: Wed, 24 Jul 2019 21:51:08 GMT
Content-Length: 0
X-Zfssa-Service-Api: 2.0
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8