Policies

This chapter describes details about the resource “policies”.

Policies define how frequently a workload is backed up and how long you can keep a copy in the backup repository. Note that they don’t include either the source or the destination for the backup.

Creating a Policy

There are two different ways in which schedule can be set in the API, though both follow cron format. In the first option, individual fields such as “minute” and “hour” can be set explicitly. The second option is to pass entire cron spec as a single string. The latter takes precedence if both are set.

Here are both examples.

Setting individual values explicitly:

POST /api/v1/policies

{
    "name": "testpolicy",
    "timezone": "America/New_York",
    "schedules": [
        {
            "retainDays": 30,
            "schedule": {
                "minute": "0",
                "hour": "3",
                "dayOfMonth": "1",
                "month": "1",
                "dayOfWeek": "*"
            }
        }
    ]
}

201 CREATED

...

Setting Cron spec:

POST /api/v1/policies

{
    "name": "testpolicy",
    "timezone": "America/New_York",
    "schedules": [
        {
            "retainDays": 30,
            "schedule": {
                "cronSpec": "30 10 * * *",
            }
        }
    ]
}

201 CREATED

...

Notes

  • “schedule” is in crontab format with few exceptions. Check crontab man page or cron for more details.

    Currently, cron spec with explicit value in “hours” field doesn’t work. For example, the spec 30 10 * * * doesn’t do anything. But both 30 * * * * and 30 */1 * * * work.

    Similarly, we do not support “*” in minutes field.

  • “timezone” is optional. If not provided, “UTC” is used. When provided, the value should be in valid timezone format.

  • “retainDays” is required.

Get/List

GET /api/v1/policies

GET /api/v1/policies/<ID>

Response will contain “status” field whose schema is described. Note that “status” may not appear immediately so client will need to poll until it sees the field.

Status

The corresponding policy resource will have a “status” field updated as per the following schema:

suspended

Boolean

Updating a Policy

PATCH /api/v1/policies

Notes

  • Any changes to a policy would only take effect on future runs. Existing backups will continue to follow the retention settings present when they were created.

Pausing and resuming a Policy

POST /api/v1/policies/<ID>/action/suspend

POST /api/v1/policies/<ID>/action/resume

Notes

  • Sending any of these requests will update the suspended field in status.

Deleting a Policy

DELETE /api/v1/policies/<ID>

Notes

  • Deletion would fail if the policy is currently in use. For example, if the policy is part of a cluster backup definition, it cannot be deleted.